OC4J-specific Deployment Descriptor for EJB

The OC4J-specific deployment descriptor contains extended deployment information for entity beans and the security for these beans. The major element structure of interest within this deployment descriptor is as follows:

<orion-ejb-jar deployment-time=... deployment-version=...> 
    <enterprise-beans>
        <entity-deployment ...></entity-deployment>
    </enterprise-beans>
    <assembly-descriptor>
        <security-role-mapping ...></security-role-mapping>
        <default-method-access></default-method-access>
    </assembly-descriptor>
</orion-ejb-jar>

Each section under the <orion-ejb-jar> main tag has its own purpose. These are described in the following sections:

• Enterprise Beans Section

• Assembly Descriptor Section

Enterprise Beans Section

The <enterprise-beans> section defines additional deployment information for all EJB. There is a section for each type of EJB.

The following sections describe the elements of interest (entity beans with container-managed persistence) within the <enterprise-beans> element:

• Entity Bean Section

• Method Definition

Entity Bean Section

The <entity-deployment> section provides additional deployment information for an entity bean deployed within this JAR file. The <entity-deployment> section contains the following structure:

<entity-deployment call-timeout=... clustering-schema=...
        copy-by-value=... data-source=... exclusive-write-access=...
        do-select-before-insert=... isolation=...
        location=... locking-mode=... max-instances=... min-instances=... 
        max-tx-retries=... tx-retry-wait=... update-changed-fields-only=... 
        name=... pool-cache-timeout=...
        table=... validity-timeout=... force-update=... 
        wrapper=... local-wrapper=... delay-updates-until-commit=...
        findByPrimaryKey-lazy-loading=... >
    <ior-security-config>
        <transport-config>
            <integrity></integrity>
            <confidentiality></confidentiality>
            <establish-trust-in-target></establish-trust-in-target>
            <establish-trust-in-client></establish-trust-in-client>
        </transport-config>
        <as-context>
            <auth-method></auth-method>
            <realm></realm>
            <required></required>
        </as-context>
        <sas-context>
            <caller-propagation></caller-propagation>
        </sas-context>
    </ior-security-config>
    <primkey-mapping>
        <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
                    persistence-type=...></cmp-field-mapping>
    </primkey-mapping>
    <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
                    persistence-type=...> </cmp-field-mapping>
    <finder-method partial=... query=... lazy-loading=... prefetch-size=... >
        <method></method>
    </finder-method>
    <env-entry-mapping name=...></env-entry-mapping>
    <ejb-ref-mapping location=... name=... />
    <resource-ref-mapping location=... name=... >
        <lookup-context location=...>
            <context-attribute name=... value=... />
        </lookup-context>
    </resource-ref-mapping>
    <resource-env-ref-mapping location=... name=... />
</entity-deployment>

Each of the element groups are discussed in the following sections of the OC4J documentation set:

• Entity bean examples, which include the <entity-deployment> element, are described in Chapter 1, "Understanding Entity Beans With Container-Managed Persistence", Chapter 3, "Understanding Orion CMP Support in OC4J" and Chapter 5, "Configuring an EJB 2.0 Entity Bean With Container-Managed Persistence" of this book.

• The <io-security-config> element configures CSIv2 security policies for interoperability, which is discussed fully in the Interoperability chapter in the Oracle Containers for J2EE Services Guide.

• The <primkey-mapping> element maps the primary key to the container-managed persistent field it represents. See "Configuring Explicit Mapping of Persistent Fields to the Database" for more information.

• The <cmp-field-mapping> element maps each <cmp-field> element to its database row. See "Configuring Explicit Mapping of Persistent Fields to the Database" for more information.

• The <finder-method> element is used to create finder methods for EJB 1.1 entity beans. To create EJB 2.0 finder methods, see "Implementing EJB QL Finder Methods".

• The <env-entry-mapping> element maps environment variables to JNDI names.

• The <ejb-ref-mapping> element maps any EJB references to JNDI names.

• The <resource-ref-mapping> element maps any EJB references to JNDI names.

• The <resource-env-ref-mapping> element is used to map an administered object for a resource.

Table A-1 lists the attributes for the <entity-deployment> element:

Table A-1 Attributes of the <entity-deployment> Element

