An XML schema that describes how you specify information about the database mappings of container-managed entity beans.
The persistent.xsd has the following structure:
XML Schema Description
Schema Element / Attribute |
Description |
persistent-ejb-map |
The root element of this deployment descriptor. It contains information about specific database properties along with information concerning the entity beans and the different relationships among them. |
switch-off-verification |
If specified, during deployment it disables the verification whether the O/R mapping is correct. Used in: persistent-ejb-map. |
create-tables-at-deploy |
Deprecated. If this element exists and the database tables are not created, during deployment the system will create the tables exactly as described in persistent.xml. If the database tables are already created, the system will not create new tables or modify the existing ones. If the O/R mapping is not specified correctly in persistent.xml, the database tables will not be created correctly, too. We therefore recommend that you switch on O/R mapping verification, that is, omit the switch-off-verification element in persistent.xml. Used in: persistent-ejb-map. |
no-empty-tables |
If used this element points that the table of the bean will never be empty. Used in: persistent-ejb-map, finder-descriptor. |
locking |
This element is used to control concurrent access from different transactions to the entity beans. ● The Table locking automatically locks the entity beans in the Enqueue Server and in this way ensures that all applications that run in the cluster and use common data have common locks. ● Deprecated. The Administrative locking is deprecated and should not be used for applications. ● Local locking can only be used when there is only one server running, because it does not synchronize the locks on multiple servers that work in a cluster. That is, the Local locking synchronizes the concurrent access on one server only, and does not use the Enqueue Server to keep the locks. Used in: persistent-ejb-map. Contains: type |
type |
Specifies the type of locking. Possible values: Table or Local. Used in: locking. |
db-properties |
Describes the properties of the database used. These properties are valid for the database mappings of the entire abstract schema. Note: This element is mandatory for persistent.xml, no matter whether it is specified as optional in the root element schema. Example: <db-properties> <data-source-name>myDataSource</data-source-name> <database-vendor>SAPDB</database-vendor> </db-properties> Used in: persistent-ejb-map. Contains: data-source-name, for-native-use-only, database-vendor, TargetSQL. |
data-source-name |
The name of the data source used to establish a connection to the database. Used in: db-properties. |
for-native-use-only |
Specifies that through the Data Source only native queries will be executed (non-Open SQL). Used in: db-properties. |
database-vendor |
The name of the database used. Used in: db-properties. Contains: name. |
name |
The database to be used. Possible values are: ● DB2_UDB ● DB2_UDB_AS400 ● DB2_UDB_OS390 ● MS_SQL_SERVER ● ORACLE ● SAPDB Used in: database-vendor |
TargetSQL |
The SQL (generated by the EJB Container) with which you want your SQL to be compatible. Used in: db-properties. Contains: name. |
name |
Possible values are: ● DB2_UDB ● DB2_UDB_AS400 ● DB2_UDB_OS390 ● MS_SQL_SERVER ● ORACLE ● MAXDB ● UNKNOWN ● OpenSQL Used in: TargetSQL. |
entity-beans |
Contains a list of all container-managed entity beans to which the abstract schema applies, the entity bean properties, and database mappings. Note: This element is mandatory for persistent.xml, no matter whether it is specified as optional in the root element schema. Used in: persistent-ejb-map. Contains: entity-bean |
entity-bean |
Example: <entity-bean> <ejb-name>myEntityBean</ejb-name> <table-name>myTable</table-name> <field-map key-type="PrimaryKey"> <field-name>id</field-name> <column> <column-name>id_0</column-name> </column> </field-map> <field-map> <field-name>name</field-name> <column> <column-name>name_0</column-name> </column> </field-map> <field-map> <field-name>order</field-name> <column> <column-name>order_0</column-name> </column> </field-map> <field-map> <field-name>item</field-name> <column> <column-name>item_0</column-name> </column> </field-map> <finder-descriptor> <criteria>select name_0,order_0 from myTable where item_0=?1</criteria> <method-name>findByOrder</method-name> <method-params> <method-param>java.lang.String</method-param> </method-params> <switch-off-storing/> </finder-descriptor> <finder-descriptor> <criteria>select name_0,order_0 from myTable where order_0=?1 AND order_0=?2</criteria> <method-name>findByOrderAndItem</method-name> <method-params> <method-param>int</method-param> <method-param>java.lang.String</method-param> </method-params> <switch-off-storing/> </finder-descriptor> <finder-descriptor> <method-name>ejbSelectAggFunction</method-name> <method-params/> <ql-2.1-compatible/> </finder-descriptor> </entity-bean> Used in: entity-beans. Contains: ejb-name, table-name, read-only, field-map, finder-descriptor. |
ejb-name |
The name of the enterprise bean, as defined in ejb-jar.xml. Used in: entity-bean. |
table-name |
The name of the database table in which the entity bean persistent data is stored. Each EJB from the abstract schema is stored in a separate table. Used in: entity-bean. |
read-only |
This element exists only when the entity bean is not allowed to update the data in the database. The bean is allowed only to read data from the database. Used in: entity-bean. |
field-map |
Describes the database mappings between cmp-fields and columns in the database. If the cmp-field is a dependent-value field and if it contains an empty constructor, then the database mapping of its fields that are declared public can be declared in the dv-column element, and the cmp-field is mapped to multiple columns. However, this is not obligatory. Both dependent-value and non-dependent-value cmp-field mappings can be described in the column element. In this case, the dependent-value cmp-field, is serialized and stored in a java.sql.Types.BLOB column. Used in: entity-bean. Contains: key-type, field-name, column, mutable. |
key-type |
Specifies the type of the column or the set of columns in which the values of the cmp-field are stored. The default value is NoKey. Used in: field-map. |
field-name |
The name of the cmp-field whose mapping is described. Used in: field-map. |
column |
This element exists only if the cmp-field is mapped to a single column in the database table. Used in: field-map. Contains: column-name. |
column-name |
The name of the column in the database table to which this field is mapped. Used in: column. |
mutable |
This element is relevant only for dependent-value fields. When specified, this property allows the inner structure of the dependent-value field to be changed, that is, the EJB Container will make a copy of the objects each time a corresponding get or set method is executed. Used in: field-map. |
finder-descriptor |
If the beans are developed according to the Enterprise JavaBeans™ v.1.1 Specification, this element describes the SQL select statements for the bean’s finder methods. If the beans are developed according to the Enterprise JavaBeans™ v.2.0 Specification, this element describes the bean’s SQL finder methods, which differ from the default finder statements that are generated by the QL parser. This element also specifies whether data storing for the finder and select methods is switched on or off, which of the bean’s fields will be retrieved from the database, and whether the QL is 2.1 compatible. Used in: entity-bean. Contains: no-empty-tables, criteria, method-name, method-params, switch-off-storing, load-selected-objects, lazy-loading, fetch-size, ql-2.1-compatible, verify-single-finder. |
criteria |
This element defines an SQL string that is going to be executed as a select statement in the corresponding finder method. The element cannot be used if the finder-descriptor element describes a select method. If this element is specified for a select method, it will be ignored. Use ?i to refer to the parameter that should be replaced. Parameters are numbered from 1 to N. Example: <criteria>select name_0,order_0 from myTable where order_0=?1 AND order_0=?2</criteria> In order to be portable, an application should use EJB QL syntax. The EJB Container will consider the criteria as a native SQL statement, will not parse or verify the correctness of the statement, and will execute/send it directly to the underlying data source. - Unchecked SQL statements may lead to a runtime error. - If you use the <criteria> element, you must also specify the database vendor in the <database-vendor> element as native database connections will be used. Used in: finder-descriptor. |
method-name |
The name of the finder/select method. Used in: finder-descriptor. |
method-params |
The parameters of the finder/select method. Used in: finder-descriptor. Contains: method-param |
method-param |
The name of the method parameter. Used in: method-params |
switch-off-storing |
Switches off data storing before this finder/select method is executed. Used in: finder-descriptor. |
load-selected-objects |
If this element exists, the bean is locked and when the finder/select method is executed, all fields of the bean are loaded from the database. Otherwise, if the element is omitted, only the primary key fields are retrieved from the database. The locking ensures that, until the end of the transaction, the loaded data will remain consistent with the last state of the data in the database and avoids the reloading of the same data when the transaction uses it later again. Used in: finder-descriptor. Contains: lock. |
lock |
Specifies the kind of lock that must be set on the bean: read or write. Used in: load-selected-objects. |
lazy-loading |
Specifies whether all entities selected by the query will be fetched to the EJB Container in the finder method. If this property is specified, the entities will be loaded on demand when the collection returned by the finder method is iterated (gradually, at the same rate as they are iterated.) Used in: finder-descriptor. |
fetch-size |
The number of rows that will be transferred at a time from the database while iterating the result from the execution of the finder/select query. Use this property when you can determine the approximate number of entities that you will need for the execution of your query. If the value is set to 0 or the tag is omitted, the JDBC driver automatically determines the fetch size. By default, this element is omitted. Used in: finder-descriptor. |
ql-2.0-compatible |
If this element exists, the query is considered QL 2.0 compatible. This element is taken into account only if the specified method is an EJB 2.0 finder or select method. Used in: finder-descriptor. |
ql-2.1-compatible |
By default, each query is QL 2.1 compatible. If this element exists, the query is considered QL 2.1 compatible. Used in: finder-descriptor. |
verify-single-finder |
If you use this element, this will mark that there has to be a check if the result of execution of the founder is unique. That is the container executes next twice on the JDBC result set. Used in: finder-descriptor. |
relationships |
Describes the relations in the database table. Example: <relationships> <table-relation> <help-table>myHelpTable</help-table> <table-relationship-role key-type="PrimaryKey"> <ejb-name>myReferencingBean</ejb-name> <cmr-field>myCmrField</cmr-field> <fk-column>myFKColumn</fk-column> </table-relationship-role> <table-relationship-role key-type="PrimaryKey"> <ejb-name>myReferencedBean</ejb-name> <cmr-field>myOtherCmrField</cmr-field> <fk-column>myOtherFKColumn</fk-column> </table-relationship-role> </table-relation> <table-relation> <help-table>AEJB_BEJB_2</help-table> <table-relationship-role key-type="PrimaryKey"> <ejb-name>AEJB</ejb-name> <cmr-field>b</cmr-field> <fk-column> <column-name>id_0_0_2</column-name> <pk-field-name>id</pk-field-name> </fk-column> </table-relationship-role> <table-relationship-role key-type="PrimaryKey"> <ejb-name>BEJB</ejb-name> <cmr-field>a</cmr-field> <fk-column> <column-name>id_0_1_2</column-name> <pk-field-name>id</pk-field-name> </fk-column> </table-relationship-role> </table-relation> <table-relation> <table-relationship-role key-type="NoKey"> <ejb-name>BeanEJB</ejb-name> <cmr-field>a1</cmr-field> <fk-column> <column-name>id_0_0</column-name> <pk-field-name>id</pk-field-name> </fk-column> </table-relationship-role> <table-relationship-role key-type="PrimaryKey"> <ejb-name>AEJB</ejb-name> </table-relationship-role> </table-relation> </relationships> Used in: persistent-ejb-map. Contains: table-relation |
table-relation |
Describes the relation. Used in: relationships. Contains: help-table, table-relationship-role, table-relationship-role. |
help-table |
In the case of an M:M relation, it is obligatory that you use a help table; this element exists when an M:M relation is described. The value of this element is the name of the help table. Used in: table-relation. |
table-relationship-role |
Describes the relations in the bean’s database table. Used in: table-relation. Contains: key-type, ejb-name, cmr-field, fk-column |
key-type |
The type of the column(s) that participate in the relationship. The default value is PrimaryKey. Used in: table-relationship-role. |
ejb-name |
The name of the EJB. Used in: table-relationship-role. |
cmr-field |
The name of the cmr-field as described in ejb-jar.xml. This element does not exist if a unidirectional relationship is described and the table-relationship-role element describes this part of the relation, which has no cmr-field. Used in: table-relationship-role. |
fk-column |
If the value of the key-type element is NoKey or ForeignKey, this element is used to describe a foreign (logical) key column and its reference to the corresponding primary key cmp-field. In such cases, the <fk-column> elements are mandatory. If the key-type is PrimaryKey, the <fk-column> element should exist only if the relationship has multiplicity many-to-many. The <fk-column> element describes the referenced columns in the help table. Used in: table-relationship-role. Contains: column-name, pk-field-name. |
column-name |
The name of the foreign key column. Used in: fk-column. |
pk-field-name |
The name of the referenced primary key cmp-field as specified in ejb-jar.xml. Used in: fk-column. |