Speedo user manual

  1. The .jdo files
  2. The Speedo ant task
  3. The PersistenceManagerFactory properties
  4. The configuration files
  5. The logging

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

A extension named sql-name permits the user to specify the table name where the persistent class is stored.

<class name="A">
    <extension vendor-name="speedo" key="sql-name" value="TABLE_A">
</class>

If this extension is not specified, by default the table name is equal to the name of the class (whithout the package name).

The primitive field extension

An extension named sql-name permits to specify the name of the column in table name where the persistent class is stored.

<field name="f1">
    <extension vendor-name="speedo" key="sql-name" value="F1_COL">
</field>

If this extension is not specified, by default the column name is equal to the name of the field.

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.

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

Example 3: The relation is One-Many 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"/>
    </collection>
</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.

<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"/>
    </collection>
</field>


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">
        <extension vendor-name="speedo" key="reverse-field" value="refToB"/>
        ...
    </field>
    ...
</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>


The Speedo ant task

under construction ...

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 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"
org.objectweb.speedo.managed This property indicates this the transactionnal environnement is managed by a container. It the value is "false" then when the user starts a transaction then a local transaction is started. If the value is "true" it is the role of the container to manage the transaction throught an XA resource provided by the connection provider (Jdbc driver, JCA connector, ...). The default value is "false" Speedo N true or false
org.objectweb.speedo.managed 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.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
javax.jdo.option.ConnectionFactoryName The JCA connection mode is TEMPORALY not supported.
javax.jdo.option.RestoreValues This option is not supported. The value is "false"
javax.jdo.option.IgnoreCache This option is not supported. The 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"
javax.jdo.option.Multithreaded This option is not supported. The value is "true"


The configuration files

There are several configuration files provided in Speedo. Indeed Speedo used several objectweb project/framework. In general the most of the Speedo users must only manage two files: speedoc.properties and speedo.properties. But this section describes in the second part the other configuration files.

The configuration file: speedoc.properties

This file is the configuration file for the JDO Instances enhancer. It defines properties which are read before the process begins. If the user redefines properties with the command line (or in the ant task), these are taking in account.
Property name Description Value Required
projectName is the project name of your application. myApplicationName No
mapperName A mapper identifies a data source type. The 'rdb' mapper represents the Relationnal Data base sources. There are sub mappers for each data base vendor (oracle, mysql, postgres, sapdb, ...) For more information see the Jorm project "rdb.postgres"
or "rdb.oracle"
or ...
Yes
keepsrc Indicates if the generated sources must be kept. true No
verbose Verbose mode false No
failsonerror Indicates if the genetation must fail at the first error true No
verbose Verbose mode false No
output The directory where the enhanced classes and generated files are written build No
intut The directory containg the .java, .jdo and the jorm files (.pd) src No


The configuration file: speedo.properties

This file contains the properties of the PersistenceManagerFactory. This permits to the user to define its property in this file ant to load it into a java.util.Properties instance as this following example:

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

For 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 in 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 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 configuration file: jormcOpts.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.

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