2011/01/16 - Apache ObJectRelationalBridge has been retired.

For more information, please explore the Attic.

HomeDocumentation
 

Repository File

Introduction - repository syntax

The syntax of the OJB repository xml files is defined by the repository.dtd.
An overview of all repository.dtd-elements can be found here. The repository.dtd can be found here.

The actual repository metadta declaration is split up into several separate files, here is an excerpt of the most important files:

  1. the repository.xml. Main file for metadata declaration. This file is split into several sub files using xml-Entity references.
  2. the repository_database.xml. This file contains the mapping information for database/connection handling.
  3. the repository_internal.xml. This file contains the mapping information for the OJB internal tables. These tables are used for implementing SequenceManagers and persistent collections.
  4. the repository_user.xml. This file contains mappings for the tutorial applications and may be used to hold further user defined class mappings.
  5. the repository_junit.xml. This file contains mapping information for common OJB JUnit regression test suite. In production environments these tables are not needed.
  6. other repository_junit_XYZ.xml
    More specific junit test mapping. In production environments these tables are not needed.
  7. There are some more files, for more information see comment in appropriate xml-file.

descriptor-repository

The descriptor-repository is the root element of a repository.xml file. It consists of one or more jdbc-connection-descriptor and at least one class-descriptor element. But it's also possible to startup OJB without any of these elements and add them at runtime.

Elements

<!ELEMENT descriptor-repository (documentation?, attribute*,
        jdbc-connection-descriptor*, class-descriptor*)>

The documentation element can be used to store arbitrary information.

The attribute element allows to add custom attributes, e.g. for passing arbitrary properties.

The jdbc-connection-descriptor element specifies a jdbc connection for the repository.

The class-descriptor element specify o/r mapping information for persistent class. 

<!ELEMENT descriptor-repository (
    documentation?,
    attribute*,
    jdbc-connection-descriptor*,
    class-descriptor* )
>

Attributes

The version attribute is used to bind a repository.xml file to a given version of this dtd. A given OJB release will work properly only with the repository version shipped with that relase. This strictness maybe inconvenient but it does help to avoid the most common version conflicts.

The isolation-level attribute defines the default locking isolation level used by OJB's pessimistic locking api. All jdbc-connection-descriptor or class-descriptor that do not define a specific isolation level will use this.
Note: This does NOT touch the jdbc-level of the connection.

The proxy-prefetching-limit attribute specifies a default value to be applied to all proxy instances. If none is specified a default value of 50 is used. Proxy prefetching specifies how many instances of a proxied class should be loaded in a single query when the proxy is first accessed. 

<!ATTLIST descriptor-repository
	version (1.0) #REQUIRED
	isolation-level (read-uncommitted | read-committed | repeatable-read |
	                 serializable | optimistic | none) "read-uncommitted"
	proxy-prefetching-limit CDATA "50"
>

jdbc-connection-descriptor

The jdbc-connection-descriptor element specifies a jdbc connection for the repository. It is allowed to define more than one jdbc-connection-descriptor. All class-descriptor elements are independent from the jdbc-connection-descriptors. More info about connection handling here.

Elements

The object-cache element specifies the object-cache implementation class associated with this class.

A connection-pool element may be used to define connection pool properties for the specified JDBC connection.

Further a sequence-manager element may be used to define which sequence manager implementation should be used within the defined connection.

Use the custom-attribute element to pass implementation specific properties. 

<!ELEMENT jdbc-connection-descriptor (documentation?, attribute*,
                object-cache?, connection-pool?, sequence-manager?)>

Attributes

The jdbc-connection-descriptor element contains a bunch of required and implied attributes:

The jcdAlias attribute is a shortcut name for the defined connection descriptor. OJB uses the jcd alias as key for the defined connections.

The default-connection attribute used to define if this connection should used as default connection with OJB. You could define only one connection as default connection. It is also possible to set the default connection at runtime using PersistenceBrokerFactory#setDefaultKey(...) method. If set true you can use a PB-api shortcut-method of the PersistenceBrokerFactory to lookup PersistenceBroker instances.

Note

If default-connection is not set at runtime, it is mandatory that username and password is set in repository file.

The platform attribute is used to define the specific RDBMS Platform. This attribute corresponds to a org.apache.ojb.broker.platforms.PlatformXXXImpl class. Supported databases see here. Default is Hsqldb.

The jdbc-level attribute is used to specify the Jdbc compliance level of the used Jdbc driver. Allowed values are: 1.0, 2.0, 3.0. Default is 1.0.

DEPRECATED!. The eager-release attribute is used to solve a problem that occurs when using OJB within JBoss (3.0 <= version < 3.2.2, seems to be fixed in jboss 3.2.2 and higher). Only use within JBoss. DEPRECATED attribute.

The batch-mode attribute allow to enable JDBC connection batch support (if supported by used database), 'true' value allows to enable per-session batch mode, whereas 'false' prohibits it. PB.serviceConnectionManager.setBatchMode(...) method can be used to switch on/off batch modus, if batch-mode is enabled. On PB.close() OJB switches off batch modus, thus you have to do '...setBatchMode(true)' on each obtained PB instance again.

Note

OJB 1.0.4 and earlier:
When using database identity columns it's not allowed to enable batch mode for insert operations.
When using optimistic locking the version check will always succeed for update operations when batch-mode is enabled - take care!!.

This will be fixed and automatically handled by OJB till next major release.

The useAutoCommit attribute allow to set how OJB uses the autoCommit state of the used connections. The default mode is 1. When using mode 0 or 2 with the PB-api, you must use PB transaction demarcation.

  • 0 - OJB ignores the autoCommit setting of the connection and does not try to change it. This mode could be helpful if the connection won't let you set the autoCommit state (e.g. using datasources within an application server).
  • 1 - [default mode] set the connection's autoCommit state temporary to 'false' if needed (when using transaction demarcation in non-managed environment) and restore the 'old' state after use.
    In versions before OJB 1.0.4 the autoCommit state was explicit set 'true' when connection was created, now OJB expect that this is done by the jdbc-driver/DataSource configuration. To enable the old behavior set a custom attribute initializationCheck to 'true'. 
    <attribute attribute-name="initializationCheck"
    attribute-value="false" />
    Then OJB set the autoCommit state explicitly to 'true' when the connection is created by the ConnectionFactory.
  • 2 - Set the connection's autoCommit explicitly to false when a connection is created.

