Speedo user manual: Speedo configuration

 FinalLogo.jpg
 FinalLogo.jpg
  1. Configuring of the data source access
  2. Configuring the concurrency management
  3. Configuring the caching management
  4. Configuring the data prefetching
  5. J2EE Application servers integration
  6. The speedo.properties file
  7. The Eclipse plugin for editing speedo.properties
  8. The other configuration file
  9. Mappers, Adapters and persistence support

Back to the Speedo documentation




  1. Configuring of the data source access
  2. The speedo-jdo.properties file contains a data access section. In this section, the user can choose between the use of a JDBC driver directly or the use of a connection factory.

    In both case it is adviced to specify the type of database that you want use, by defining the org.objectweb.speedo.mapperName property.

  3. Configure the concurrency Management
  4. Speedo provides two transaction managements. The first mode lets Speedo managing the concurrency. It supports pessimistic or optimistic locking. The second mode delegates the concurrency management to the database.
    The interest of the second mode (concurrency managed by the database) is to permit the clustering or concurrent modifications on the database. Typically a batch application can update the database directly, and the new values will be used immediatly after the batch end. The drawback of this solution is to drop the use of L2 cache between transactions. Indeed between two transactions data can be modified in the database.
    In the other hand, you can let speedo manage the concurrency when only the JDO application modifies data. In this case, you benefit of the cache use, and a concurrency managed in memory. This solution is the most efficient for stand alone application.
    By default the concurrency is managed by Speedo (first mode). To change it, you have to set the property org.objectweb.speedo.transaction.locking to the value 'database' as shown by the following example:

    org.objectweb.speedo.transaction.locking=database

    The value corresponding to the first mode (Speedo manages the concurrency) is 'speedo'.

    Note: When the concurrency management is delegated to the database, the L2 cache is still in use.

    Speedo has several other configuration points:

  5. Configuring the caching management
  6. Speedo provides two cache levels. The first level is the working set (ex: a transaction). That means if you use a persistent object in a transaction (or outside a transaction) the value is not reload in the transaction, except if you ask a refresh explicitly:

    pm.refresh(myObj)

    The second level cache keeps persistent object between working set. It avoids to load states between transactions. It permits to share the state between simultaneous transaction. Of course Speedo manages the concurrent access with or without L2 cache.
    The L1 cache is not desactivable currently whereas you can desactivate the L2 cache by several ways:

