![]() |
![]() |
Back to the Speedo documentation
The speedo.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.
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:
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:
org.objectweb.speedo.cache.classPolicy(com.foo.Bar)=nocache
The L2 cache of Speedo is configurable through properties in the speedo.properties. You can change the following properties:
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.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
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:
org.objectweb.speedo.shareable false
org.objectweb.speedo.shareable(com.foo.Bar*) falseNote that if you specify * as class name, it is the same effect than using the first solution.
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:
org.objectweb.speedo.query.prefetch.query offThis property desactivates the prefetching for all queries for all classes.
org.objectweb.speedo.query.prefetch.query(<class name>)This property desactivates the prefetching for all queries of the specified class.
org.objectweb.speedo.query.prefetch.extent offThis property desactivates the prefetching for all queries for all classes.
org.objectweb.speedo.query.prefetch.extent(<class name>)This property desactivates the prefetching for all extents of the specified class.
org.objectweb.speedo.genclass.prefetch(<class name>#<field name>) offThis property desactivates the prefetching of the specified collection.
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.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:
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.
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:
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.
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(*) * 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 | 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:
|
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:
Here is the possible values:
|
Speedo | N | 'instance'(default) or 'field' |
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
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.
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.
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.
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.
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
logger.org.objectweb.speedo.mapper.mapper.sql.level DEBUGin the monolog.properties file.
The librairies of the p6spy tool are included in the speedo.jar.
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.
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.
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.
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).
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 more information about Monolog and its configuration file see
the Monolog
documentation