XML Deployment Descriptors

Oracle-Specific Deployment Descriptor

The Oracle-specific deployment descriptor is used for the following:

This deployment descriptor has the following structure:

<?xml version="1.0"?>
<!DOCTYPE oracle-descriptor PUBLIC "-//Oracle Corporation//DTD Enterprise 
JavaBeans 1.1//EN" "oracle-ejb-jar.dtd">

<oracle-descriptor>
  <mappings>
    <ejb-mapping> </ejb-mapping>
    <resource-ref-mapping> </resource-ref-mapping>
  </mappings>
  <run-as> </run-as>
  <persistence-provider> </persistence-provider>
  <persistence-descriptor> </persistence-descriptor>
</oracle-descriptor>

Note:
The entire DTD is listed "DTD for Oracle-Specific Deployment Descriptor".

Header

The following is the required header for all Oracle8i EJB deployment descriptors. It details the XML version and the XML DTD file.

XML Version Number

<?xml version="1.0"?>

DTD Filename

<!DOCTYPE oracle-descriptor PUBLIC "-//Oracle Corporation.//DTD Oracle 1.1//EN"
"oracle-ejb-jar.dtd">

Defining Mappings

The primary use of the Oracle-specific deployment descriptor is to map logical names used within the EJB deployment descriptor to actual names used within the Oracle8i database. The different names that can be mapped are as follows:

EJB Logical Name Description

Bean name defined in <session | entity> <ejb-name>

If a logical name was used within the <ejb-name> element instead of the JNDI name, this name should be mapped to the actual JNDI name.

EJB reference environment elements

If you provided a logical name for the target bean within <ejb-ref>, you must map this to the actual JNDI name for the EJB.

JDBC DataSource environment element

If you defined a JDBC DataSource as an environment element, you must map the <res-ref-name> to the actual JNDI name.

Security roles

If you used a logical name within the <security-role><role-name> element within the <assembly-descriptor>, this logical name must be mapped to the actual user name used within the database.

Transaction Manager

If you are using a two phase commit engine for your global transaction, specify the JNDI name for the OracleJTADataSource object that represents this database.

EJB Logical Name	Description
Bean name defined in `<session \| entity> <ejb-name>`	If a logical name was used within the `<ejb-name>` element instead of the JNDI name, this name should be mapped to the actual JNDI name.
EJB reference environment elements	If you provided a logical name for the target bean within `<ejb-ref>`, you must map this to the actual JNDI name for the EJB.
JDBC DataSource environment element	If you defined a JDBC DataSource as an environment element, you must map the `<res-ref-name>` to the actual JNDI name.
Security roles	If you used a logical name within the `<security-role><role-name>` element within the `<assembly-descriptor>`, this logical name must be mapped to the actual user name used within the database.
Transaction Manager	If you are using a two phase commit engine for your global transaction, specify the JNDI name for the OracleJTADataSource object that represents this database.

Bean Name

As described in "Bean Names", the bean name can be either a logical name or a JNDI name. If you defined a logical name, as demonstrated in the following example, you must map this name to the actual JNDI name within the <mappings> section.

Example A-7 EJB Name

The following defines a logical name of PurchaseOrder for the bean with in the EJB deployment descriptor.

   <enterprise-beans>
      <entity>
         <description>no description</description>
         <ejb-name>PurchaseOrder</ejb-name>
         <home>purchase.PurchaseOrderHome</home>
         <remote>purchase.PurchaseOrder</remote>
         <ejb-class>purchaseServer.PurchaseOrderBean</ejb-class>
         <persistence-type>Bean</persistence-type>
         <prim-key-class>java.lang.String</prim-key-class>
         <reentrant>False</reentrant>
      </entity>
   </enterprise-beans>

The PurchaseOrder logical name is mapped to its JNDI name within the <mappings> section of the Oracle-specific deployment descriptor. The following example shows how the bean name is defined in the <ejb-name> element and the corresponding JNDI name is defined in the <jndi-name> element.

<oracle-descriptor>
  <mappings>
    <ejb-mapping>
      <ejb-name>PurchaseOrder</ejb-name>
      <jndi-name>/test/purchase</jndi-name>
    </ejb-mapping>
  </mappings>
. . .
</oracle-descriptor>

EJB Reference

The EJB reference mapping is described in "Environment References To Other Enterprise JavaBeans". The structure of the mapping is the same as the bean name, demonstrated in "Bean Name".

