Speedo user manual

 FinalLogo.jpg
 FinalLogo.jpg
  1. The .jdo files
  2. Configuration of the data source access
  3. The identifier of persistent objects
  4. The Speedo ant task
  5. The PersistenceManagerFactory properties
  6. The configuration files
  7. The mappers matching to the persistent support
  8. The logging
  9. Supported types
  10. Application servers integration

Back to the Speedo documentation




The .jdo files

The .jdo files describes which are the persistent classes. In the current version of Speedo,the user is required to specify which are the persistent fields for each class. For each class and each field, the user can specify (optional) extensions for Speedo. Extensions allow the user to choose a mapping of the persistent object into a relational database.

The class extension

The primitive field extension


The reference field extension

A reference field is a field which references a Persistent class and not a Collection/Set/... of ... Speedo allows the user to specify whether foreign key values reference tuples stored in the target table or the source table:

For more information about the values corresponding to the key "source-foreign-keys" and "target-foreign-keys" see the section foreign keys declaraction

The collection field extension

A "collection" field is a field which references several persistent classes. Speedo supports several types of structure (java.util.Collection, java.util.Set, java.util.List, []...). Depending of the type of relation ( One-Many, Many-Many) a join table can be specified. The join table is optional for a One-Many relation; a foreign key can indeed be defined in the table of the referenced persistent class. In the opposite, a join table is needed for a Many-Many relation. The following examples go through the supported cases:

Example 1:

The user does not specify any information about the mapping. By default the relation is stored into a join table. The table and the columns names are chosen by Speedo.

<field name="collectionOfB" persistence-modifier="persistent">
    <collection element-type="B"/>
</field>

Example 2:

The relation is One-Many and there is no join table. The "source-foreign-keys" extension defines the name of the foreign key column in the table of the referenced persistent class.

<class name="A">
    <field name="collectionOfB" persistence-modifier="persistent">
        <collection element-type="B"/>
        <extension vendor-name="speedo" key="source-foreign-keys" value="PKA=FKA"/>
        <extension vendor-name="speedo" key="reverse-field" value="thefA"/>
    </field>
</class>
...
<class name="B">
    <field name="thefA" persistence-modifier="persistent">
        <collection element-type="B"/>
    </field>
</class>

Example 3:

The relation is Many (no reverse field exists) and there is a join table. The key "join-table" defines the name of the join table. If it is not specified the default table name is defined by the concatenation of the short class name (without package name) of the source class, with the name of the collection field. The "source-foreign-keys" and "target-foreign-keys" extensions define the columns name of the join table.

<field name="collectionOfB" persistence-modifier="persistent">
    <collection element-type="B"/>
    <extension vendor-name="speedo" key="join-table" value="A_TO_B"/>
    <extension vendor-name="speedo" key="source-foreign-keys" value="PKA=FKA"/>
    <extension vendor-name="speedo" key="target-foreign-keys" value="PKB=FKB"/>
</field>

Example 4:

The relation is Many-Many. The key "join-table" defines the name of the join table. If it is not specified the default table name is defined by the concatenation of the short class name (without package name) of the source class, with the name of the collection field. The "source-foreign-keys" and "target-foreign-keys" extensions define the columns name of the join table.

<class name="A">
    <field name="collectionOfB" persistence-modifier="persistent">
        <collection element-type="B"/>
        <extension vendor-name="speedo" key="join-table" value="A_TO_B"/>
        <extension vendor-name="speedo" key="source-foreign-keys" value="PKA=FKA"/>
        <extension vendor-name="speedo" key="target-foreign-keys" value="PKB=FKB"/>
        <extension vendor-name="speedo" key="reverse-field" value="collectionOfA"/>
    </field>
</class>
...
<class name="B">
    <field name="collectionOfA" persistence-modifier="persistent">
        <collection element-type="A"/>
    </field>
</class>

The map field extension