If the ignoreAutoCommitExceptions attribute is set to true, all exceptions caused by setting autocommit state, will be ignored. Default mode is false.

If a jndi-datasource-name for JNDI based lookup of Jdbc connections is specified, the following four attributes driver, protocol, subprotocol, and dbalias used for Jdbc DriverManager based construction of Jdbc Connections must not be declared.
If a jndi-datasource-name is specified, OJB always assume that a JNDI based datasource connection lookup was expected (so take care that this attribute is empty or absent on driver based connection handling).

The username and password attributes are used as credentials for obtaining a jdbc connections.
If users don't want to keep user/password information in the repository.xml file, they can pass user/password using a PBKey to obtain a PersistenceBroker. More info see FAQ. 

<!ATTLIST jdbc-connection-descriptor
    jcd-alias CDATA #REQUIRED
    default-connection (true | false) "false"
    platform (  Db2 | Hsqldb | Informix | MsAccess | MsSQLServer |
                MySQL | Oracle | PostgreSQL | Sybase | SybaseASE |
                SybaseASA | Sapdb | Firebird | Axion | NonstopSql |
                Oracle9i | MaxDB ) "Hsqldb"
    jdbc-level (1.0 | 2.0 | 3.0) "1.0"
    eager-release (true | false) "false"
    batch-mode (true | false) "false"
    useAutoCommit (0 | 1 | 2) "1"
    ignoreAutoCommitExceptions (true | false) "false"

    jndi-datasource-name CDATA #IMPLIED

    driver CDATA #IMPLIED
    protocol CDATA #IMPLIED
    subprotocol CDATA #IMPLIED
    dbalias CDATA #IMPLIED

    username CDATA #IMPLIED
    password CDATA #IMPLIED
>

Custom attributes

The JdbcConnectionDescriptor supports specific configuration properties via custom-attributes.

Attribute initializationCheck is an attribute to support backward compatibility with OJB versions before 1.0.4.
In older versions OJB change the 'autoCommit' state dependent of the used 'useAutoCommit' attribute setting at connection initialization. This doesn't work in all situations/environments, thus for useAutoCommit="1" the ConnectionFactory does no longer set autoCommit to true on connection creation.
To use the old behavior (OJB version 1.0.3 or earlier) set this property to true, then OJB change the 'autoCommit' state (if needed) of new obtained connections at connection initialization.
If false or this property is removed, OJB dosen't try to change connection 'autoCommit' state at connection initialization.

Usage example of supported custom attributes: 

<jdbc-connection-descriptor
    ...
 >

    <attribute attribute-name="initializationCheck"
        attribute-value="false" />
    ...
</jdbc-connection-descriptor>

connection-pool

The connection-pool element specifies the connection pooling and low-level JDBC driver parameters. Read more about OJB connection handling.

Elements

The documentation element can be used to store arbitrary information.

Use the attribute element to set JDBC-level properties or to enable DBCP PreparedStatement pooling if your JDBC driver does not have a PreparedStatement cache already.

See section custom attributes below for more information.

Note

When using an external DataSource, OJB cannot configure any JDBC-properties. 
<!ELEMENT connection-pool ( documentation?, attribute* )>

Attributes

maxActive (default=21) The maximum number of active connections that can be allocated from this pool at the same time, or zero for no limit.

maxIdle (default=-1) The maximum number of active connections that can remain idle in the pool, without extra ones being released, or zero for no limit.

minIdle (Since OJB 1.0.4, default=0) The minimum number of active connections that can remain idle in the pool, without extra ones being created, or zero to create none.

maxWait (default=5000) The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely.
Must be > 0 for timeout to actually happen in DBCP PoolingDataSource.

whenExhaustedAction (default=0)

  • 0 - fail when pool is exhausted
  • 1 - block when pool is exhausted
  • 2 - grow when pool is exhausted

validationQuery (default=not specified) The SQL query that will be used to validate connections from this pool according to testOnBorrow/testOnReturn/testWhileIdle. If specified, this query must be an SQL SELECT statement that returns at least one row.
If not specified, only connection.isClosed() checks will be performed according to testOnBorrow/testOnReturn/testWhileIdle.

Note

Many database servers will discard idle connections after some time of inactivity. This timespan is usually configurable by the DBA and can range from anything between one hour and several days.
Consider specifying a validation query that fits your database server and set at least testOnBorrow=true.

Example validation queries: 

    Oracle      SELECT 1 FROM DUAL
    PostgreSQL  SELECT 1
    MySQL       SELECT 1

testOnBorrow (default=true) The indication of whether connections will be validated before being borrowed from the pool. If the connection fails to validate, it will be dropped from the pool, and OJB will attempt to borrow another.

testOnReturn (default=false) The indication of whether connections will be validated before being returned to the pool.

testWhileIdle (default=false) The indication of whether connections will be validated by the idle object evictor (if any). If a connection fails to validate, it will be dropped from the pool.

timeBetweenEvictionRunsMillis (default=-1) The number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.

numTestsPerEvictionRun (default=10) The number of objects to examine during each run of the idle object evictor thread (if any).
Has no meaning if timeBetweenEvictionRunsMillis is non-positive.

minEvictableIdleTimeMillis (default=1800000) The minimum amount of time a connection may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any).
When non-positive, no connection will be dropped from the pool due to idle time alone.
Has no meaning if timeBetweenEvictionRunsMillis is non-positive.