JDBC DataSource

The JDBC DataSource connection mapping is described in "Environment References To Resource Manager Connection Factory References". You map the JDBC DataSource to the bound JNDI name with the <resource-ref-mapping> element, as follows:

<oracle-descriptor>
  <mappings>
    <resource-ref-mapping>
      <res-ref-name>jdbc/EmployeeAppDB</res-ref-name>
      <jndi-name>jdbc/OracleDataSource</jndi-name>
    </resource-ref-mapping>
  </mappings>
  ...
</oracle-descriptor>

The <res-ref-name> element contains the JDBC DataSource defined in the EJB deployment descriptor. The <jndi-name> element contains the JNDI name bound to the JDBC DataSource within the name space. This example maps the "jdbc:comp/env/jdbc/EmployeeAppDB" environment name to the JNDI name "jdbc/OracleDataSource".

Security Role

If you defined a logical name for the <role-name> within the <assembly-descriptor>, this logical name must be mapped to an actual database role or user within the Oracle-specific deployment descriptor.

For example, you define a logical role of POMGR for the role necessary for purchase order authorization within the <assembly-descriptor>. The actual database role that is allowed to make this authorization is SCOTT. The following would be the necessary mapping definition within the Oracle-specific deployment descriptor:

<mappings>
 <security-role-mapping>
   <security-role>
     <description>POMGR role mapping</description>
     <role-name>POMGR</role-name>
   </security-role>
   <oracle-role>SCOTT</oracle-role>
 </security-role-mapping>
</mappings>

As shown in Figure A-4, the <role-name> of POMGR defined in the <assembly-descriptor><security-role><role-name> is mapped to SCOTT within the Oracle-specific deployment descriptor in the <security-role-mapping> element.

Figure A-4 Security Mapping

Defining Two Phase Commit Engine for Transactions

If you are using two-phase commit for your global transaction, you must provide the UserTransaction object's JNDI name to the <transaction-manager> element. The following example specifies the UserTransaction object "/test/myUTFor2pc":

<mappings>
 ...
 <transaction-manager>
   <jndi-name>/test/myUTFor2pc<jndi-name>
 </transaction-manager>
</mappings>

Defining Run-As Identity

The <run-as> element is an EJB 1.0 element that Oracle still supports within the Oracle-specific deployment descriptor. You can define that a particular EJB will run under the specified identity with the <run-as> element. There are three types of identity that you can specify for your bean. They are as follows:

Run-As Identity Description

CLIENT_IDENTITY

The bean runs under the client's identity. This is the default.

SYSTEM_IDENTITY

The bean runs under the SYSTEM identity. This is specific to the type of environment the bean is running on. For example, on an Oracle8i database, the SYSTEM identity is equivalent to SYS.

SPECIFIED_IDENTITY

You can specify a specific identity or role that the bean runs as when invoked. This identity is specified within the <security-role> element.

Run-As Identity	Description
CLIENT_IDENTITY	The bean runs under the client's identity. This is the default.
SYSTEM_IDENTITY	The bean runs under the SYSTEM identity. This is specific to the type of environment the bean is running on. For example, on an Oracle8i database, the SYSTEM identity is equivalent to SYS.
SPECIFIED_IDENTITY	You can specify a specific identity or role that the bean runs as when invoked. This identity is specified within the `<security-role>` element.

The <method> element specifies the methods that the <run-as> definition applies to. It takes in the following definitions:

<ejb-name>: The logical name of the bean defined in the XML deployment descriptor.
<method-name>: The method name (* implies all methods) that this mode applies to within the bean.
<method-params>: If you have more than one method of this name with overloaded parameters and you want the <run-as> to apply to only one of them, specify the parameters within this element.

For example, the following defines that the price method, which requires two String parameters, in the PurchaseOrder EJB will always run as SCOTT when invoked.

  <run-as>
    <description>no description</description>
    <mode>SPECIFIED_IDENTITY</mode>
    <security-role>
      <role-name>SCOTT</role-name>
    </security-role>
    <method>
      <ejb-name>PurchaseOrder</ejb-name>
      <method-name>price</method-name>
      <methodl-params>
        <method-param>java.lang.String<method-param>
        <method-param>java.lang.String<method-param>
    </method>
  </run-as>

