Show TOC Start of Content Area

Object documentation persistent.xsd  Locate the document in its SAP Library structure

Use

An XML schema that describes how you specify information about the database mappings of container-managed entity beans.

Structure

The persistent.xsd has the following structure:

This graphic is explained in the accompanying text

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.

 

End of Content Area