removeAbandoned [ConnectionFactoryDBCPImpl] (default=false) Flag to remove abandoned connections if they exceed the removeAbandonedTimout. If set to true a connection is considered abandoned and eligible for removal if it has been idle longer than the removeAbandonedTimeout. Setting this to true can recover db connections from poorly written applications which fail to close a connection.
If you have enabled "removeAbandoned" then it is possible that a connection is reclaimed by the pool because it is considered to be abandoned. This mechanism is triggered on borrowObject (ie in OJB when a PersistenceBroker gets a Connection) when:
(numIdle < 2) and (numActive > maxActive - 3)
For example maxActive=20, 18 active connections and 1 idle connection would trigger the "removeAbandoned". But only the active connections that aren't used for more then removeAbandonedTimeout seconds are removed. Traversing a resultset doesn't count as being used.
The abandoned object eviction takes place before normal borrowObject logic (there is no asynch evictor thread like for testWhileIdle).

removeAbandonedTimeout [ConnectionFactoryDBCPImpl] (default=300) Timeout in seconds before an abandoned connection can be removed.
Has no meaning if removeAbandoned is false.

logAbandoned [ConnectionFactoryDBCPImpl] (default=false) Flag to log stack traces for application code which abandoned a Statement or Connection.

Note

Logging of abandoned Statements and Connections adds overhead for every Connection open or new Statement because a stack trace has to be generated. 
<!ATTLIST connection-pool
    maxActive                       CDATA #IMPLIED
    minIdle                         CDATA #IMPLIED
    maxIdle                         CDATA #IMPLIED
    maxWait                         CDATA #IMPLIED
    minEvictableIdleTimeMillis      CDATA #IMPLIED
    numTestsPerEvictionRun          CDATA #IMPLIED
    testOnBorrow                    ( true | false ) #IMPLIED
    testOnReturn                    ( true | false ) #IMPLIED
    testWhileIdle                   ( true | false ) #IMPLIED
    timeBetweenEvictionRunsMillis   CDATA #IMPLIED
    whenExhaustedAction             ( 0 | 1 | 2 ) #IMPLIED
    validationQuery                 CDATA #IMPLIED

    removeAbandoned                 ( true | false ) #IMPLIED
    removeAbandonedTimeout          CDATA #IMPLIED
    logAbandoned                    ( true | false ) #IMPLIED
>

Custom attributes

OJB itself and the ConnectionFactory implementation classes support specific connection configuration properties, these properties can be set by using custom-attributes.

Usage example of supported custom attributes: 

<connection-pool
    maxActive="30"
    validationQuery="@VALIDATION_QUERY@"
    testOnBorrow="@TEST_ON_BORROW@"
    testOnReturn="@TEST_ON_RETURN@"
    whenExhaustedAction="0"
    maxWait="10000">

    <!-- Set fetchSize to 0 to use driver's default. -->
    <attribute attribute-name="fetchSize" attribute-value="0"/>

    <!-- Attributes with name prefix "jdbc." are passed directly to the JDBC driver. -->
    <!-- Example setting (used by Oracle driver when Statement batching is enabled) -->
    <attribute attribute-name="jdbc.defaultBatchValue" attribute-value="5"/>

    <!-- Attributes determining if ConnectionFactoryDBCPImpl
         should also pool PreparedStatement. This is programmatically disabled
         when using platform=Oracle9i since Oracle statement caching will conflict
         with DBCP ObjectPool-based PreparepdStatement caching (ie setting true
         here has no effect for Oracle9i platform). -->
    <attribute attribute-name="dbcp.poolPreparedStatements" attribute-value="true"/>
    <attribute attribute-name="dbcp.maxOpenPreparedStatements" attribute-value="60"/>
    <!-- Attribute determining if the Commons DBCP connection wrapper will allow
         access to the underlying concrete Connection instance from the JDBC-driver
         (normally this is not allowed, like in J2EE-containers using wrappers). -->
    <attribute attribute-name="dbcp.accessToUnderlyingConnectionAllowed"
          attribute-value="false"/>
</connection-pool>

jdbc.*

Since OJB 1.0.4, custom attributes with names starting with "jdbc." will be passed (without the "jdbc." prefix) to the JDBC DriverManager when creating new Connection objects.

Use this attribute to set driver-specific customized tuning options. For example, to set Oracle-batching to 5 statements: 

<attribute attribute-name="jdbc.defaultBatchValue" attribute-value="5"/>

fetchSize

(default=0, unspecified) Sets a hint in the JDBC driver not to fetch more than specified number of rows per server roundtrip for any ResultSet.
Setttings different than the default (0) are especially useful to reduce memory footprint when using drivers that default to not using server-side cursors and retrieves all rows to the JDBC client-side driver buffer. PostgreSQL JDBC driver is a well-known example of this.

Note

* Many JDBC drivers will silently ignore the fetchSize hint.
* Also note that fetchSize has nothing to do with max rows returned by a ResultSet, only number of rows retrieved per JDBC- driver network roundtrip to the database server (if the driver cares about the hint at all, that is).

dbcp.poolPreparedStatements

Only valid for ConnectionFactoryDBCPImpl (default=false) Enable prepared statement pooling.

Note

PreparedStatement pooling with Commons DBCP is programmatically disabled when using platform=Oracle9i in OJB, since the platform implementation activates Oracle-specific statement caching that conflicts with DBCP ObjectPool-based caching. Ie, for a descriptor with platform="Oracle9i" there is no effect in setting: 
<attribute attribute-name="dbcp.poolPreparedStatements" attribute-value="true"/>

dbcp.maxOpenPreparedStatements

Only valid for ConnectionFactoryDBCPImpl (default=0, unlimited) The maximum number of open statements that can be allocated from the statement pool at the same time, or zero for no limit.

dbcp.accessToUnderlyingConnectionAllowed

Only valid for ConnectionFactoryDBCPImpl (default=false) Controls if the DBCP "PoolGuard" connection wrapper allows access to the underlying Connection instance from the JDBC-driver.

