Oracle8i Enterprise JavaBeans Developer's Guide and Reference Release 3 (8.1.7) Part Number A83725-01 |
|
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>
The following is the required header for all Oracle8i EJB deployment descriptors. It details the XML version and the XML DTD file.
<?xml version="1.0"?>
<!DOCTYPE oracle-descriptor PUBLIC "-//Oracle Corporation.//DTD Oracle 1.1//EN" "oracle-ejb-jar.dtd">
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:
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.
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>
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".
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
".
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.
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>
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:
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>
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.
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:
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>
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:
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:
Java Type | Oracle Types Definition | Oracle Datatype | |
---|---|---|---|
SQLJ stream classes |
|||
Oracle extensions |
|||
Query result objects |
|||
If you decide to use PSI-RI, you must define the following within the <psi-ri>
element, which exists within the <persistence-descriptor>
.
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.
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.
<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>
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>
|
Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|