A XML Reference for orion-ejb-jar.xml Elements

This appendix describes the elements contained within the orion-ejb-jar.dtd– the OC4J-specific EJB deployment descriptor. This appendix covers the structure and briefly describes the elements in this DTD; however, most of these elements are fully described in other sections of this book.

The DTD is located at http://xmlns.oracle.com/ias/dtds/orion-ejb-jar.dtd.

The description of this deployment descriptor has been divided into the following sections:

• Overall description of each element section–Each section of elements of this XML file is described in "OC4J-specific Deployment Descriptor for EJB".

• Element description–An alphabetical listing and description for each element is discussed in "Element Description".

Whenever you deploy an application, OC4J automatically generates the OC4J-specific XML file with the default elements. If you want to change these defaults, you must copy the orion-ejb-jar.xml file to where your original ejb-jar.xml file is located and change it in this location. If you change the XML file within the deployed location, OC4J overwrites these changes when the application is deployed again. The changes only stay constant when changed in the development directories.

You should add your OC4J-specific XML files within the recommended development structure, similar to the one that Figure A-1 shows:

Figure A-1 Development Application Directory Structure

Description of "Figure A-1 Development Application Directory Structure"

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", "Configuring Database Isolation Levels" 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.

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>

Element Description

<assembly-descriptor>

The mapping of the assembly descriptor elements.

<called-by>

Enables the application deployer to control or restrict the usage of the asynchronous methods defined on the AC4J bean. You specify the user identity that is allowed to execute all methods of the bean in this element. The identities that can execute the AC4J beans are identified in one or more <caller> elements.

<caller>

Each caller identity that is allowed to execute methods on the AC4J bean is defined in a single <caller> element.

Attributes:

• caller-identity–The security role that is allowed to execute the AC4J bean methods.

<cmp-field-mapping>

Deployment information for a persistent field. If no subtags are used to define different behavior, the field is persisted through serialization or native handling of "recognized" primitive types.

Attributes:

• ejb-reference-home–The JNDI location of the field's remote EJB home, if the field is an entity EJBObject or an EJBHome.

• name–The name of the field.

• persistence-name–The name of the field in the database table.

• persistence-type–The database type of the field. Valid values vary from database to database.

<collection-mapping>

A relational mapping of a Collection type. A Collection consists of n unordered items (order is not specified and not relevant). The field containing the mapping must be of type java.util.Collection.

Attributes:

• table–The name of the table in the database.

<context-attribute>

An attribute that is sent to the context. The only mandatory attribute in JNDI is the java.naming.factory.initial, which is the class name of the context factory implementation.

Attributes:

• name–The name of the attribute.

• value–The value of the attribute.

<data-bus>

The name and URL of a specific Databus for an OC4J object.

Attributes:

• data-bus-name–The user-defined name of the Databus.

• url–The URL of the Databus, which is similar to a JDBC URL.

<default-method-access>

The default method access policy for methods not tied to a method-permission.

<description>

A short description.

<ejb-name>

An enterprise bean's name. This name is assigned by the ejb-jar.xml file producer to name the enterprise bean in deployment descriptor. The name must be unique among the names of the enterprise beans in the same ejb-jar.xml file. The enterprise bean code does not depend on the name; therefore the name can be changed during the application assembly process without breaking the enterprise bean's function. There is no architected relationship between the <ejb-name> element in the deployment descriptor and the JNDI name that the deployer will assign to the enterprise bean's home. The name must conform to the lexical rules for an NMTOKEN.

<ejb-ref-mapping>

Declares a reference to another enterprise bean's home. This element ties this to a JNDI location at deployment time.

Attributes:

• location–The JNDI location, in which to search for the EJB home.

• name–The ejb-ref's name. Matches the name of an ejb-ref in ejb-jar.xml file.

<enterprise-beans>

Lists the beans contained in this EJB JAR file.

<entity-deployment>

Contains the deployment information for an entity bean. See Table A-1 for list and description of attributes of this element.

<entity-ref>

Specifies the configuration for persisting an entity reference using its primary key. The subtag of this tag is the specification of how to persist the primary key.

Attributes:

• home–The JNDI location of the EJBHome, in which to search for the bean.

<env-entry-mapping>

Overrides the value of an <env-entry> element in the assembly descriptor. It is used to keep the EAR clean from deployment-specific values. The body of the element represents the value.

Attribute:

• name–The name of the context parameter.

<fields>

Specifies the configuration of a field-based (java class field) mapping persistence for this field. The fields that are to be persisted have to be public, non-static, non-final, and the type of the containing object has to have a zero-argument constructor.

<finder-method>

The definition of a container-managed finder method. This defines the selection criteria in a findBy<CRITERION> method in the bean's home.

Attributes:

• partial–Specifies whether or not the query is a partial one. A partial query is the WHERE clause or the ORDER (if it starts with order) clause of the SQL query. Queries are partial by default. If partial="false" is specified, then the full query is to be entered as value for the query attribute and you need to make sure that the query produces a result set containing all of the persistent fields. This is useful when performing advanced queries involving table joins.

• query–Defines the query part of a SQL statement. This is the section following the WHERE keyword in the statement. Special tokens are $number, which denotes a method argument number, and $name, which denotes a persistent field name. For instance, the query for findByAge(int age) would be "$1 = $age" (assuming the persistent field is named age).