Note:
Specify the <security-role> element only for the SPECIFIED_IDENTITY value. The <security-role> element is ignored for both CLIENT_IDENTITY and SYSTEM_IDENTITY values.

Defining Container-Managed Persistence

If you have chosen to have the container manage the persistent variables for your entity bean, you need to provide the name of the persistence provider and map each persistence provider to the container-managed persistent bean. This version supports the Oracle Persistence Service Interface Reference Implementation (PSI-RI) persistence manager. Using this manager, you must define the mappings of the persistent fields to the database.

Persistence Provider

The persistence provider controls the management of all container-managed fields. It defines how to map the fields within the bean to corresponding persistent storage. It also defines how to save and update these fields from the bean to the storage.

You define the Oracle PSI-RI persistence provider is defined within the <persistence-provider> element. The following elements describe the persistence provider:

Persistence Provider Elements Description

<description>

Gives a description of the provider.

<persistence-name>

Defines a logical name for the provider. In this release, only Oracle PSI-RI is supported.

<persistence-deployer>

Provides the Java class used for the persistence maintenance. This class is called by Oracle's container when persistence is required.

Persistence Provider Elements	Description
`<description>`	Gives a description of the provider.
`<persistence-name>`	Defines a logical name for the provider. In this release, only Oracle PSI-RI is supported.
`<persistence-deployer>`	Provides the Java class used for the persistence maintenance. This class is called by Oracle's container when persistence is required.

The following defines the Oracle PSI-RI persistence provider. The logical name is defined as "PSI-RI" and the class called for persistence management is oracle.aurora.ejb.persistence.ocmp.OcmpEntityDeployer.

<persistence-provider>
  <description> specifies a type of persistence manager </description>
  <persistence-name>psi-ri</persistence-name>
  <persistence-deployer>oracle.aurora.ejb.persistence.ocmp.OcmpEntityDeployer

  </persistence-deployer>
</persistence-provider>

Persistence Fields

The persistent fields were defined in the EJB deployment descriptor in the <cmp-field> elements. Each of these <cmp-field> elements need to be persistently managed by your provider. You define a single provider for all <cmp-field> elements within a single bean through the <persistence-descriptor> element. You define the provider for the bean through the combination of the logical names for the bean and for the provider within the <persistence-descriptor>. These fields are as follows:

Persistence Elements Description

<description>

Provides a text description of the persistence elements.

<ejb-name>

The EJB that contains the persistent fields. This would be the same <ejb-name> for the entity bean that defined the <cmp-field> elements.

<persistence-name>

The logical name of the persistence provider defined within the <persistence-provider> <persistence-name> element.

Persistence Elements	Description
`<description>`	Provides a text description of the persistence elements.
`<ejb-name>`	The EJB that contains the persistent fields. This would be the same `<ejb-name>` for the entity bean that defined the `<cmp-field>` elements.
`<persistence-name>`	The logical name of the persistence provider defined within the `<persistence-provider> <persistence-name>` element.

For example, to define that Oracle PSI-RI manages all persistent fields within the purchase order bean, you specify the logical bean name, PurchaseOrder, and the logical persistence provider name, Oracle PSI-RI, within the following fields:

<persistence-descriptor>
  <ejb-name>PurchaseOrder</ejb-name>
  <persistence-name>psi-ri</persistence-name>
  . . . 
</persistence-descriptor>

The Oracle PSI-RI maps the persistent data types to database rows. It uses SQL to update the persistent fields between the bean and the database. Each persistent data type is mapped to the Oracle SQLJ data types documented in the Oracle8i SQLJ Developer's Guide and Reference. The data type mapping is documented fully on Table 5-1, "Type Mappings for Supported Host Expression Types" on page 5-2. The only restrictions is that the following data types are not supported:

Table A-2 Unsupported Java Types for Persistent Variables

	Java Type	Oracle Types Definition	Oracle Datatype
SQLJ stream classes	sqlj.runtime.BinaryStream	LONGVARBINARY	LONG RAW
	sqlj.runtime.AsciiStream	LONGVARCHAR	LONG
	sqlj.runtime.UnicodeStream	LONGVARCHAR	LONG
Oracle extensions	oracle.sql.ROWID	ROWID	ROWID
	oracle.sql.BLOB	BLOB	BLOB
	oracle.sql.CLOB	CLOB	CLOB
Query result objects	java.sql.ResultSet	CURSOR	CURSOR
Query result objects	SQLJ iterator objects	CURSOR	CURSOR