A "map" field is always store into an intermediate table which the name can be defined by the 'join-table' extension.

The example shows a map referenced by the A class ('mapOfBIndexedByString' field). The key of the map is a String value which the column name can be specified by the 'index-sql-name' extension'. The value type of the map is the persistent class B which the mapping (column name) of the reference can be specified by the 'target-foreign-keys' extension. Finally the map identifier is always the identifier of the reference holder (the 'A' class). The column name of the map identifier can be specified by the extension 'source-foreign-keys'.

<class name="A">
    <field name="mapOfBIndexedByString" persistence-modifier="persistent">
        <map key-type="java.lang.String" value-type="B"/>
        <extension vendor-name="speedo" key="join-table" value="MAP_TABLE_NAME"/>
        <extension vendor-name="speedo" key="source-foreign-keys" value="PKA=FKA"/>
        <extension vendor-name="speedo" key="target-foreign-keys" value="PKB=FKB"/>
        <extension vendor-name="speedo" key="index-sql-name" value="KEY_COL_NAME"/>
        <extension vendor-name="speedo" key="index-sql-type" value="VARCHAR(40)"/>
    </field>
</class>

The example shows a map referenced by the 'A' class ('mapOfStringIndexedByLong' field). The key of the map is a Long value which the column name can be specified by the 'index-sql_name' extension'. The value type of the map is a String which the column name) can be specified by the 'element-sql-name' extension. Finally the map identifier is always the identifier of the reference holder (the 'A' class). The column name of the map identifier can be specified by the extension 'source-foreign-keys'.

<class name="A">
    <field name="mapOfStringIndexedByLong" persistence-modifier="persistent">
        <map key-type="java.lang.Long" value-type="java.lang.String"/>
        <extension vendor-name="speedo" key="join-table" value="MAP_TABLE_NAME"/>
        <extension vendor-name="speedo" key="source-foreign-keys" value="PKA=FKA"/>
        <extension vendor-name="speedo" key="element-sql-name" value="VALUE_COL_NAME"/>
        <extension vendor-name="speedo" key="element-sql-type" value="VARCHAR(34)"/>
        <extension vendor-name="speedo" key="index-sql-name" value="KEY_COL_NAME"/>
        <extension vendor-name="speedo" key="index-sql-type" value="INT8"/>
    </field>
</class>


The reverse field extension

For each field referencing one or several persistent classes, it is possible to specify the reverse field of the relation if it exists. This information is very important: useless I/O are avoided based on the reverse field declaration The fact that two fields are opposite depends on the semantic of the fields.

<class name="A">
    <field name="refToB">
        <extension vendor-name="speedo" key="reverse-field" value="refToA"/>
        ...
    </field>
    ...
</class>
<class name="B">
    <field name="refToA"/>
    ...
</class>


The foreign keys declaraction

A foreign key declaraction (source or target) defines the column names of the foreign in according to the primary key structure. A foreign key declaraction is comma list of equality between the name of a primary key column and the name of the foreign key column.

Example 1:

The identifier of the referenced object (A) consists of a single column named "pka" and the column name of the foreign key column is named "fka".

<field name="refToB">
    <extension vendor-name="speedo" key="target-foreign-keys" value="pka=fka"/>
</field>

Example 2:

The identifier of the referenced object (A) consists of two fields (FIRST_NAME, LAST_NAME). The corresponding names of the composite foreign key are (A_FN, A_LN).

<field name="refToB">
    <extension vendor-name="speedo"
        key="target-foreign-keys"
        value="FIRST_NAME=A_FN,LAST_NAME=A_LN"/>
</field>


Configuration of the data source access

In the speedo.properties files, there is a data access section. In this section you must choose between the use of a jdbc driver directly or a connection factory.

The identifier of the persistent objects

Speedo supports 4 types of identifiers:

All the extension concerning the identifier must be done on the class tag in the .jdo files.

