OJB
Downloads
Documentation
Development
Translated (Web)
|
Introduction - repository syntax |
The syntax of the OJB repository xml files is defined by the
repository.dtd .
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:
-
the repository.xml.
Main file for metadata declaration. This file is split into several sub files
using xml-Entity references.
-
the repository_database.xml.
This file contains the mapping information for database/connection handling.
-
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.
-
the repository_user.xml.
This file contains mappings for the tutorial applications
and may be used to hold further user defined class mappings.
-
the repository_junit.xml.
This file contains mapping information for the OJB JUnit regression
test suite. In production environments these tables are not needed.
-
other repository_junit_XYZ.xml
More junit test mapping. In production environments these tables are not needed.
-
There are some more files, for more information see comment in appropriate
xml-file.
|
Repository semantics |
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.
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? )
>
|  |
 |  |  |
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.
The platform
attribute is used to define the specific RDBMS Platform. This attribute
corresponds to a org.apache.ojb.broker.platforms.PlatformXXXImpl
class.
The jdbc-level
attribute is used to specify the Jdbc compliance level of the used Jdbc driver.
The eager-release
attribute was adopt to solve a problem occured when using OJB within JBoss
(3.0 <= version < 3.2.2, seems to be fixed in jboss 3.2.2). Only use
within JBoss.
The batch-mode
attribute allow to set batch mode modus global from the used connection.
It is also possible to change batch mode at runtime, using the
PB.serviceConnectionManager.setBatchMode(...) method.
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 - Set autoCommit explicitly to
true when a connection was created
and temporary set to false when necessary (default mode).
-
2 - Set autoCommit explicitly to
false when a connection was 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 four
attributes driver , protocol , subprotocol ,
and dbalias used for Jdbc DriverManager based construction
of Jdbc Connections must not be declared.
The username
and password
attributes are used as credentials for obtaining a jdbc connections.
If users don't want to keep this information the
repository.xml file, they could pass user/password
using a PBKey to obtain a PersistenceBroker
 |  |  |
 |
<!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 ) "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
>
|  |
 |  |  |
|
connection-pool |
The connection-pool element specifies the connection pooling
parameter.
 |  |  |
 |
<!ELEMENT connection-pool (
documentation? )
>
|  |
 |  |  |
Valid attributes for the connection-pool element are:
maxActive is the maximum
number of connections that can be borrowed from the pool at one time. When
non-positive, there is no limit.
maxIdle controls the maximum
number of connections that can sit idle in the pool at any time. When
non-positive, there is no limit
maxWait - the maximum time
block to get connection instance from pool, after that exception is thrown.
When non-positive, block till last judgement
whenExhaustedAction
- 0 - fail when pool is exhausted
- 1 - block when pool is exhausted
- 2 - grow when pool is exhausted
testOnBorrow : when
true the pool will attempt to validate each object before it
is returned from the pool.
testOnReturn set to
true will force the pool to attempt to validate each object before
it is returned to the pool.
testWhileIdle indicates
whether or not idle objects should be validated. Objects that fail to validate
will be dropped from the pool
timeBetweenEvictionRunsMillis
indicates how long the eviction thread should sleep before "runs" of examining idle
objects. When non-positive, no eviction thread will be launched.
minEvictableIdleTimeMillis
specifies the minimum amount of time that a connection may sit idle in the
pool before it is eligable for eviction due to idle time. When non-positive,
no connection will be dropped from the pool due to idle time alone (depends
on timeBetweenEvictionRunsMillis > 0)
numTestsPerEvictionRun
- the number of connections to examine during each run of the idle object
evictor thread (if any)
validationQuery
allows to specify a validation query used by the ConnectionFactory implementations
using connection pooling, to test a requested connection (e.g. "select 1 from dual")
before leave the pool (used by ConnectionFactoryDBCPImpl
and ConnectionFactoryPooledImpl ).
If not set, only connection.isClosed()
will have been called before the connection was delivered.
logAbandoned is only
supported when using org.apache.ojb.broker.accesslayer.ConnectionFactoryDBCPImpl
ConnectionFactory implementation.
Then it is a flag to log stack traces for application code which abandoned
a Statement or Connection. Defaults to false. Logging of
abandoned Statements and Connections adds overhead for
every Connection open or new Statement because a
stack trace has to be generated.
removeAbandoned /
removeAbandonedTimeout
When using org.apache.ojb.broker.accesslayer.ConnectionFactoryDBCPImpl
ConnectionFactory implementation, the removeAbandoned flag
controls the removal of abandoned connections if they exceed the
removeAbandonedTimeout . Set to true or false, default false.
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.
 |  |  |
 |
<!ATTLIST connection-pool
maxActive 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
logAbandoned ( true | false ) #IMPLIED
removeAbandoned ( true | false ) #IMPLIED
removeAbandonedTimeout CDATA #IMPLIED
>
|  |
 |  |  |
|
class-descriptor |
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? )
)
>
|  |
 |  |  |
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 specifies the transactional isolation to be used for this
class on ODMG-level (does not touch the jdbc-connection isolation level).
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.
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 TODO
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. It's set to false by default.
 |  |  |
 |
<!ATTLIST class-descriptor
class ID #REQUIRED
isolation-level (read-uncommitted | read-committed |
repeatable-read | serializable | optimistic) "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"
>
|  |
 |  |  |
|
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.
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.
If the PersistentFieldDirectAccessImpl is used there must be an attribute
in the persistent class with this name.
If the PersistentFieldIntrospectorImpl is used there must be a JavaBeans
compliant property of this name.
More info see javdoc of the PersistentField implementation classes
in ...broker.metadata.fieldaccess package.
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 optional 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.
The primarykey specifies if the column is a primary key column.
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 are automatically generated by OJB.
The sequence-name attribute can be used to state explicitly a sequence
name used by the sequence manager implementations. Check the docs/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 was not set.
The locking attribute is set to true if the persistent attribute is
used for optimistic locking. can only be set for TIMESTAMP and INTEGER
columns.
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.
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.
"readonly" marks fields that 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.
 |  |  |
 |
<!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"
>
|  |
 |  |  |
|
collection-descriptor |
A collection-descriptor contains mapping info for a Collection- or
Array-attribute of a persistent class that contains persistent
entity Objects.
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.
If the PersistentFieldDefaultImpl is used there must be an attribute
in the persistent class with this name.
If the PersistentFieldPropertyImpl is used there must be a JavaBeans
compliant property of this name.
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.
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.
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.
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
object and collection references on instance loading.
The auto-retrieve attribute specifies whether OJB automatically retrieves
this attribute on loading the persistent object.
If set to false the persistent attribute is set to null. In this case the
user is responsible to fill the persistent attribute.
The auto-update attribute specifies whether OJB automatically stores
this reference attribute on storing the persistent object.
This attribute must be set to false if using the OTM, ODMG or JDO layer.
The auto-delete attribute specifies whether OJB automatically deletes
this reference attribute on deleting the persistent object.
This attribute must be set to false if using the OTM, ODMG or JDO layer.
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 (true | false) "false"
auto-delete (true | false) "false"
otm-dependent (true | false) "false"
>
|  |
 |  |  |
|
|
|