Attribute	Description
call-timeout	Specifies the maximum time to wait for any resource to make a business/life cycle method invocation. This is not a timeout of how long a business method invocation can take. If the timeout is reached, a TimeOutException is thrown. This excludes database connections. The default value is 90000 milliseconds. Set to 0 if you want the timeout to be forever. See the EJB section in the Oracle Application Server Performance Guide for more information.
clustering-schema	Do not use. Not applicable.
copy-by-value	Indicates whether or not to copy (clone) all the incoming and outgoing parameters in EJB calls. Set to false if you are certain that your application does not assume copy-by-value semantics for a speed-up. The default value is true.
data-source	Specifies the name of the data source used.
exclusive-write-access	Defines whether or not the EJB server has exclusive write (update) access to the database back-end. This can be used only for entity beans that use a read-only locking mode (see "Configuring Concurrency Modes"). In this case, it increases the performance for common bean operations and enables better caching. This parameter corresponds to which commit option is used (A, B or C, as defined in the EJB 2.0 specification). When exclusive-write-access=true, this is commit option A. The default value is false for beans with locking-mode=optimistic or pessimistic, and true for locking-mode=read-only. The exclusive-write-access is forced to false if locking is pessimistic or optimistic, and is not used with EJB clustering (see "Entity Bean Concurrency Modes and Clustering"). The exclusive-write-access can be false with read-only locking, but read-only will not have any performance impact if exclusive-write-access=false, since ejbStore methods are already skipped when no fields have been changed. To see a performance advantage and avoid the execution of ejbLoad methods for read-only beans, you must also set exclusive-write-access=true. See "Configuring Exclusive Write Access to the Database" for more information.
do-select-before-insert	Specifies whether or not to avoid executing a select before an insert. Set it to false if you choose to avoid executing a select before an insert. The extra select normally checks to see if the entity already exists before doing the insert to avoid duplicates. If a unique key constraint is defined for the entity, then you should set this to false. If there is no unique key constraint, setting this to false leads to not detecting a duplicate insert. To prevent duplicate inserts in this case, leave it set to true. For performance, Oracle recommends setting this to false to avoid the extra select before insert. The default value is true.
location	Specifies the JNDI name to which this bean will be bound.
isolation	Specifies the isolation level (see "Configuring Database Isolation Levels") for database actions. The valid values for Oracle databases are serializable and committed, with committed being the default. Non-Oracle databases can be the following: none, committed, serializable, uncommitted, and repeatable_read. For more information, see "Entity Bean Database Isolation Levels and Resource Contention", "Using Database Isolation Modes to Protect Against Resource Contention" on page 4-14 and Oracle Application Server Performance Guide.
locking-mode	Specifies the concurrency mode (see "Configuring Concurrency Modes" and Oracle Application Server Performance Guide). The concurrency modes are as follows: pessimistic, optimistic, read-only.
max-instances	Specifies the number of maximum bean implementation instances to be kept instantiated or pooled. The default value is 0, which means infinite.
min-instances	Specifies the number of minimum bean implementation instances to be kept instantiated or pooled. The default value is 0.
max-tx-retries	Specifies the number of times to retry a transaction that was rolled back due to system-level failures. Generally, you should add retries only where errors are seen that could be resolved through retries. For example, if you are using serializable isolation and you want to retry the transaction automatically if there is a conflict, you might want to use retries. However, if the bean wants to be notified when there is a conflict, then you should leave max-tx-retries=0. The default value is 0. See the EJB section in the Oracle Application Server Performance Guide for more information.
tx-retry-wait	Specifies the time to wait in seconds between retrying the transaction. The default value is 60.
update-changed-fields-only	Specifies whether the container updates only modified fields or all fields to persistence storage for entity beans with container-managed persistence when ejbStore method is invoked. The default value is true, which specifies to only update modified fields.
name	Specifies the name of the bean, which matches the name of a bean in the assembly section of the EJB deployment descriptor.
pool-cache-timeout	Specifies the amount of time in seconds that the bean implementation instances are to be kept in the pooled (unassigned) state. Specifying never retains the instances until they are garbage collected. The default value is 60.
table	Specifies the name of the table in the database.
validity-timeout	The maximum amount of time in milliseconds that an entity is valid in the cache (before being reloaded). Useful for loosely coupled environments where rare updates from legacy systems occur. This attribute is only valid for entity beans with concurrency mode of read-only and when exclusive-write-access=true (default). If the data is never being modified externally (and, therefore, you have set exclusive-write-access=true), you should set this to 0 or -1 to disable this option, since the data in the cache will always be valid for read-only beans that are never modified externally. If the bean is generally not modified externally, so you are using exclusive-write-access=true, yet occasionally the table is updated so you need to update the cache sometimes, then set this to a value corresponding to the interval you think the data may be changing externally.
force-update	If OC4J does not believe that any of the persistence data has changed, the force-update attribute set to true means that OC4J will still execute the bean's life cycle by invoking the ejbStore method. This manages data in transient fields and sets appropriate persistent fields during the ejbStore method. For example, an image might be kept in one format in memory, but stored in a different format in the database. The default value is false.
wrapper	Specifies the name of the OC4J remote home wrapper class for this bean. This is an internal server value and should not be edited.
local-wrapper	Specifies the name of the OC4J local home wrapper class for this bean. This is an internal server value and should not be edited.
delay-updates-until-commit	Specifies whether or not to defer the flushing of transactional data until commit time. The default value is true. Set this value to false to update persistence data after completion of every EJB method invocation, except ejbRemove method and the finder methods.