The Speedo ant task

Description

Enhance an application. Currently this task does not support to classes already enhanced. Then you must removed the .class file of the persistent classes each times that use this task.

Parameters

Attribute Description Required
confFile This is the configuration file of the Speedo enhancer. Usualy this file is the speedoc.properties provided in the distribution No
output Is the location of the .class of the user application. This is also the location where the Speedo files produced for the user persistent class, is written. Yes
src Is the location of the source of the user application. Yes
projectName Is the name of the user project. If the user provides jorm persistent descriptor (Exotic legacy mapping case) like .pd files, the projectname must be specified and matching to the project name used in the .pd files. No
mapperName Is the name of the mapper where the persistent classes is stored. For more information about mappers see the mapper section. This parameter is needed if the confFile does not contains the properties mapperName. No
classpathref Is the classpath containing Speedo, the user classes, and the configuration files(etc directory). No
logPropFile Is the logging configuration file. It permits to choose another monolog configuration file than the one provided in the etc directory No
failsonerror indicates if the Speedo enhancer must stop after the first error or try to continue. The default value is true. No

Parameters specified as nested elements


Examples

The following examples comes from the examples:

<property name="src" value="${basedir}/src"/>
<property name="build" value="${basedir}/build"/>
<property name="speedoDist" value="${basedir}/../.."/>
...
<path id="classpath">
    <pathelement location="${speedoDist}/etc"/>
    <pathelement location="${build}"/>
    <fileset dir="${speedoDist}">
        <include name="speedo.jar"/>
        <include name="lib/log/log4j.jar"/>
        <include name="lib/jdbc/postgres_jdbc2.jar"/>
    </fileset>
</path>
...
<taskdef name ="speedo"
    classname="org.objectweb.speedo.ant.AntSpeedo"
    classpathref="classpath" />
...
<target="generation">
    <delete dir="${build}"/>
    <mkdir dir="${build}"/>
    <javac srcdir="${src}" destdir="${build}" debug="on">
        <classpath refid="classpath"/>
        <include name="**/*.java"/>
    </javac>
    <speedo
        confFile="${speedoDist}/etc/speedoc.properties"
        output="${build}"
        src="${src}"
        projectName="invoice"
        classpathref="classpath"/>


The PersistenceManagerFactory properties

This section descibes the propeties of the PersistencManagerFactory. Some properties are not defined in the JDO specification and are specific to Speedo. All of these properties are grouped in the Speedo.properties configuration file.
Property name Description JDO / Speedo Req Value
javax.jdo.PersistenceManagerFactoryClass This property defines the name of the PersistenceManagerFactory class provided by Speddo. This value cannot be changed. JDO Y "org.objectweb.speedo.Speedo"
javax.jdo.option.DriverClassName This property defines the name of the jdbc driver class JDO Y "org.postgresql.Driver"
or "com.mysql.jdbc.Driver"
or ...
org.objectweb.speedo.mapperName This property defines the name of mapper which must be used with the database. For more information see the mappers section Speedo Y "rdb.postgres"
or "rdb.mysql"
or ...
javax.jdo.option.ConnectionURL This property defines the url of the database. JDO Y "jdbc:postgresql:speedoTest"
javax.jdo.option.ConnectionUserName This property defines the user name authorized to access the database. JDO Y "smith"
javax.jdo.option.ConnectionPassword This property defines the password corresponding to user name authorized to access the database. JDO Y "myPassword"
javax.jdo.option.ConnectionFactoryName This property is the jndi name of a registered connection factory. JDO Y "myConnFactJndiNAme"
org.objectweb.speedo.jca.TMName This property is the jndi name of a registered transaction manager. For more information see the section about the application server integration Speedo Required when is integrated into an application server "javax.transaction.TransactionManger"
javax.jdo.option.IgnoreCache Indicates if queries and extends must ingore the instance modified in memory and not yet committed into the support. The default value is 'false' JDO N 'true' or 'false'
javax.jdo.option.Multithreaded Indicates if several threads can manipulate a same PersistenceManager instance in same time (concurrency). The default value is 'false' JDO N 'true' or 'false'
org.objectweb.speedo.query.prefetch This property permits to desactive the data prefetching on queries. The default value is 'on'. Speedo N 'on' or 'off'
org.objectweb.speedo.mappingStructure This property specifies the behavior of Speedo on the mapping structures (ex SQL tables). The possible behavior are the following:
  • DO_NOTHING : nothing is done. Then the mapping structures already exist at the Speedo starting.
  • CREATE_IF_REQUIRED : The mapping structures are created if they are not already present (default).
  • FORCE_CREATE: The mapping structures are removed (if they already exist), and and created.
  • DELETE_DATA: The data present in the mapping structure are removed. Of course if the mapping structure do not exist, they are created.