Only use when you need direct access to driver-specific extentions. It is generally not needed to change this setting in OJB.

Note

* Do not close the underlying connection, only the original one.
* If using P6Spy, the underlying connection in DBCP will still be wrapped by P6Spy and you will have to continue unwrapping to the innermost delegate and Connection of JDBC-driver specific class.

sequence-manager

The sequence-manager element specifies the sequence manager implementation used for key generation. All sequence manager implementations shipped with OJB can be found in the org.apache.ojb.broker.util.sequence package. If no sequence manager is defined, OJB uses the default one. More info about sequence key generation here.

Elements

Use the custom-attribute element to pass implementation specific properties. 

<!ELEMENT sequence-manager (
    documentation?,
    attribute* )
>

Attributes

The className attribute represents the full qualified class name of the desired sequence manager implementation - it is mandatory when using the sequence-manager element. All sequence manager implementations you find will under org.apache.ojb.broker.util.sequence package named as SequenceManagerXXXImpl

More info about the usage of the Sequence Manager implementations can be found here. 

<!ATTLIST sequence-manager
    className CDATA #REQUIRED>

Custom Attributes

The SequenceManager implementation classes support specific configuration properties, these properties can be set by using custom-attributes.

The description of the properties can be found in sequence manager docs.
Usage example of supported custom attributes: 

<sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerHighLowImpl">
    <!-- attributes supported by SequenceManagerHighLowImpl,
    SequenceManagerInMemoryImpl, SequenceManagerNextValImpl
    please see "Sequence Manager" guide or/and javadoc of class for more information -->
    <attribute attribute-name="seq.start" attribute-value="200000"/>
    <attribute attribute-name="autoNaming" attribute-value="true"/>

    <!-- attributes supported by SequenceManagerHighLowImpl
    please see "Sequence Manager" guide or/and javadoc of classes for more information -->
    <attribute attribute-name="grabSize" attribute-value="20"/>

    <!-- optional attributes supported by SequenceManagerNextValImpl (support depends
    on the used database), please see "Sequence Manager" guide or/and javadoc of
    classes for more information -->
    <!-- attribute attribute-name="seq.as" attribute-value="INTEGER"/ -->
    <!-- attribute attribute-name="seq.incrementBy" attribute-value="1"/ -->
    <!-- attribute attribute-name="seq.maxValue" attribute-value="999999999999999999999999999"/ -->
    <!-- attribute attribute-name="seq.minValue" attribute-value="1"/ -->
    <!-- attribute attribute-name="seq.cycle" attribute-value="false"/ -->
    <!-- attribute attribute-name="seq.cache" attribute-value="20"/ -->
    <!-- attribute attribute-name="seq.order" attribute-value="false"/ -->
</sequence-manager>

object-cache

The object-cache element can be used to specify the ObjectCache implementation used by OJB. There are three levels of declaration:

  • in OJB.properties file, to declare the standard (default) ObjectCache implementation
  • on jdbc-connection-descriptor level, to declare ObjectCache implementation on a per connection/user level
  • on class-descriptor level, to declare ObjectCache implementation on a per class level

Note

The priority of the declared object-cache elements are:
per class > per jdbc descriptor > standard

E.g. if you declare ObjectCache implementation 'my.cacheDef' as standard, set ObjectCache implementation 'my.cacheA' in class-descriptor for class A and class B does not declare an object-cache element. Then OJB use 'my.cacheA' as ObjectCache for class A and 'my.cacheDef' for class B.

Elements

Use the custom-attribute element to pass implementation specific properties. 

<!ELEMENT object-cache (documentation?, attribute*)>

Attributes

Attribute 'class' specifies the full qualified class name of the used ObjectCache implementation. 

<!ATTLIST object-cache class  CDATA  #REQUIRED>

Custom Attributes

Many ObjectCache implementation classes support specific configuration properties, these properties can be set by using custom-attributes.

The description of the properties can be found in object cache docs.
Usage example of supported custom attributes: 

<object-cache class="org.apache.ojb.broker.cache.ObjectCacheTwoLevelImpl">
    <!-- meaning of attributes, please see docs section "Caching" -->
    <!-- common attributes -->
    <attribute attribute-name="cacheExcludes" attribute-value=""/>

    <!-- ObjectCacheTwoLevelImpl attributes -->
    <attribute attribute-name="applicationCache"
        attribute-value="org.apache.ojb.broker.cache.ObjectCacheDefaultImpl"/>
    <attribute attribute-name="copyStrategy"
        attribute-value="org.apache.ojb.broker.cache.ObjectCacheTwoLevelImpl$CopyStrategyImpl"/>
    <attribute attribute-name="forceProxies" attribute-value="false"/>

    <!-- ObjectCacheDefaultImpl attributes -->
    <attribute attribute-name="timeout" attribute-value="900"/>
    <attribute attribute-name="autoSync" attribute-value="true"/>
    <attribute attribute-name="cachingKeyType" attribute-value="0"/>
    <attribute attribute-name="useSoftReferences" attribute-value="true"/>
</object-cache>

custom attribute

An attribute element allows arbitrary name/value pairs to be represented in the repository. See the repository.dtd for details on which elements support it (e.g. class-descriptor, object-cache, ...). 

<!ELEMENT attribute EMPTY>

The attribute-name identifies the name of the attribute.
The attribute-value identifies the value of the attribute. 

<!ATTLIST attribute
    attribute-name CDATA #REQUIRED
    attribute-value CDATA #REQUIRED
>

To get access of the definied attribute use methods of org.apache.ojb.broker.metadata.AttributeContainer. All classes supporting custom attributes have to implement this interface.

Here you can see an example how to define an custom attribute within the class-descriptor element: 

<class-descriptor
        class="my.TestClass"
        table="OJB_TEST_CLASS"
    >
      <field-descriptor
         name="id"
         column="ID"
         jdbc-type="INTEGER"
         primarykey="true"
         autoincrement="true"
      />
      ...
      <attribute attribute-name="myAttribute" attribute-value="myValue"/>