If you decide to use PSI-RI, you must define the following within the <psi-ri> element, which exists within the <persistence-descriptor>.

Persistence Elements Description

<schema>

Define the schema where the database table resides.

<table>

Define the table where the persistent fields are saved.

<attr-mapping>

Define each container-managed field and its corresponding table row within this element.

<field-name>

Define the container-managed field name as defined within the bean.

<column-name>

Define the database row where the <field-name> is saved.

Persistence Elements	Description
`<schema>`	Define the schema where the database table resides.
`<table>`	Define the table where the persistent fields are saved.
`<attr-mapping>`	Define each container-managed field and its corresponding table row within this element.
`<field-name>`	Define the container-managed field name as defined within the bean.
`<column-name>`	Define the database row where the `<field-name>` is saved.

Note:
Before you can deploy this bean, the table and its appropriate rows must exist within the schema.

For example, the following <psi-ri> maps the customer bean persistence 
fields--primary key, customer name, and address--to the customers table within 
SCOTT's schema
<persistence-descriptor>
  <ejb-name>PurchaseOrder</ejb-name>
  <persistence-name>psi-ri</persistence-name>
  <psi-ri>
      <schema>SCOTT</schema>
      <table>customers</table>
      <attr-mapping>
        <field-name>custid</field-name>
        <column-name>cust_id</column-name>
      </attr-mapping>
      <attr-mapping>
        <field-name>name</field-name>
        <column-name>cust_name</column-name>
      </attr-mapping>
      <attr-mapping>
        <field-name>addr</field-name>
        <column-name>cust_addr</column-name>
      </attr-mapping>
  </psi-ri>
</persistence-descriptor>

If the persistent fields that you define are objects, you can ask Oracle PSI-RI to serialize some or all fields defined as persistent into a single database column. This column must be defined as either long Raw or Raw.

Note:
There is a limitation of 4 KB for any Raw columns.

You define the fields and the destination column within the <serialize-mapping> element. The persistent fields are mapped either within the <attr-mapping> or the <serialize-mapping> elements, but not in both.

The following example serializes the customer bean persistent fields--customer name, and address--and save them into the custinfo column. Normally, you would do this if you wanted to serialize an object.

Note:
There is one restriction: you cannot include the primary key within the <serialize-mapping> element. It hinders finding an object through findByPrimaryKey.

<persistence-descriptor>
  <ejb-name>PurchaseOrder</ejb-name>
  <persistence-name>psi-ri</persistence-name>
  <psi-ri>
   <schema>SCOTT</schema>
   <table>customers</table>
   <serialize-mapping>
    <field-name>name</field-name>
    <field-name>addr</field-name>
    <column-name>custinfo</column-name>
   </serialize-mapping>
  </psi-ri>
</persistence-descriptor>


Example A-8  Container-Managed Persistence

The following is the full example for defining container-managed persistence for the customer example.

<persistence-provider>
  <description>use the simple CMP provider</description>
  <persistence-name>psi-ri</persistence-name>
  <persistence-deployer>oracle.aurora.ejb.persistence.ocmp.OcmpEntityDeployer

  </persistence-deployer>
</persistence-provider>

<persistence-descriptor>
  <ejb-name>customerbean</ejb-name>
  <persistence-name>psi-ri</persistence-name>
  <psi-ri>
      <schema>SCOTT</schema>
      <table>customers</table>
      <attr-mapping>
        <field-name>custid</field-name>
        <column-name>cust_id</column-name>
      </attr-mapping>
      <attr-mapping>
        <field-name>name</field-name>
        <column-name>cust_name</column-name>
      </attr-mapping>
      <attr-mapping>
        <field-name>addr</field-name>
        <column-name>cust_addr</column-name>
      </attr-mapping>
  </psi-ri>
</persistence-descriptor>
</oracle-descriptor>

EJB Client JAR Section

One of the tasks that the deployejb tool performs is to create a JAR file with the required stubs and skeletons, which is used by the client at execution time. Unless this JAR file name is specified in the <ejb-client-jar> element in the XML deployment descriptor, the default name for this JAR file is server_generated.jar. This JAR file must be included in the CLASSPATH for client execution.

The following defines that deployejb should create the client's stubs and skeletons in myClient.jar:

<ejb-client-jar>myClient.jar</ejb-client-jar>