The default value is CREATE_IF_REQUIRED.
Speedo N DO_NOTHING
or CREATE_IF_REQUIRED
or FORCE_CREATE
or DELETE_DATA
org.objectweb.speedo.cache.size This property permits to manage the size of the cache of memory instances. The default value is "nolimit", that means that the cache have not a maximum size. Speedo N "nolimit" or a positive integer value
org.objectweb.speedo.cache.autoCleanSize This property defines the number of cache entry to free when the cache of memory instance is full. The value can be a percent of the maximal cache size (ex: "10%") or an absolute value (ex: "456"). The default value is a percent: "7%". Speedo N a positive integer value between 0 and the cache size or a percent (ex: 12%)
org.objectweb.speedo.connection.pool.min This property permits to manage the minimal size of the pool of connection when Speedo uses directly a JDBC driver. The default value is 0. Speedo N a positive integer value
org.objectweb.speedo.connection.pool.max This property permits to manage the maximal size of the pool of connection when Speedo uses directly a JDBC driver. The default value is 20. Speedo N a positive integer value
org.objectweb.speedo.peristencemanager.pool.min This property permits to manage the minimal size of the pool of PersistenceManager. The default value is 0. Speedo N a positive integer value
org.objectweb.speedo.peristencemanager.pool.max This property permits to manage the maximal size of the pool of PersistenceManager. The default value is "nolimit". Speedo N "nolimit" or a positive integer value
org.objectweb.speedo.query.pool.min This property permits to manage the minimal size of the pool of query instances. The default value is 0. Speedo N a positive integer value
org.objectweb.speedo.query.pool.max This property permits to manage the maximal size of the pool of query instances. The default value is "nolimit". Speedo N "nolimit" or a positive integer value
org.objectweb.speedo.query.compiledquery.min This property permits to manage the minimal size of the pool of compiled query instances. The default value is 0. Speedo N a positive integer value
org.objectweb.speedo.query.compiledquery.max This property permits to manage the maximal size of the pool of compiled query instances. The default value is "nolimit". Speedo N "nolimit" or a positive integer value
org.objectweb.speedo.txStatistic This property indicates if Speedo must build statistics about the transactions. Speedo N 'true' or 'false'
javax.jdo.option.RestoreValues The management of this option is not supported. The only supported value is "true"
javax.jdo.option.RetainValues The management of this option is not supported. The only supported value is "true"
javax.jdo.option.NontransactionalRead This option is not supported. The value is "false"
javax.jdo.option.NontransactionalWrite This option is not supported. The value is "false"


The configuration files

There are several configuration files provided in Speedo. Indeed Speedo used several objectweb projects/frameworks. All these configuration files must be availlable at the root of the classpath. In general most of the Speedo users have to manage only one files: speedo.properties. But this section describes in the second part, the other configuration files.

The configuration file: speedo.properties

This file is used at enhancement time in order to generate the access to the support (SQL request for example). Then for the enhancement you have to define at least the mapper name property.

