persistent.dtd 

Definition

A document type definition (DTD) that describes how you specify information about the database mappings of container-managed entity beans.

Use

The GENERATE_PERSISTENT shell command from the EJB shell command group generates a default persistent.xml for your application. For more information, see Generating persistent.xml for Container-Managed Entity Beans.

Structure

The persistent.dtd defines the following elements:

The usage of each element is explained below:

 

<!--
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.
-->
<!ELEMENT persistent-ejb-map (switch-off-verification?, create-tables-at-deploy?, locking?, db-properties?, entity-beans?, relationships?)>

 

<!--
If specified, during deployment it disables the verification whether the O/R mapping is correct. For more information, see Object/Relational Mapping Rules.
-->
<!ELEMENT switch-off-verification EMPTY>

 

<!--
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.
-->
<!ELEMENT create-tables-at-deploy EMPTY>

 

<!--
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. 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. In this case, the application can use the EJBLocking API to make an explicit locking in the Enqueue Server.
-->
<!ELEMENT locking EMPTY>

 

<!--
Specifies the type of locking.
-->
<!ATTLIST locking type (Administrative|Table|Local) "Table">

 

<!--
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 DTD.
Example:
    <db-properties>
        <data-source-name>myDataSource</data-source-name>
        <database-vendor>SAPDB</database-vendor>
    </db-properties>
-->
<!ELEMENT db-properties (data-source-name, database-vendor?)>

 

<!--
The name of the data source used to establish a connection to the database.
-->
<!ELEMENT data-source-name (#PCDATA)>

 

<!--
The name of the database used. If this element is omitted, the system marks the database as unknown.
-->
<!ELEMENT database-vendor EMPTY>

 

<!--
The possible values of the database used.
-->
<!ATTLIST database-vendor name (DB2_UDB|DB2_UDB_AS400|DB2_UDB_OS390|MS_SQL_SERVER|ORACLE|SAPDB) #REQUIRED>

 

<!--
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 DTD.
-->
<!ELEMENT entity-beans (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>
-->
<!ELEMENT entity-bean (ejb-name, table-name, (read-only | select-for-update)?, field-map*, finder-descriptor*)>

 

<!--
The name of the enterprise bean, as defined in ejb-jar.xml.
-->
<!ELEMENT ejb-name (#PCDATA)>

 

<!--
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.
-->
<!ELEMENT table-name (#PCDATA)>

 

<!--
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.
-->
<!ELEMENT read-only EMPTY>

 

<!--
Specifies that the entity bean will use database locking.
-->
<!ELEMENT select-for-update EMPTY>

 

<!--
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.
-->
<!ELEMENT field-map (field-name, (column|dv-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.
-->
<!ELEMENT mutable EMPTY>

 

<!--
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.
-->
<!ATTLIST field-map key-type (NoKey|PrimaryKey|UniqueKey) "NoKey">

 

<!--
This element exists only if the cmp-field is mapped to a single column in the database table.
-->
<!ELEMENT column (column-name)>

 

<!--
Describes the database mapping of a cmp-field to a set of columns.
-->
<!ELEMENT dv-column (subfield-name, column-name)>

 

<!--
The name of the field in the dependent-value class that is described.
-->
<!ELEMENT subfield-name (#PCDATA)>

 

<!--
The name of the column in the database table to which this field is mapped.
-->
<!ELEMENT column-name (#PCDATA)>

 

<!--
The name of the cmp-field whose mapping is described.
-->
<!ELEMENT field-name (#PCDATA)>

 

<!--
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.
-->
<!ELEMENT finder-descriptor (criteria?, method-name, method-params, switch-off-storing?, load-selected-objects?, lazy-loading?, fetch-size?, ql-2.1-compatible?)>

 

<!--
Defines the select statement that is going to be executed in this finder method. Use format ?i to specify the number of the parameter that should be used instead of the statement. 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>
If this criteria describes EJB2.0, it is not recommended that you overwrite the default statement that was generated by the QL parser. It is forbidden to change the default SQL statements of QL queries of select methods. If this element is specified for select methods, it will be ignored.
The system will not detect whether the criteria is not correct, or whether it returns the wrong result type during the application’s deployment. However, the system will throw an exception at runtime when you try to execute the incorrect criteria.
-->
<!ELEMENT criteria (#PCDATA)>

 

<!--
The name of the finder/select method.
-->
<!ELEMENT method-name (#PCDATA)>

 

<!--
The parameters of the finder/select method.
-->
<!ELEMENT method-params (method-param*)>

<!ELEMENT method-param (#PCDATA)>

 

<!--
Switches off data storing before this finder/select method is executed.
-->
<!ELEMENT switch-off-storing EMPTY>

 

<!--
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.
-->
<!ELEMENT load-selected-objects EMPTY>

 

<!--
Specifies the kind of lock that must be set on the bean – read or write.
-->
<!ATTLIST load-selected-objects lock (read|write) #IMPLIED>

 

<!--
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.)
-->
<!ELEMENT lazy-loading EMPTY>

 

<!--
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.
-->
<!ELEMENT fetch-size (#PCDATA)>

 

<!--
By default, each query is QL 2.0 compatible. If you need to use ORDER BY, aggregate functions, and so on, use this element to indicate that the QL is 2.1 compatible.
If this element exists, the query is considered QL 2.1 compatible. This element is taken into account only if the specified method is an EJB 2.0 finder or select method.
-->
<!ELEMENT ql-2.1-compatible EMPTY>

 

<!--
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>
-->
<!ELEMENT relationships (table-relation*)>

<!ELEMENT table-relation (help-table?, table-relationship-role, table-relationship-role)>

 

<!--
In 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.
-->
<!ELEMENT help-table (#PCDATA)>

 

<!--
Describes the relations in the bean’s database table.
-->
<!ELEMENT table-relationship-role (ejb-name, cmr-field?, fk-column*)>

 

<!--
The type of the column(s) that participate in the relationship. The default value is PrimaryKey.
-->
<!ATTLIST table-relationship-role key-type (NoKey|PrimaryKey|ForeignKey) "PrimaryKey">

 

<!--
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.
-->
<!ELEMENT fk-column (column-name, pk-field-name)>

 

<!--
The name of the foreign key column.
-->
<!ELEMENT column-name (#PCDATA)>

 

<!--
The name of the referenced primary key cmp-field as specified in ejb-jar.xml.
-->
<!ELEMENT pk-field-name (#PCDATA)>

 

<!--
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.
-->
<!ELEMENT cmr-field (#PCDATA)>