</class-descriptor>

To access the attribute you have to know the associated AttributeContainer class. Here it was ClassDescriptor. To read the attribute at runtime do: 

// get the ClassDescriptor
ClassDescriptor cld = broker.getClassDescriptor(TestClass.class);
String value = cld.getAttribute("myAttribute");

class-descriptor

A class-descriptor and the associated java class ClassDescriptor encapsulate metadata information of an interface, abstract or concrete class.

Elements

For interfaces or abstract classes a class-descriptor holds a sequence of extent-class elements which specify the types extending this class.
Concrete base classes may specify a sequence of extent-class elements, naming the derived classes.

For concrete classes it must have field-descriptors that describe primitive typed instance variables. References to other persistent entity classes are specified by reference-descriptor elements. Collections or arrays attributes that contain other persistent entity classes are specified by collection-descriptor elements
A class-descriptor may contain user defined custom attribute elements.

Use the custom-attribute element to pass implementation specific properties. 

<!ELEMENT class-descriptor (
    (
        documentation?,
        extent-class+,
        attribute* ) |
    (
        documentation?,
        object-cache?,
        extent-class*,
        field-descriptor+,
        reference-descriptor*,
        collection-descriptor*,
        index-descriptor*,
        attribute*,
        insert-procedure?,
        update-procedure?,
        delete-procedure? )
    )
>

Attributes

The class attribute contains the full qualified name of the specified class. As this attribute is of the XML type ID there can only be one class-descriptor per class.