This file is used at runtime for the properties of the PersistenceManagerFactory. Therfore this properties file can be loaded into a java.util.Properties instance in order to fetch a PersistanceManagerFactory as this following example:

Properties p = new Properties();
p.load(new FileInputStream("speedo.properties"));
PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory(p);

The file must be availlable at the root of the classpath during the enhancement and the runtime. For more information about the propeties of the PersistanceManagerFactory see the section The PersistenceManagerFactory properties of this documentation.

The configuration file: monolog.properties

This file permits to configure logging. It must be availlable at the root of the classpath during the enhancement and the runtime.For more information see the section The logging in this documentation.

The configuration file: spy.properties

This file is the configuration file of the tool P6Spy permiting to log the SQL call throught the jdbc driver. To active this logging the user must

The librairies of the p6spy tool are already included in the speedo.jar.


The configuration file: julia.cfg

Speedo is written in respect with the component model defined in Objectweb: Fractal. Speedo uses Julia as implementation of this model. The julia.cfg file is the configuration file of Julia. It must be availlable in the classpath (root position) during the enhancement and the runtime.

The configuration file: jorm.properties

To manage the I/O with the support Speedo uses Jorm. The jorm.properties file is the jorm configuration file. It defines the supported mapper. It must be availlable in the classpath during the enhancement and the runtime.

The mappers matching to the persistent supports

The persistent objects are stored in a persistence support. Thanks to Jorm, it is possible to store persistent objects into various types of persistent support. Each persistent support type is represented by a mapper. For a relationnal database the mapper is "rdb". Due to the lack of conformance of JDBC drivers, Jorm provides adapters to the JDBC specification for some database. Then depending on the used relationnal database the mapper name is different. The following table shows the supported persistent support and the mapper names associated:

Persistent support Mapper name Status
Oracle (<=8.x) rdb.oracle8 OK
Oracle (>=9.x) rdb.oracle OK
PostgresSQL (>= 7.2) rdb.postgres OK
Mysql rdb.mysql OK
MS Sql Server rdb.sqlserver OK
Firebird rdb.firebird Testing
McKoi rdb.mckoi OK
Sap DB rdb.sapdb Testing
Sybase rdb.sybase Testing
Driver conform to JDBC specification rdb OK

For more information about the adapter contact see the Jorm framework. It is easy to write an adapter for a new relationnal database.

The logging

As other objectweb product, Speedo uses a logging API in order to be independant from an implementation. Monolog provides wrappers to the usual logging system like log4j or the logging systems provided with the jdk1.4. There is a logging configuration file which does not depends on the logging system used under monolog. This file is "monolog.properties". Speedo uses Monolog in the automatic mode:

For more information about the Monolog and its configuration file see the monolog documentation

Supported types

Speedo supports the following list of type. A supported type means that a persistent field can be declared with one of these types:


Application servers integration

Speedo can be integrated into application servers as a resource adapter (JCA Connector SUN specification). Then to use Speedo into an application server, you have to use the rar file provided in the Speedo binary distribution.
To use speedo in an application server with transactions demarcated by the EJB container, the transaction manager instance (implements javax.transaction.TransactionManager) MUST be registered into JNDI. The JNDI name can be assigned to the property org.objectweb.speedo.jca.TMName in the 'speedo.properties' configuration file. If no name is specified, several attempts are done with classical jndi names used in some application server:

Application Server JNDI name of TransactionManager instance
JOnAS javax.transaction.UserTransaction
WebLogic javax.transaction.TransactionManager
Orion java:comp/UserTransaction
JBoss java:/TransactionManager


JOnAS case: In case of you want to integrate Speedo into JOnAS, you have to use compatible version. Indeed JOnAS and Speedo uses common frameworks (Jorm, Medor, Perseus) and the some classes are already availlable in the server. In addition a small rar file dedicated to JOnAS is aslo provided into the speedo distribution.