AC4J Active EJB Section

The <jem-server-extension> section defines the JNDI name of the database, where the AC4J Databus is installed. The <jem-server-extension> contains the following structure:

<jem-server-extension data-source-location=... scheduling-threads=...>
    <description></description>
    <data-bus data-bus-name=... url=.../>
</jem-server-extension>

For more information on this element, see the Oracle Containers for J2EE Services Guide.

The <jem-deployment> section provides additional deployment information for an active bean deployed within this JAR file. The <jem-deployment> section contains the following structure:

<jem-deployment jem-name=... ejb-name=...>
    <description></description>
    <data-bus data-bus-name=... url=.../>
    <called-by>
        <caller caller-identity=.../>  
    </called-by>
    <security-identity>
    <description></description>
    <use-caller-identity></use-caller-identity>
    </security-identity>
</jem-deployment>

The <called-by> element lets you control or restrict the usage of the asynchronous methods defined on the AC4J bean at deployment time. In the following example CLIUSER, SVRUSER and XTRAUSER can invoke all methods defined on AC4JBeanA, which corresponds to the EJB with name="ABean". If USER1 or USER2 invoke this AC4JBeanA, then the container throws SecurityException:

<jem-deployment jem-name="AC4JBeanA" ejb-name="ABean">
    <called-by>
        <caller caller-identity="CLIUSER"/>           
        <caller caller-identity="SVRUSER"/>
        <caller caller-identity="XTRAUSER"/>
    </called-by>
</jem-deployment>

If the application deployer defines a security role for the ABean EJB with role="USER1", then USER1 can invoke all the methods on the ABean EJB synchronously. However, USER1 can not invoke the same asynchronous methods in AC4JBeanA unless the <called-by> element is defined for USER1.

For more information on this element, see the Oracle Containers for J2EE Services Guide.

Method Definition

The following structure is used to specify the methods (and, possibly, parameters of that method) of the bean:

<method>
    <description></description>
    <ejb-name></ejb-name>
    <method-intf></method-intf>
    <method-name></method-name>
    <method-params>
        <method-param></method-param>
    </method-params>
</method>

You can use one of the following styles:

1. When referring to all the methods of the specified bean's home and remote interfaces, specify the methods as follows:

   <method>
       <ejb-name>EJBNAME</ejb-name>
       <method-name>*</method-name>
   </method>
   
   

2. When referring to multiple methods with the same overloaded name, specify the methods as follows:

   <method>
       <ejb-name>EJBNAME</ejb-name>
       <method-name>METHOD</method-name>
   </method>>
   
   

3. When referring to a single method within a set of methods with an overloaded name, you can specify each parameter within the method as follows:

   <method>
       <ejb-name>EJBNAME</ejb-name>
       <method-name>METHOD</method-name>
       <method-params>
           <method-param>PARAM-1</method-param>
           <method-param>PARAM-2</method-param>
           ...
           <method-param>PARAM-n</method-param>
       </method-params>
   </method>
   
   

The <method> element is used within the security and MDB sections. See "Specifying Logical Roles in the EJB Deployment Descriptor" on page 10-3 for more information.

Assembly Descriptor Section

In addition to specifying deployment information for individual beans, you can also specify addition deployment mapping information for security in the <assembly-descriptor> section. The <assembly-descriptor> section contains the following structure:

<assembly-descriptor>
    <security-role-mapping impliesAll=... name=...>
        <group name=... />
        <user name=... />
    </security-role-mapping>
    <default-method-access>
        <security-role-mapping impliesAll=... name=...>
            <group name=... />
            <user name=... />
        </security-role-mapping>    
    </default-method-access>
</assembly-descriptor>