The isolation-level attribute defines the locking isolation level of the specified class (used by OJB's pessimistic locking api).

Note

The isolation-level does not touch the jdbc-connection isolation level. It's completely independend from the database connection setting and only important when pessimistic locking was used.

If the proxy attribute is set, proxies are used for all loading operations of instances of this class. If set to dynamic, dynamic proxies are used. If set to another value this value is interpreted as the full-qualified name of the proxy class to use. More info about using of proxies here.

The proxy-prefetching-limit attribute specifies a limit to the number of elements loaded on a proxied reference. When the first proxied element is loaded, a number up to the proxy-prefetch-limit will be loaded in addition.

The schema attribute may contain the database schema owning the table mapped to this class.

The table attribute speciefies the table name this class is mapped to.

The row-reader attribute may contain a full qualified class name. This class will be used as the RowReader implementation used to materialize instances of the persistent class.

The extends attribute is deprecated and will be removed or reintroduced with changed funcitonality in future. DON'T USE IT!

The accept-locks attribute specifies whether implicit locking should propagate to this class. Currently relevant for the ODMG layer only.

The optional initialization-method specifies a no-argument instance method that is invoked after reading an instance from a database row. It can be used to do initialization and validations.

The optional factory-class specifies a factory class that that is to be used instead of a no argument constructor when new objects are created. If the factory class is specified, then the factory-method also must be defined. It refers to a static no-argument method of the factory class that returns a new instance.

The refresh attribute can be set to true to force OJB to refresh instances when loaded from cache. Means all field values (except references) will be replaced by values retrieved from the database. It's set to false by default. 

<!ATTLIST class-descriptor
    class ID #REQUIRED
    isolation-level (read-uncommitted | read-committed |
        repeatable-read | serializable | optimistic | none) "read-uncommitted"
    proxy CDATA #IMPLIED
    proxy-prefetching-limit CDATA #IMPLIED
    schema CDATA #IMPLIED
    table CDATA #IMPLIED
    row-reader CDATA #IMPLIED
    extends IDREF #IMPLIED
    accept-locks (true | false) "true"
    initialization-method CDATA #IMPLIED
    factory-class CDATA #IMPLIED
    factory-method CDATA #IMPLIED
    refresh (true | false) "false"
>

extent-class

An extent-class element is used to specify an implementing class or a derived class that belongs to the extent of all instances of the interface or base class. 

<!ELEMENT extent-class EMPTY>

The class-ref attribute must contain a fully qualified classname and the repository file must contain a class-descriptor for this class. 

<!ATTLIST extent-class class-ref IDREF #REQUIRED>

field-descriptor

A field descriptor contains mapping info for a primitive typed attribute of a persistent class.
A field descriptor may contain custom attribute elements.

Use the custom-attribute element to pass implementation specific properties. 

<!ELEMENT field-descriptor (documentation?, attribute*)>

The id attribute is optional. If not specified, OJB internally sorts field-descriptors according to their order of appearance in the repository file.
If a different sort order is intended the id attribute may be used to hold a unique number identifying the decriptors position in the sequence of field-descriptors.

Note

The order of the numbers for the field-descriptors must correspond to the order of columns in the mapped table.

The name attribute holds the name of the persistent classes attribute. More info about persistent field handling.

The table attribute may specify a table different from the mapped table for the persistent class. (currently not implemented).

The column attribute specifies the column the persistent classes field is mapped to.

The jdbc-type attribute specifies the JDBC type of the column. If not specified OJB tries to identify the JDBC type by inspecting the Java attribute by reflection - OJB use the java/jdbc mapping desribed here.

The primarykey specifies if the column is a primary key column, default value is false. It's possible to auto assign primary key fields, more info see autoincrement section

The nullable attribute specifies if the column may contain null values.

The indexed attribute specifies if there is an index on this column

The autoincrement attribute specifies if the values for the persistent attribute should be automatically generated by OJB. More info about sequence key generation here.

The sequence-name attribute can be used to state explicitly a sequence name used by the sequence manager implementations. Check the javadocs of the used sequence manager implementation to get information if this is a mandatory attribute. OJB standard sequence manager implementations build a sequence name by its own, if the attribute is not set. More info about sequence key generation here.

The locking attribute is set to true if the persistent attribute is used for optimistic locking. More about optimistic locking. The default value is false.

The updatelock attribute is set to false if the persistent attribute is used for optimistic locking AND the dbms should update the lock column itself. The default is true which means that when locking is true then OJB will update the locking fields. Can only be set for TIMESTAMP and INTEGER columns.

The default-fetch attribute specifies whether the persistent attribute belongs to the JDO default fetch group.

The conversion attribute contains a fully qualified class name. This class must implement the interface org.apache.ojb.accesslayer.conversions.FieldConversion. A FieldConversion can be used to implement conversions between Java- attributes and database columns. More about field conversion.

The length attribute can be used to specify a length setting if required by the jdbc-type of the underlying database column.

The precision attribute can be used to specify a precision setting, if required by the jdbc-type of the underlying database column.

The scale attribute can be used to specify a sclae setting, if required by the jdbc-type of the underlying database column.

The access attribute specifies the accessibility of the field. Fields marked as readonly are not to modified. readwrite marks fields that may be read and written to. anonymous marks anonymous fields.
An anonymous field has a database representation (column) but no corresponding Java attribute. Hence the name of such a field does not refer to a Java attribute of the class, but is used as a unique identifier only. More info about anonymous keys here. 

<!ATTLIST field-descriptor
    id CDATA #IMPLIED
    name CDATA #REQUIRED
    table CDATA #IMPLIED
    column CDATA #REQUIRED
    jdbc-type (BIT | TINYINT | SMALLINT | INTEGER | BIGINT | DOUBLE |
               FLOAT | REAL | NUMERIC | DECIMAL | CHAR | VARCHAR |
               LONGVARCHAR | DATE | TIME | TIMESTAMP | BINARY |
               VARBINARY | LONGVARBINARY | CLOB | BLOB) #REQUIRED
    primarykey (true | false) "false"
    nullable (true | false) "true"
    indexed (true | false) "false"
    autoincrement (true | false) "false"
    sequence-name CDATA #IMPLIED
    locking (true | false) "false"
    update-lock (true | false) "true"
    default-fetch (true | false) "false"
    conversion CDATA #IMPLIED
    length CDATA #IMPLIED
    precision CDATA #IMPLIED
    scale CDATA #IMPLIED
    access (readonly | readwrite | anonymous) "readwrite"
>

reference-descriptor

A reference-descriptor contains mapping info for an attribute of a persistent class that is not primitive but references another persistent entity Object. More about 1:1 references here.

A foreignkey element contains information on foreign key columns that implement the association on the database level. 

<!ELEMENT reference-descriptor ( foreignkey+)>

The name attribute holds the name of the persistent classes attribute. Depending on the used PersistendField implementation, there must be e.g. an attribute in the persistent class with this name or a JavaBeans compliant property of this name.

The class-ref attribute contains a fully qualified class name. This class is the Object type of the persistent reference attribute. As this is an IDREF there must be a class-descriptor for this class in the repository too.

The proxy attribute can be set to true to specify that proxy based lazy loading should be used for this attribute.

The proxy-prefetch-limit attribute specifies a limit to the number of elements loaded on a proxied reference. When the first proxied element is loaded, a number up to the proxy-prefetch-limit will be loaded in addition.

The refresh attribute can be set to true to force OJB to refresh the object reference when the object is loaded from cache. If true OJB try to retrieve the reference (dependent on the auto-xxx settings) again when the main object is loaded from cache (normally only make sense for 1:n and m:n relations).
This could be useful if the ObjectCache implementation cache full object graphs without synchronize the referenced objects.

Note

This does not mean that all referenced objects will be read from database. It only means that the reference will be refreshed, the objects itself may provided by the cache. To refresh the object fields itself set the refresh attribute in class-descriptor of the referenced object or disable caching (to always read objects from the persistent storage).

The auto-retrieve attribute specifies whether OJB automatically retrieves this reference attribute on loading the persistent object. If set to false the reference attribute is set to null. In this case the user is responsible to fill the reference attribute.
More info about auto-retrieve here.

The auto-update attribute specifies whether OJB automatically stores this reference attribute on storing the persistent object.
More info about the auto-XXX settings here.

Note

This attribute must be set to false if using the OTM or JDO layer.
For ODMG-api none is mandatory (since OJB 1.0.2).

The auto-delete attribute specifies whether OJB automatically deletes this reference attribute on deleting the persistent object.
More info about the auto-XXX settings here.

Note

This attribute must be set to false if using the OTM or JDO layer.
For ODMG-api none is mandatory (since OJB 1.0.2).

The otm-dependent attribute specifies whether the OTM layer automatically creates the referred object or deletes it if the reference field is set to null. Also otm-dependent references behave as if auto-update and auto-delete were set to true, but the auto-update and auto-delete attributes themself must be always set to false for use with OTM layer. 

<!ATTLIST reference-descriptor
	name CDATA #REQUIRED
	class-ref IDREF #REQUIRED

	proxy (true | false) "false"
	proxy-prefetching-limit CDATA #IMPLIED
	refresh (true | false) "false"

	auto-retrieve (true | false) "true"
	auto-update (none | link | object | true | false) "false"
	auto-delete (none | link | object | true | false) "false"
	otm-dependent (true | false) "false"
>

foreignkey

A foreignkey element contains information on a foreign-key persistent attribute that implement the association on the database level. 

<!ELEMENT foreignkey EMPTY>

The field-ref and field-id-ref attributes contain the name and the id attributes of the field-descriptor used as a foreign key.

Note

Exactly one of these attributes must be specified. 
<!ATTLIST foreignkey
    field-id-ref CDATA #IMPLIED
    field-ref CDATA #IMPLIED
>

collection-descriptor

A collection-descriptor contains mapping info for a Collection- or Array-attribute of a persistent class that contains persistent entity Objects. See more about 1:n and m:n references.

The orderby element(s) allow to specify the order the collection objects. It's allowed to specify multiple order fields.

The inverse-foreignkey elements contains information on foreign-key attributes that implement the association on the database level.

The fk-pointing-to-this-class and fk-pointing-to-element-class elements are only needed if the Collection or array implements a m:n association. In this case they contain information on the foreign-key columns of the intermediary table.

Use the custom-attribute element to pass implementation specific properties. 

<!ELEMENT collection-descriptor (
    documentation?,
    orderby*,
    inverse-foreignkey*,
    fk-pointing-to-this-class*,
    fk-pointing-to-element-class*,
    attribute*)>

The name attribute holds the name of the persistent classes attribute. More info about persistent field handling.

The collection-class may hold a fully qualified class name. This class must be the Java type of the Collection attribute. This attribute must only specified if the attribute type is not a java.util.Collection (or subclass) or Array type. It is also possible to use non Collection or Array type user defined "collection" classes. More info see section manageable collection.

The element-class-ref attribute contains a fully qualified class name. This class is the Object type of the elements of persistent collection or Array attribute. As this is an IDREF there must be a class-descriptor for this class in the repository too.

DEPRECATED, please use the 'orderby'-element. The orderby attribute may specify a field of the element class. The Collection or Array will be sorted according to the specified attribute. The sort attribute may be used to specify ascending or descending order for this operation.

The indirection-table must specify the name of an intermediary table, if the persistent collection attribute implements a m:n association.

The proxy attribute can be set to true to specify that proxy based lazy loading should be used for this attribute. More about using proxy here.

The proxy-prefetch-limit attribute specifies a limit to the number of elements loaded on a proxied reference. When the first proxied element is loaded, a number up to the proxy-prefetch-limit will be loaded in addition.

The refresh attribute can be set to true to force OJB to refresh the object reference when the object is loaded from cache. If true OJB try to retrieve the reference (dependent on the auto-xxx settings) again when the main object is loaded from cache (normally only make sense for 1:n and m:n relations).
This could be useful if the ObjectCache implementation cache full object graphs without synchronize the referenced objects.

Note

This does not mean that all referenced objects will be read from database. It only means that the reference will be refreshed, the objects itself may provided by the cache. To refresh the object fields itself set the refresh attribute in class-descriptor of the referenced object or disable caching (to always read objects from the persistent storage).

The auto-retrieve attribute specifies whether OJB automatically retrieves this reference attribute on loading the persistent object. If set to false the reference attribute is set to null. In this case the user is responsible to fill the reference attribute.
More info about auto-retrieve here.

The auto-update attribute specifies whether OJB automatically stores this reference attribute on storing the persistent object.
More info about the auto-XXX settings here.

Note

This attribute must be set to false if using the OTM or JDO layer.
For ODMG-api none is mandatory (since OJB 1.0.2).

The auto-delete attribute specifies whether OJB automatically deletes this reference attribute on deleting the persistent object.
More info about the auto-XXX settings here.

Note

This attribute must be set to false if using the OTM or JDO layer.
For ODMG-api none is mandatory (since OJB 1.0.2).

The otm-dependent attribute specifies whether the OTM layer automatically creates collection elements that were included into the collection, and deletes collection elements that were removed from the collection. Also otm-dependent references behave as if auto-update and auto-delete were set to true, but the auto-update and auto-delete attributes themself must be always set to false for use with OTM layer. 

<!ATTLIST collection-descriptor
	name CDATA #IMPLIED
	collection-class CDATA #IMPLIED
	element-class-ref IDREF #REQUIRED
	orderby CDATA #IMPLIED
	sort (ASC | DESC) "ASC"

	indirection-table CDATA #IMPLIED

	proxy (true | false) "false"
	proxy-prefetching-limit CDATA #IMPLIED
	refresh (true | false) "false"

	auto-retrieve (true | false) "true"
	auto-update (none | link | object | true | false) "false"
	auto-delete (none | link | object | true | false) "false"
	otm-dependent (true | false) "false"
>

order-by

A order-by element contains an attribute name and a sort order. 

<!ELEMENT orderby (documentation?)>

The name attribute specifies the field or the column (full qualified column name) the order based on. The sort attribute specifies the order direction. 

<!ATTLIST orderby
	name CDATA #REQUIRED
	sort (ASC | DESC) "ASC"
>

Here is an examples of how to use ordering for one side of a m:n reference: 

<collection-descriptor
    name="actors"
    collection-class="org.apache.ojb.broker.util.collections.ManageableArrayList"
    element-class-ref="org.apache.ojb.broker.M2NTest$Actor"
    auto-retrieve="false"
    auto-update="false"
    auto-delete="false"
    indirection-table="M2N_ROLE"
>
    <!-- Check the use of order by element for fields and plain columns -->
    <orderby name="name" sort="ASC"/>
    <orderby name="M2N_ROLE.MOVIE_ID_INT" sort="DESC"/>

    <fk-pointing-to-this-class column="MOVIE_ID_INT"/>
    <fk-pointing-to-this-class column="MOVIE_ID2_INT"/>
    <fk-pointing-to-this-class column="MOVIE_ID_STR"/>
    <fk-pointing-to-element-class column="ACTOR_ID"/>
    <fk-pointing-to-element-class column="ACTOR_ID2"/>
</collection-descriptor>

inverse-foreignkey

A inverse-foreignkey element contains information on a foreign-key persistent attribute that implement the association on the database level. 

<!ELEMENT inverse-foreignkey EMPTY>

The field-ref and field-id-ref attributes contain the name and the id attributes of the field-descriptor used as a foreign key. Exactly one of these attributes must be specified. 

<!ATTLIST inverse-foreignkey
    field-id-ref CDATA #IMPLIED
    field-ref CDATA #IMPLIED
>

fk-pointing-to-this-class

A fk-pointing-to-this-class element contains information on a foreign-key column of an intermediary table in a m:n scenario. 

<!ELEMENT fk-pointing-to-this-class EMPTY>

The column attribute specifies the foreign-key column in the intermediary table that points to the class holding the collection. 

<!ATTLIST fk-pointing-to-this-class
    column CDATA #REQUIRED
>

fk-pointing-to-element-class

A fk-pointing-to-element-class element contains information on a foreign-key column of an intermediary table in a m:n scenario. 

<!ELEMENT fk-pointing-to-element-class EMPTY>

The column attribute specifies the foreign-key column in the intermediary table that points to the class of the collection elements. 

<!ATTLIST fk-pointing-to-element-class
    column CDATA #REQUIRED
>

query-customizer

A query enhancer element to enhance the 1:n query, e.g. to modify the result objects of a query. More info about customizing collection queries.

Use the custom-attribute element to pass implementation specific properties. 

<!ELEMENT query-customizer (
    documentation?,
    attribute*)>

<!ATTLIST query-customizer
    class CDATA #REQUIRED
>

index-descriptor

An index-descriptor describes an index by listing its columns. It may be unique or not. 

<!ELEMENT index-descriptor (documentation?, index-column+)>

<!ATTLIST index-descriptor
    name CDATA #REQUIRED
    unique (true | false) "false">

index-column

An index-column is just the name of a column in an index. 

<!ELEMENT index-column (documentation?)>

<!ATTLIST index-column
    name CDATA #REQUIRED>

Stored Procedure Support

OJB supports stored procedures for insert, update and delete operations. How to use stored procedures within OJB can be found here.

insert-procedure

Identifies the procedure/function that should be used to handle insertions for a specific class-descriptor.

The nested argument elements define the argument list for the procedure/function as well as the source for each argument.

Use the custom-attribute element to pass implementation specific properties. 

<!ELEMENT insert-procedure
    (documentation?, (runtime-argument | constant-argument)?, attribute*)>

The name attribute identifies the name of the procedure/function to use

The return-field-ref identifies the field-descriptor that will receive the value that is returned by the procedure/function. If the procedure/ function does not include a return value, then do not specify a value for this attribute.

The include-all-fields attribute indicates if all field-descriptors in the corresponding class-descriptor are to be passed to the procedure/ function. If include-all-fields is 'true', any nested 'argument' elements will be ignored. In this case, values for all field-descriptors will be passed to the procedure/function. The order of values that are passed to the procedure/function will match the order of field-descriptors on the corresponding class-descriptor. If include-all-fields is false, then values will be passed to the procedure/function based on the information in the nested 'argument' elements. 

<!ATTLIST insert-procedure
    name CDATA #REQUIRED
    return-field-ref CDATA #IMPLIED
    include-all-fields (true | false) "false"
>

update-procedure

Identifies the procedure/function that should be used to handle updates for a specific class-descriptor.

The nested argument elements define the argument list for the procedure/function as well as the source for each argument.

Use the custom-attribute element to pass implementation specific properties. 

<!ELEMENT update-procedure
    (documentation?, (runtime-argument | constant-argument)?, attribute*)>

The name attribute identifies the name of the procedure/function to use

The return-field-ref identifies the field-descriptor that will receive the value that is returned by the procedure/function. If the procedure/ function does not include a return value, then do not specify a value for this attribute.

The include-all-fields attribute indicates if all field-descriptors in the corresponding class-descriptor are to be passed to the procedure/ function. If include-all-fields is 'true', any nested 'argument' elements will be ignored. In this case, values for all field-descriptors will be passed to the procedure/function. The order of values that are passed to the procedure/function will match the order of field-descriptors on the corresponding class-descriptor. If include-all-fields is false, then values will be passed to the procedure/function based on the information in the nested 'argument' elements. 

<!ATTLIST update-procedure
    name CDATA #REQUIRED
    return-field-ref CDATA #IMPLIED
    include-all-fields (true | false) "false"
>

delete-procedure

Identifies the procedure/function that should be used to handle deletions for a specific class-descriptor.

The nested runtime-argument and constant-argument elements define the argument list for the procedure/function as well as the source for each argument.

Use the custom-attribute element to pass implementation specific properties. 

<!ELEMENT delete-procedure
    (documentation?, (runtime-argument | constant-argument)?, attribute*)>

The name attribute identifies the name of the procedure/function to use

The return-field-ref identifies the field-descriptor that will receive the value that is returned by the procedure/function. If the procedure/ function does not include a return value, then do not specify a value for this attribute.

The include-pk-only attribute indicates if all field-descriptors in the corresponding class-descriptor that are identified as being part of the primary key are to be passed to the procedure/function. If include-pk-only is 'true', any nested 'argument' elements will be ignored. In this case, values for all field-descriptors that are identified as being part of the primary key will be passed to the procedure/function. The order of values that are passed to the procedure/function will match the order of field-descriptors on the corresponding class-descriptor. If include-pk-only is false, then values will be passed to the procedure/ function based on the information in the nested 'argument' elements. 

<!ATTLIST delete-procedure
    name CDATA #REQUIRED
    return-field-ref CDATA #IMPLIED
    include-pk-only (true | false) "false"
>

runtime-argument

Defines an argument that is passed to a procedure/function. Each argument will be set to a value from a field-descriptor or null.

Use the custom-attribute element to pass implementation specific properties. 

<!ELEMENT runtime-argument
    (documentation?, attribute*)>

The field-ref attribute identifies the field-descriptor in the corresponding class-descriptor that provides the value for this argument. If this attribute is unspecified, then this argument will be set to null. 

<!ATTLIST runtime-argument
    field-ref CDATA #IMPLIED
    return (true | false) "false"
>

constant-argument

Defines a constant value that is passed to a procedure/function.

Use the custom-attribute element to pass implementation specific properties. 

<!ELEMENT constant-argument
    (documentation?, attribute*)>

The value attribute identifies the value that is passed to the procedure/ function. 

<!ATTLIST constant-argument
    value CDATA #REQUIRED
>

by Thomas Mahler, Daren Drummond, Brian McCallister, Armin Waibel, Thomas Dudziak, Martin Kalén