• lazy-loading–For entity bean finder methods, lazy loading can cause the select method to be invoked more than once. To turn on lazy loading and enforce only a single execution of this finder method, set this property to true. The default value is false.

• prefetch-size–Oracle JDBC drivers include extensions that let you set the number of rows to prefetch into the client, while a result set is being populated during a query. This reduces round trips to the database by fetching multiple rows of data each time data is fetched–the extra data is stored in client-side buffers for later access by the client. You can set any number of rows to prefetch. The default number of rows to prefetch to the client is 10. The number set here is passed to the JDBC driver. See the Oracle Database JDBC Developer's Guide and Reference for more information on using prefetch with a JDBC driver.

<group>

A group that this <security-role-mapping> implies. That is, all members of the specified group are included in this role.

Attributes:

• name–The name of the group.

<ior-security-config>

The <ior-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.

<jem-deployment>

Specifies an active enterprise bean for deployment into the AC4J container.

Attributes:

• jem-name–The AC4J name that is used to identify the enterprise bean within the AC4J calls.

• ejb-name–The name of the enterprise bean defined in the ejb-jar.xml file as an active bean.

<jem-server-extension>

Describes the database server where the Databus is installed

Attributes:

• data-source-location–Provides the JNDI data source definition of the database where the Databus exists. The data source is configured in the data-sources.xml file.

• scheduling-threads–If greater than 1, then multiple OC4J threads can act in parallel. 1 is the default value.

<lookup-context>

The specification of an optional javax.naming.Context implementation used for retrieving the resource. This is useful when using third party modules, such as a third party JMS server. Either use the Context implementation supplied by the resource vendor or, if none exists, write an implementation that negotiates with the vendor software.

Attribute:

• location–The name looked for in the foreign context when retrieving the resource.

<map-key-mapping>

Specifies a mapping of the map key. Map keys are always immutable.

Attributes:

• type–The fully qualified class name of the type of the value. For example, com.acme.Product, java.lang.String, and so on.

<method>

Specifies the methods (and, possibly, parameters of that method) of the bean.

<method-intf>

Allows a method element to differentiate between the methods with the same name and signature that are defined in both the remote and home interfaces. This element must be either home or remote.

<method-name>

Contains a name of an enterprise bean method, or the asterisk ( * ) character. The asterisk is used when the element denotes all the methods of an enterprise bean's remote and home interfaces.

<method-param>

Contains the fully qualified Java type name of a method parameter.

<method-params>

Contains a list of the fully qualified Java type names of the method parameters.

<orion-ejb-jar>

An orion-ejb-jar.xml file contains the OC4J-specific deployment information for a bean. It is used to specify initial deployment properties. After each deployment, the deployment descriptor file is reformatted and altered by the server for additional information.

Attributes:

• deployment-time–The time (long milliseconds in decimal) of the last deployment, if not matching the last editing date the JAR will be redeployed. This is an internal server value, do not edit it.

• deployment-version–The version of OC4J with which this JAR was deployed. If it is not matching the current version, then it will be redeployed. This is an internal server value, do not edit it.

<primkey-mapping>

Designates how the primary key is mapped.

<properties>

Specifies the configuration of a property-based (bean properties) mapping persistence for this field. The properties have to adhere to the EJB 2.0 specification, and the type of the containing object has to have an empty constructor. This is also designated within the EJB 2.0 specification.

<resource-ref-mapping>

Declares a reference to an external resource, such as a data source. This element ties the data source to a JNDI location at deployment time.

Attributes:

• location–The JNDI location from which to search the resource factory.

• name–The <resource-ref> element name in ejb-jar.xml file.

<resource-env-ref-mapping>

Maps an administered object for a resource. These objects are retrieved at the same time from JNDI. This element maps the destination object.

Attributes:

• location–The JNDI location from which to search the administered resource.

• name–The <resource-env-ref> element name in ejb-jar.xml file.

<role-name>

The security role under which the AC4J EJB methods are run when using the <run-as-specified-identity> element.

<run-as-specified-identity>

Specifies that all methods of an AC4J EJB execute under a specific identity. That is, the container does not check different roles for permission to run specific methods; instead, the container executes all of the AC4J EJB methods under the specified security identity.

<security-identity>

Describes if the AC4J Databus should use the caller or run-as identity for the AC4J bean security.

<security-role-mapping>

The run-time mapping of a role to groups and users. Maps to a security role of the same name in the assembly descriptor.

Attributes:

• impliesAll–Indicates whether or not this mapping implies all users. The default value is false.

• name–The name of the role.

<set-mapping>

Specifies a relational mapping of a Set type. A Set consists of n unique unordered items (order is not specified and not relevant). The field containing the mapping must be of type java.util.Set.

Attributes:

• table–The name of the table in the database.

<use-caller-identity>

Specifies that all methods of an AC4J bean execute under the caller's identity.

<user>

A user that this <security-role-mapping> element implies.

Attributes:

• name–The name of the user.

<value-mapping>

Specifies a mapping of the primary key part of a set of fields.

Attributes:

• immutable–Identifies whether or not the value can be trusted to be immutable, once added to the Collection. Setting this to true will optimize database operations extensively. The default value is true for <set-mapping> element, and false for <collection-mapping> element

• type–The fully qualified class name of the type of the value. For example, com.acme.OrderEntry, java.lang.String, and so on.