Note: When the cache is turned off, it only desactivates the cache process. The cache component is still part of the Speedo architecture and cache entries are still instanciated (the objects are always read from the database). As a consequence you still need to configure the properties listed below for the cache management. However it is possible to desactive complety the cache usage by desactivating the java instance sharing

    The L2 cache of Speedo is configurable through properties in the speedo-jdo.properties. You can change the following properties:

    The user caches

    The L2 cahce is indexed by the identifiers of the persistent objects. For each persistent class, the user defines the identifier (application or datastore). If your persistent class has a secondary key, you can specify it to Speedo in order to speed up the access to the instances. Let us take an example:
    Let have the persistent class Product which has a field 'productId' using as identifier and a field 'productName' which is a secondary key. This means that a productid or a productName represent an unique instance. Comparing to a database schema, the column 'productid' would be the primary key, and the column 'productname' would be declared as unique.
    In jdo, there are two ways to fetch an object:

    Then to fetch a product by its 'productName', we have to write a JDO query such as below, because the 'productName' is not the identifier:

    Query query = pm.newQuery(Product.class);
    query.setFilter("productName == p");
    query.declareParameters("String p");
    query.setUnique(true);
    Product p = (Product) query.execute("myProductName");

    In usual case, this JDO Query is translated into a SQL query executed on the database. But if you declare a user cache for the class Product, with the field 'productName' as index, Speedo tries first to find from the L2 cache, the Product instance corresponding to the value. If the instance is found from the L2 cache, no SQL query is executed. Therefore it is more efficient !
    The user cache declaration is done in the .jdo files. Indeed Speedo enhancer generates bytes code for handling indexed field modifications. The following examples shows how to declare a user class named 'c1', with the 'productName' field used as index:

    <class name="Product" identity-type="application">
    <field name="id" primary-key="true"/>
    <field name="productName">
    <extension vendor-name="speedo" key="user-cache" value="c1"/>
    </field>
    ...
    </class>

    If the index of the cache is composed of several fields, simply specify the same user cache for each field. A class can have several user class, if, for instance, the class has several secondary key.

    IMPORTANT: By default the user caches are not activated. You have to specify it in the speedo-jdo.properties such as the following example:

    org.objectweb.speedo.user-cache.classPolicy(*) *

    It actives all user caches of all classes

    org.objectweb.speedo.user-cache.classPolicy(*.Product) c1

    It actives the 'c1' user caches of all classes which the name is Product.

    How is it implemented in Speedo
    For each user cache of persistent classes, a

  1. The sharing of java persistent instance
  2. Speedo offers a special feature permitting to share the java persistent instances. This means in a JVM, there is only one java instance corresponding to an identifier of a persistent data. The interests are firstly to permit the exchange of java object between threads/transactions, secondly to avoid the creation of java object for each transaction and finally to be close to the java programming model. To manage this feature, Speedo extracts the persistent fields into another instance (StateItf). The java object sharing is assumed thanks to the L2 cache. Indeed it contains a persistent object and maybe the state too. By default this feature is activated. This is the reason why even if the cache is desactivate, the L2 cache is used for the sharing of java object but not for the caching apsect. The different ways to desactivate this feature are the following:

  3. Configuring the data prefetching
  4. The data prefetching is a strategy to load data from the data support before to use the them. This concept is different from the fetchgroup and fetch plan specified in JDO. Speedo provides three prefetching strategies:


  5. J2EE Application servers integration
  6. Speedo can be integrated into application servers as a resource adapter (JCA Connector SUN specification). Then, to use Speedo inside 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-jdo.properties' (or speedo-ejb.properties) configuration file. If no name is specified, several attempts are done with classical JNDI names used in some application servers:

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

    The org.objectweb.speedo.transaction.mode property enables to choose the transaction mode used for your application within a J2EE server. Thanks to this property, there is no need of changing your code passing from a standalone application to a J2EE application.
    Three modes are available:

    1. NORMAL: the Speedo transactions are processed as in a standalone application.
    2. REQUIRED: the Speedo transactions are ignored and only the method declared as "REQUIRED" in the xml descriptor of the web application are demarcated by JTA UserTransactions.
    3. USER_TRANSACTION: the Speedo transactions are changed into JTA UserTransactions.

    Data structures: Speedo is able, through Jorm, to create the data structure during the first use of a persistent class. But some data support does not permit to create data structures (SQL relations) inside XA transactions. Then Speedo allows only the DO_NOTHING value for the property org.objectweb.speedo.mappingStructure. Then you should read the Creation of the data structure section in order to create the data structure before the application starting.

    JOnAS case: In case of you want to integrate Speedo into JOnAS, you have to use compatible versions. Indeed, JOnAS and Speedo use common frameworks (JORM, MEDOR, Perseus) and the some classes are already available in the server. In addition, a small rar file dedicated to JOnAS is also provided with the Speedo distribution.

  7. The speedo-jdo.properties file
  8. This section describes the properties of the PersistencManagerFactory. The properties can be defined into the speedo.properties configuration file. Speedo provides an Eclipse plugin 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"
    org.objectweb.speedo.mapperName This property defines the name of mapper which must be used with the database. The default value is 'rdb.automatic'. For more information see the mappers section Speedo Y "rdb.automatic"
    or "rdb.postgres"
    or "rdb.mysql"
    or ...
    Speedo alone (no application server)
    javax.jdo.option.ConnectionDriverName This property defines the class name of the jdbc driver JDO Y "org.postgresql.Driver"
    or "com.mysql.jdbc.Driver"
    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 to the database. JDO Y "smith"
    javax.jdo.option.ConnectionPassword This property defines the password corresponding to user name authorized to access to the database. JDO Y "myPassword"
    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.connection.pool.ttl This property defines the time to live of a connection. The value is declared in millisecond. The 0 value means the resource has no TTL. The 0 value is the default. Speedo N 0 or a positive integer value
    org.objectweb.speedo.connection.pool.inactivettl This property defines the time to live of the unsused connection, ie the maximun time of a connection unsused in the pool. The value is declared in millisecond. The 0 value means the resource has no TTL. The 0 value is the default. Speedo N 0 or a positive integer value
    org.objectweb.speedo.connection.pool.timeout This property defines the time which the user agrees to wait a free connection from the pool. The value is declared in millisecond. The 0 value means that the user want to wait until a resource has been released. Speedo N 0 or a positive integer value
    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 created.
    • DELETE_DATA: The data present in the mapping structure are removed. Of course if the mapping structure do not exist, it is created.
    The default value is CREATE_IF_REQUIRED.
    Note: When speedo is integrated into an application server, this property must equal DO_NOTHING. Indeed it is rarely possible to create data structure (SQL relations) inside an XA transaction. If you specify another value, Speedo will force the value to DO_NOTHING and will log a warning about it.
    Speedo N DO_NOTHING
    or CREATE_IF_REQUIRED
    or FORCE_CREATE
    or DELETE_DATA
    Integration of Speedo into a J2EE application server
    javax.jdo.option.ConnectionFactoryName This property is the jndi name of the connection factory to use to access the data support. 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 N "javax.transaction.TransactionManger"
    Memory Cache Configuration
    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 'true' JDO N 'true' or 'false'
    javax.jdo.option.RestoreValues The management of this option is not supported. The only supported value is "false"
    javax.jdo.option.RetainValues This property indicates if the peristent state are kept in memory at commit time. The default value is 'true' JDO N 'true' or 'false'
    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.policy It defines the replacement politic of the memorry cache. The possible values are: LRU, MRU or FIFO. The default value is LRU Speedo N LRU, MRU or FIFO
    org.objectweb.speedo.cache.autoCleanSize This property defines the number of cache entry to free when the cache of memory instance is full or when the threshold is reached. 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.cache.autoCleanThreshold Is the number of entries since the cache must try to evict entries. The number of entries to evict is specified by the 'autoCleanSize' property. The possible values are absolute values (234) or a percent of the maximal cache size (75%). By default there is no threshold, then there is no auto cleaning process. Speedo N a positive integer value between 0 and the cache size or a percent (ex: 80%)
    org.objectweb.speedo.cache.classPolicy({class}) Define the caching policy for persistent classes.
    • nocache: instances of the class cannot be cached.
    • cache: instances of the class can be cached.
    • fixed: instances of the class can be cached and stay in the cache.
    • all: ALL instances are loaded at initialisation time, and they stay in the cache. This value can be used only with classes which have few instance. Indeed all instance are loaded in memory. The advantage of this option is to avoid I/O on extent.

    see Caching chapter
    Speedo N 'nocache' or 'cached' or 'fixed' or 'all'
    org.objectweb.speedo.user-cache.classPolicy({class}) user-cache activation
    An user cache is a view of the L2 memory cache indexed my a secondary key on persistent instance. You have to declare field used as index in the .jdo files and to activate the user caches. To this last action, you have to add this property which follows this pattern:
    org.objectweb.speedo.user-cache.classPolicy(<class name pattern>) <cache name comma list>
    Examples:
    org.objectweb.speedo.user-cache.classPolicy(*) *
    org.objectweb.speedo.user-cache.classPolicy(*.Bar) myCache1,myCache2

    see User-cache chapter
    Speedo N a comma list of user cache names or *
    Configuration of the Persistence manager pool
    org.objectweb.speedo.persistencemanager.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.persistencemanager.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.persistencemanager.pool.ttl This property defines the time to live of the unsused persistence manager, ie the persistence manager availlable in the pool. The value is declared in millisecond. The 0 value means the resource has no TTL. The 0 value is the default. Speedo N 0 or a positive integer value
    org.objectweb.speedo.persistencemanager.pool.timeout This property defines the time which the user agrees to wait a free peristence manager from the pool. The value is declared in millisecond. The 0 value means that the user want to wait until a resource has been released. Speedo N 0 or a positive integer value
    Query Management Configuration
    org.objectweb.speedo.query.prefetch.query This property permits to desactive the data prefetching on queries. The default value is 'on'. Speedo N 'on' or 'off'
    org.objectweb.speedo.query.prefetch.query({class}) This property permits to desactive the data prefetching on queries which the result is the specified class. The default value is 'on'.
    example: org.objectweb.speedo.query.prefetch.query(com.foo.Bar) off
    Speedo N 'on' or 'off'
    org.objectweb.speedo.query.prefetch.extent This property permits to desactive the data prefetching on extents. The default value is 'on'. Speedo N 'on' or 'off'
    org.objectweb.speedo.query.prefetch.extent({class}) This property permits to desactive the data prefetching on extents which the result is the specified class. The default value is 'on'.
    example: org.objectweb.speedo.query.prefetch.query(com.foo.Bar) off
    Speedo N 'on' or 'off'
    org.objectweb.speedo.compiledquery.cache.policy It defines the replacement politic of the compiled query cache. The possible values are: LRU, MRU or FIFO. The default value is LRU Speedo N LRU, MRU or FIFO
    org.objectweb.speedo.compiledquery.cache.size This property permits to manage the size of the cache of compiled query 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.compiledquery.cache .autoCleanSize This property defines the number of cache entry to free when the cache of compiled query instances is full or when the threshold is reached. 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.compiledquery.cache .autoCleanThreshold Is the number of entries since the cache must try to evict entries. The number of entries to evict is specified by the 'autoCleanSize' property. The possible values are absolute values (234) or a percent of the maximal cache size (75%). By default there is no threshold, then there is no auto cleaning process. Speedo N a positive integer value between 0 and the cache size or a percent (ex: 80%)
    Other properties
    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.txStatistic This property indicates if Speedo must build statistics about the transactions. Speedo N 'true' or 'false'
    javax.jdo.option.NontransactionalRead This property cannot be changed. Read operations are always allowed out of a transaction.
    javax.jdo.option.NontransactionalWrite This property cannot be changed. Write operations are always allowed out of a transaction.
    Transaction properties
    org.objectweb.speedo.transaction.locking Indicate which is in charge of the concurrency management. The concurrency can be manage by Speedo or the database:
    • speedo: Speedo manages the concurrency, the write access on the data support must be done only by a single Speedo instance. It means this mode does not support clustering or direct write accesses to the database.
    • database: The database manages the concurrency, the clusterting or direct write accesses to the database are possible. The drawback of this mode is to remove the use of the L2 cache. It means data are loaded at each transaction begin.
    Speedo N 'speedo'(default) or 'database'
    org.objectweb.speedo.transaction.locking .pessimistic.policy In case of Speedo is in charge of the concurrency management and the concurrency policy is set to pessimitic, this option defines the locking policy on persistant instance:
    • rw : parallel reader are permit, but a writer is alone to use the resource,
    • mutex : the access is exclusif.
    In all case the resource access is FIFO.
    Speedo N 'rw' or 'mutex'
    org.objectweb.speedo.transaction.locking.level.thin In case of Speedo is in charge of the concurrency management, this option defines if speedo allows the thin locking level management. A thin locking level is the management of the locking at class field or collection element level. The interest of this thin locking is to permit concurrent modification on a presistent instance (class or collection) but on different fields or elements.
    If you enable the thin locking level, you can specify for which collections or class the thin locking level must be used. To do this use the properties org.objectweb.speedo.transaction.locking.level({field}) and org.objectweb.speedo.transaction.locking.level({class}).
    Speedo N 'true' or 'false'(default)
    org.objectweb.speedo.transaction.locking.level({field}) In case of Speedo is in charge of the concurrency management, this option defines the locking level for a particular collection identified by its fully qualified path such as the following examples:
    • org.objectweb.speedo.transaction.locking.level(com.foo.Bar#*) = field
    • org.objectweb.speedo.transaction.locking.level(com.foo.Bar#myCollection) = instance

    Here is the possible values:
    • instance: the locking level is the persistent instances
    • field : the locking level can the element of collections (or list or set or map). Be careful to this locking level because it permits concurrent modification of the same collection if accessed elements are different.
    Speedo N 'instance'(default) or 'field'


  9. The Eclipse plugin for editing speedo.properties
  10. The plugin org.objectweb.speedo.properties.editor permits to edit a speedo.properties file. The interest of this plugin is to offer a documentation for each properties. It provides a graphical way to edit the configuration file. Of course, It avoids typos. The plugin is availlable in english and in french.

    Here is a snapshot of the plugin

    Editor of speedo.properties

    The plugin is based on a generic plugin (org.objectweb.eclipse.spe) which permits to edit structured properties file. The plugin 'org.objectweb.eclipse.spe' is personalized with an xml file describing the properties and the value for a speedo.properties.

  11. The other configuration files
  12. There are several configuration files provided with Speedo. Indeed Speedo uses several ObjectWeb projects/frameworks. All these configuration files must be available at the root of the classpath. In general most Speedo users only have to manage one file: speedo.properties. This section also describes in the second part the other configuration files.

    The configuration file: speedo.properties

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

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

    The file must be available at the root of the classpath during 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 is used to configure logging. It must be available at the root of the classpath during the enhancement and at 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 activate this logging the user must

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


    The configuration file: julia.cfg

    The Speedo implementation respects 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 available in the classpath (root position) during the enhancement and at 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 available in the classpath during the enhancement and at runtime.

  13. Mappers, Adapters and persistence support
  14. The persistent objects are stored in a persistence support. Thanks to JORM, it is possible to store persistent objects into various types of persistence support. Each persistence 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 databases. JORM provides also an automatic mechanism to discover the database product via a metadata provided by connections. If the auto detection fails you have to specify the mapper name mathcing the database product. The following table shows the supported persistence support and the associated mapper names:

    Persistence 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
    Hsql rdb.hsql OK
    Driver conform to JDBC specification rdb OK

    For more information about the adapters, see the JORM framework. Note that writing an adapter for a new relational database is a very easy task.

    How to write a new RdbAdapter ?

    The JORM project provides a RdbAdapter module permitting to easily write RdbAdapter. Download the product on the JORM download page.
    When your new RdbAdapter works fine, you can integrate the ow_jorm_rdb_adapter.jar into Speedo (lib directory in the distribution).

  15. Logging
  16. Like other ObjectWeb products, Speedo uses a logging API in order to be independant from implementations. Monolog provides wrappers to the usual logging systems like log4j or the logging system of jdk (since 1.4). There is a logging configuration file which does not depends on the logging system. This file is named "monolog.properties". Speedo uses Monolog in the automatic mode:


    For logging the SQL requests, see the configuration of the P6Spy tool in the configuration file section.

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