B
OC4J-Specific DTD Reference

This appendix describes the elements contained within the OC4J-specific EJB deployment descriptor: orion-ejb-jar.dtd. 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 EJBs".

• 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 simply overwrites these changes when the application is deployed again. The changes only stay constant when changed in the development directories.

Oracle recommends that you add your OC4J-specific XML files within the recommended development structure as shown in Figure B-1.

Figure B-1 Development Application Directory Structure

Text description of the illustration dtdxmla.gif

OC4J-Specific Deployment Descriptor for EJBs

The OC4J-specific deployment descriptor contains extended deployment information for session beans, entity beans, message driven beans, and security for these EJBs. The major element structure within this deployment descriptor has the following structure:

<orion-ejb-jar deployment-time=... deployment-version=...> 
 <enterprise-beans>
   <session-deployment ...></session-deployment>
   <entity-deployment ...></entity-deployment>
   <message-driven-deployment ...></message-driven-deployment>
   <jem-deployment ...></jem-deployment>
   <jem-server-extension ...></jem-server-extension>
 </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 sections below:

• Enterprise Beans Section

• Assembly Descriptor Section

Enterprise Beans Section

The <enterprise-beans> section defines additional deployment information for all EJBs: session beans, entity beans, and message driven beans. There is a section for each type of EJB.

The following sections describe the elements within <enterprise-beans> element;

• Session Bean Section

• Entity Bean Section

• Message Driven Bean Section

• EJB 1.1 CMP Field Mapping Section

• Method Definition

Session Bean Section

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

<session-deployment pool-cache-timeout=... call-timeout=... copy-by-value=...
      location=... max-instances=... min-instances=... max-tx-retries=...
      name=... persistence-filename=... timeout=... wrapper=...
      local-wrapper=...
  <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>
  <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=... />
</session-deployment>

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

• A session bean example, which includes the <session-deployment> element, is described in "Create the Deployment Descriptor" in Chapter 2, "An EJB Primer For OC4J".

• The <ior-security-config> element is an interoperability element, which is discussed fully in the Interoperability chapter in the Oracle9iAS Containers for J2EE Services Guide.

• The <env-entry-mapping> element maps environment variables to JNDI names and is discussed in "Environment variables".

• The <ejb-ref-mapping> element maps any EJB references to JNDI names and is discussed in "Environment References To Other Enterprise JavaBeans".

• The <resource-ref-mapping> element maps any EJB references to JNDI names and is discussed in "Environment References To Resource Manager Connection Factory References".

• The <resource-env-ref-mapping> element is used to map an administered object for a resource. For example, to use JMS, the bean must obtain both a JMS factory object and a destination object. These objects are retrieved at the same time from JNDI. The <resource-ref> element declares the JMS factory and the <resource-env-ref> elment is used to declare the destination. Thus, the <resource-env-ref-mapping> element maps the destination object. See "Using Logical Names in the JMS JNDI Lookup" for more information.

The attributes for the <session-deployment> element are as follows:

Table B-1 Attributes for <session-deployment> Element  

Attribute	Description
pool-cache-timeout	The pool-cache-timeout applies for stateless session EJBs. This parameter specifies how long to keep stateless sessions cached in the pool. For stateless session beans, if you specify a pool-cache-timeout, then at every pool-cache-timeout interval, all beans in the pool, of the corresponding bean type, are removed. If the value specified is zero or negative, then the pool-cache-timeout is disabled and beans are not removed from the pool. Default Value: 60 (seconds)
call-timeout	This parameter specifies the maximum time to wait for any resource to make a business/life-cycle method invocation. This is not a timeout for how long a business method invocation can take. If the timeout is reached, a TimedOutException is thrown. This excludes database connections. Default Values: 90000 milliseconds. Set to 0 if you want the timeout to be forever. See the EJB section in the Oracle9i Application Server Performance Guide for more information.
copy-by-value	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 is 'true'.
location	The JNDI-name to which this bean will be bound.
max-instances	The number of maximum bean implementation instances to be kept instantiated or pooled. The default is 100. This setting is valid for stateless session beans only.
min-instances	The number of minimum bean implementation instances to be kept instantiated or pooled. The default is 0. This setting is valid for stateless session beans only.
max-tx-retries	This parameter specifies the number of times to retry a transaction that was rolled back due to system-level failures. Generally, we recommend that you start by setting max-tx-retries to 0 and adding 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 in this case, you should set max-tx-retries=0. Default Value: 3. See the EJB section in the Oracle9i Application Server Performance Guide for more information.
name	The name of the bean, which matches the name of a bean in the assembly section of the EJB deployment descriptor (ejb-jar.xml).
persistence-filename	Path to the file where sessions are stored across restarts.
timeout	The timeout applies for stateful session EJBs. If the value is zero or negative, then all timeouts are disabled. The timeout parameter is an inactivity timeout for stateful session beans. Every 30 seconds the pool clean up logic is invoked. Within the pool clean up logic, only the sessions that timed out, by passing the timeout value, are deleted. Adjust the timeout based on your applications use of stateful session beans. For example, if stateful session beans are not removed explicitly by your application, and the application creates many stateful session beans, then you may want to lower the timeout value. If your application requires that a stateful session bean be available for longer than 30 minutes, then adjust the timeout value accordingly. Default Value: 30 (minutes)
wrapper	Name of the OC4J wrapper class for this bean. This is an internal server value and should not be edited.
local-wrapper	Name of the OC4J local home wrapper class for this bean. This is an internal server value and should not be edited.

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=... instance-cache-timeout=... isolation=...
      location=... locking-mode=... max-instances=... min-instances=... 
      max-tx-retries=... update-chnaged-fields-only=... 
      disable-wrapper-cache=... name=... pool-cache-timeout=...
      table=... validity-timeout=... force-update=... 
      wrapper=... local-wrapper=...>
  <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=... >
   <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 includes the <entity-deployment> element, are described in Chapter 3, "CMP Entity Beans", Chapter 4, "Entity Relationship Mapping", Chapter 5, "EJB Query Language", and Chapter 6, "BMP Entity Beans".

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

• The <primkey-mapping> element maps the primary key to the CMP field it represents. See "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 "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 "Entity Relationship Mapping". To continue to use EJB 1.1 finder methods with this element, see "EJB 1.1 Advanced Finder Methods".

• The <env-entry-mapping> element maps environment variables to JNDI names and is discussed in "Environment variables".

• The <ejb-ref-mapping> element maps any EJB references to JNDI names and is discussed in "Environment References To Other Enterprise JavaBeans".

• The <resource-ref-mapping> element maps any EJB references to JNDI names and is discussed in "Environment References To Resource Manager Connection Factory References".

• The <resource-env-ref-mapping> element is used to map an administered object for a resource. For example, to use JMS, the bean must obtain both a JMS factory object and a destination object. These objects are retrieved at the same time from JNDI. The <resource-ref> element declares the JMS factory and the <resource-env-ref> elment is used to declare the destination. Thus, the <resource-env-ref-mapping> element maps the destination object. See "Using Logical Names in the JMS JNDI Lookup" for more information.

The attributes for the <entity-deployment> element are as follows:

Table B-2 Attributes for <entity-deployment> Element  

Attribute	Description
call-timeout	This parameter specifies the maximum time to wait for any resource to make a business/life-cycle method invocation. This is not a timeout for how long a business method invocation can take. If the timeout is reached, a TimedOutException is thrown. This excludes database connections. Default Values: 90000 milliseconds. Set to 0 if you want the timeout to be forever. See the EJB section in the Oracle9i Application Server Performance Guide for more information.
clustering-schema	Do not use. Not needed in this release.
copy-by-value	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 is 'true'.
data-source	The name of the data source used if using container-managed persistence.
exclusive-write-access	Whether or not the EJB-server has exclusive write (update) access to the database backend. This can be used only for entity beans that use a "read_only" locking mode. 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 specification). When exclusive-write-access = true, this is commit option A. Default 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. The exclusive-write-access can be false with read-only locking, but read-only won't have any performance impact if exclusive-write-access=false, since ejbStores are already skipped when no fields have been changed. To see a performance advantage and avoid doing ejbLoads for read-only beans, you must also set exclusive-write-access=true. See "Exclusive Write Access to the Database" for more information.
do-select-before-insert	Recommend setting to false to avoid the extra select before insert which checks if the entity already exists before doing the insert. This will then detect a duplicate, if there is one, during the insert. Default Value: true
instance-cache-timeout	The amount of time in seconds that entity wrapper instances are assigned to an identity. If you specify 'never', you retain the wrapper instances until they are garbage collected. The default is 60 seconds.
location	The JNDI-name to which this bean will be bound.
isolation	Specifies the isolation-level for database actions. The valid values for Oracle databases are 'serializable' and 'committed'. The default is 'committed'. Non-Oracle databases can be the following: 'none', 'committed', 'serializable', 'uncommitted', and 'repeatable_read'. For more information, see "Entity Bean Concurrency and Database Isolation Modes" and Oracle9i Application Server Performance Guide .
locking-mode	The concurrency modes configure when to block to manage resource contention or when to execute in parallel. For more information, see "Entity Bean Concurrency and Database Isolation Modes" and Oracle9i Application Server Performance Guide . The concurrency modes are as follows: PESSIMISTIC: This manages resource contention and does not allow parallel execution. Only one user at a time is allowed to execute the entity bean at a single time. OPTIMISTIC: Multiple users can execute the entity bean in parallel. It does not monitor resource contention; thus, the burden of the data consistency is placed on the database isolation modes. This is the default. READ-ONLY: Multiple users can execute the entity bean in parallel. The container does not allow any updates to the bean's state.
max-instances	The number of maximum bean implementation instances to be kept instantiated or pooled. The default is 100. See "Configuring Pool Sizes For Entity Beans" for more information.
min-instances	The number of minimum bean implementation instances to be kept instantiated or pooled. The default is 0. See "Configuring Pool Sizes For Entity Beans" for more information.
max-tx-retries	This parameter specifies the number of times to retry a transaction that was rolled back due to system-level failures. Generally, we recommend that you start by setting max-tx-retries to 0 and adding 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 in this case, you should set max-tx-retries=0. Default Value: 3. See the EJB section in the Oracle9i Application Server Performance Guide for more information.
update-changed- fields-only	Specifies whether the container updates only modified fields or all fields to persistence storage for CMP entity beans when ejbStore is invoked. The default is true, which specifies to only update modified fields. See "Techniques for Updating Persistence" for more information.
disble-wrapper-cache	If true, a pool of wrapper instances is not maintained. The default is true. See "Configuring Pool Sizes For Entity Beans" for more information.
name	The name of the bean, which matches the name of a bean in the assembly section of the EJB deployment descriptor (ejb-jar.xml).
pool-cache-timeout	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 is 60.
table	The name of the table in the database if using container-managed persistence.
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 locking mode of read_only and when exclusive-write-access="true" (the default). We recommend that if the data is never being modified externally (and therefore you've set exclusive-write-access=true), that you can set this to 0 or -1, to disable this option, since the data in the cache will always be valid for read-only EJBs that are never modified externally. If the EJB is generally not modified externally, so you're using exclusive-write-access=true, yet occasionally the table is updated so you need to update the cache occasionally, 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 EJB lifecycle 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 is false.
wrapper	Name of the OC4J remote home wrapper class for this bean. This is an internal server value and should not be edited.
local-wrapper	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	This attribute is valid only for CMP entity beans. Defers the flushing of transactional data until commit time or not. The default is true. Set this value to false to update persistence data after completion of every EJB method invocation - except ejbRemove() and the finder methods.

Message Driven Bean Section

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

<message-driven-deployment cache-timeout=... connection-factory-location=... 

      destination-location=... name=... subscription-name=...
      listener-threads=... transaction-timeout=...>
  <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=... />
</message-driven-deployment>

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

• A message-driven bean example, which includes the <message-driven-deployment> element, is described in Chapter 7, "Message-Driven Beans".

• The <env-entry-mapping> element maps environment variables to JNDI names and is discussed in "Environment variables".

• The <ejb-ref-mapping> element maps any EJB references to JNDI names and is discussed in "Environment References To Other Enterprise JavaBeans".

• The <resource-ref-mapping> element maps any EJB references to JNDI names and is discussed in "Environment References To Resource Manager Connection Factory References".

• The <resource-env-ref-mapping> element is used to map an administered object for a resource. For example, to use JMS, the bean must obtain both a JMS factory object and a destination object. These objects are retrieved at the same time from JNDI. The <resource-ref> element declares the JMS factory and the <resource-env-ref> elment is used to declare the destination. Thus, the <resource-env-ref-mapping> element maps the destination object. See "Using Logical Names in the JMS JNDI Lookup" for more information.

The attributes for the <message-driven-deployment> element are as follows:

Table B-3 Attributes for <message-driven-deployment> Element

Attribute	Description
cache-timeout	Do not use this element.
connection-factory- location	The JNDI location of the connection factory to use. The JMS Destination Connection Factory is specified in the connection-factory-location attribute. The syntax is "java:comp/resource" + resource provider name + "TopicConnectionFactories" or "QueueConnectionFactories" + user defined name. The xxxConnectionFactories details what type of factory is being defined. For more information, see "OC4J-Specific Deployment Descriptor".
destination-location	The JNDI location of the destination (queue/topic) to use. The JMS Destination is specified in the destination-location attribute. The syntax is "java:comp/resource" + resource provider name + "Topics" or "Queues" + Destination name. The Topic or Queue details what type of Destination is being defined. The Destination name is the actual queue or topic name defined in the database. For more information, see "OC4J-Specific Deployment Descriptor".
max-instances	Do not use this element. Use listener-threads instead
min-instances	Do not use this element.
name	The name of the bean, which matches the name of a bean in the assembly section of the EJB deployment descriptor (ejb-jar.xml).
subscription-name	If this is a topic, the subscription name is defined in the subscription-name attribute. For more information, see "OC4J-Specific Deployment Descriptor".
listener-threads	The listener threads are used to concurrently consume JMS messages. The default is one thread. For more information, see "OC4J-Specific Deployment Descriptor".
transaction-timeout	This attribute controls the transaction timeout interval for any container-managed transactional MDB. The default is one day. If the transaction has not completed in this timeframe, the transaction is rolled back. For more information, see "OC4J-Specific Deployment Descriptor".

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 Chapter 10, "Active Components for Java".

The <jem-deployment> section provides additional deployment information for an active EJB 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 the application deployer to control or restrict the usage of the asynchronous methods defined on the AC4J bean. 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 Chapter 10, "Active Components for Java".

EJB 1.1 CMP Field Mapping Section

If you still use EJB 1.1 CMP entity beans, you use the following elements to map the CMP fields to the database. See "Mapping EJB 1.1 CMP Fields to a Database Table and Its Columns" for a discussion on mapping EJB 1.1 CMP data fields.

The following are the XML elements used for CMP persistent data field mapping within the orion-ejb-jar.xml file:

<cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
      persistence-type=...>
   <fields> 
      <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
          persistence-type=...></cmp-field-mapping>
   </fields>
   <properties> 
      <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
            persistence-type=...></cmp-field-mapping>
   </properties>
   <entity-ref home=...> 
      <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
          persistence-type=...></cmp-field-mapping>
   </entity-ref>
   <list-mapping table=...> 
      <primkey-mapping>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </primkey-mapping>
      <value-mapping immutable="true|false" type=...>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </value-mapping>
   </list-mapping>
   <collection-mapping table=...>
      <primkey-mapping>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </primkey-mapping>
      <value-mapping immutable="true|false" type=...>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </value-mapping>
   </collection-mapping>
   <set-mapping table=...>
      <primkey-mapping>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </primkey-mapping>
      <value-mapping immutable="true|false" type=...>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </value-mapping>
   </set-mapping>
   <map-mapping table=...>
      <primkey-mapping>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </primkey-mapping>
      <map-key-mapping type=...>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </map-key-mapping>
      <value-mapping immutable="true|false" type=...>
         <cmp-field-mapping ejb-reference-home=... name=... persistence-name=...
             persistence-type=...></cmp-field-mapping>
      </value-mapping>
   </map-mapping>
</cmp-field-mapping>

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>

The style used can be one of the following:

1. When referring to all the methods of the specified enterprise 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 "OC4J-Specific Deployment Descriptor" and "Specifying Logical Roles in the EJB Deployment Descriptor" 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>

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

• The <security-role-mapping> element is described in "Mapping Logical Roles to Users and Groups".

• The <default-method-access> element is described in "Specifying a Default Role Mapping for Undefined Methods".

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 be execute the AC4J beans are identified in one or more <caller> elements.

<caller>

Each caller identity allowed to execute methods on the AC4J bean are 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 container-managed persistence 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 fields 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 (valid values varies from database to database) of the field.

<collection-mapping>

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

Attiributes:

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

<context-attribute>

An attribute sent to the context. The only mandatory attribute in JNDI is the 'java.naming.factory.initial' which is the classname 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 AC4J 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>

The ejb-name element specifies an enterprise bean's name. This name is assigned by the ejb-jar file producer to name the enterprise bean in the ejb-jar file's deployment descriptor. The name must be unique among the names of the enterprise beans in the same ejb-jar 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 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>

The ejb-ref element that is used for the declaration of a reference to another enterprise bean's home. The ejb-ref-mapping element ties this to a JNDI-location when deploying.

Attributes:

• location - The JNDI location to look up the EJB home from.

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

<enterprise-beans>

The beans contained in this EJB JAR file.

<entity-deployment>

Deployment information for an entity bean.

Attributes:

• call-timeout - The time (long milliseconds in decimal) to wait for any resource that the EJB uses, except database connections, if it is busy (before throwing a RemoteException, treating it as a deadlock). This is also used as a SQL query timeout. If the timeout occurs before the SQL query finishes, a SQL exception is thrown. If zero, the timeout is disabled. The default is 90 seconds.

• clustering-schema - Not recommended to use.

• copy-by-value - Whether or not to copy all the incoming/outgoing parameters for all incoming and outgoing EJB calls. Set to 'false' if your application does not assume copy-by-value semantics for these parameters. The default is 'true'.

• data-source - The name of the data source used if using container-managed persistence.

• delay-updates-until-commit - Defers the flushing of transactional data until commit time or not. The default is true. If you want each change to be updated in the database, set this element to false.

• disable-wrapper-cache - If true, a pool of wrapper instances is not maintained. The default is true. See "Configuring Pool Sizes For Entity Beans" for more information.

• do-select-before insert - Recommend setting to false to avoid the extra select before insert which checks if the entity already exists before doing the insert. This will then detect a duplicate, if there is one, during the insert. Default Value: true.

• exclusive-write-access - Whether or not the EJB-server has exclusive write (update) access to the database backend. This can be used only for entity beans that use a "read_only" locking mode. In this case, it increases the performance for common bean operations and enables better caching. The default is false. See "Exclusive Write Access to the Database" for more information.

• instance-cache-timeout - The amount of time in seconds that entity wrapper instances are assigned to an identity. If you specify 'never', you retain the wrapper instances until they are garbage collected. The default is 60 seconds.

• isolation - Specifies the isolation-level for database actions. The valid values for Oracle databases are 'serializable' and 'committed'. The default is 'committed'. Non-Oracle databases can be the following: 'none', 'committed', 'serializable', 'uncommitted', and 'repeatable_read'. For more information, see "Entity Bean Concurrency and Database Isolation Modes" and Oracle9i Application Server Performance Guide .

• local-wrapper - Name of the OC4J local home wrapper class for this bean. This is an internal server value and should not be edited.

• location - The JNDI-name this bean will be bound to.

• locking-mode - The concurrency modes configure when to block to manage resource contention or when to execute in parallel. For more information, see "Entity Bean Concurrency and Database Isolation Modes" and Oracle9i Application Server Performance Guide . The concurrency modes are as follows:
  • PESSIMISTIC: This manages resource contention and does not allow parallel execution. Only one user at a time is allowed to execute the entity bean at a single time.

  • OPTIMISTIC: Multiple users can execute the entity bean in parallel. It does not monitor resource contention; thus, the burden of the data consistency is placed on the database isolation modes. This is the default.

  • READ-ONLY: Multiple users can execute the entity bean in parallel. The container does not allow any updates to the bean's state.

• max-instances - The number of maximum bean implementation instances to be kept instantiated or pooled. The default is 100. See "Configuring Pool Sizes For Entity Beans" for more information.

• min-instances - The number of minimum bean implementation instances to be kept instantiated or pooled. The default is 0. See "Configuring Pool Sizes For Entity Beans" for more information.

• max-tx-retries--The number of times to retry a transaction that was rolled back due to system-level failures. The default is 3. Consider setting to zero if using the serializable isolation level. Within a transaction, the container uses the max-tx-retries value of the first invoked bean within the transaction. The performance guide recommends that you set this value to 0 and add retries only where errors are seen that could be resolved through a retry.

• name - The name of the bean, this matches the name of a bean in the assembly descriptor (ejb-jar.xml).

• pool-cache-timeout - 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 is 60.

• table - The name of the table in the database if using container-managed persistence.

• 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 locking mode of read_only and when exclusive-write-access="true" (the default).

  We recommend that if the data is never being modified externally (and therefore you've set exclusive-write-access=true), that you can set this to 0 or -1, to disable this option, since the data in the cache will always be valid for read-only EJBs that are never modified externally.

  If the EJB is generally not modified externally, so you're using exclusive-write-access=true, yet occasionally the table is updated so you need to update the cache occasionally, then set this to a value corresponding to the interval you think the data may be changing externally.

• update-changed-fields-only - Specifies whether the container updates only modified fields or all fields to persistence storage for CMP entity beans when ejbStore is invoked. The default is true, which specifies to only update modified fields. See "Techniques for Updating Persistence" for more information.

• wrapper - Name of the OC4J remote home wrapper class for this bean. (internal server attribute, do not edit)

<entity-ref>

Specified the configuration for persisting an entity reference via it's primary key. The child-tag of this tag is the specification of how to persist the primary key.

Attributes:

• home - JNDI location of the EJBHome to get lookup the beans at.

<env-entry-mapping>

Overrides the value of an env-entry in the assembly descriptor. It is used to keep the EAR clean from deployment-specific values. The body is 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 an empty constructor.

<finder-method>

The definition of a container-managed finder method. This defines the selection criteria in a findByXXX() method in the bean's home.

Attributes:

• partial - Whether or not the specified 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 CMP fields. This is useful when doing advances queries involving table joins and similar.

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

<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 Oracle9iAS Containers for J2EE Services Guide.

<jem-deployment>

Specifies an active EJB for deployment into the AC4J container.

Attributes:

• jem-name - An AC4J name that is used to identify the bean within the AC4J calls

• ejb-name - Identifies the EJB defined in the ejb-jar.xml file as an active EJB.

<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. Default is 1.

<list-mapping>

Specifies a relational mapping of a List type. A List is a sequential (where order/index is important) Collection of items. The field containing the mapping must be of type java.util.List or the legacy types java.util.Vector or Type[].

Attributes:

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

<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. Examples are com.acme.Product, java.lang.String etc.

<map-mapping>

Specifies a relational mapping of a Map type. A Map consists of n unique keys and their mapping to values. The field containing the mapping must be of type java.util.Map or the legacy types java.util.Hashtable or java.util.Properties.

Attributes:

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

<message-driven-deployment>

Deployment information for a MDB.

Attributes:

• connection-factory-location: The JNDI location of the connection factory to use. The JMS Destination Connection Factory is specified in the connection-factory-location attribute. The syntax is "java:comp/resource" + resource provider name + "TopicConnectionFactories" or "QueueConnectionFactories" + user defined name. The xxxConnectionFactories details what type of factory is being defined.

• destination-location: The JNDI location of the destination (queue/topic) to use. The JMS Destination is specified in the destination-location attribute. The syntax is "java:comp/resource" + resource provider name + "Topics" or "Queues" + Destination name. The Topic or Queue details what type of Destination is being defined. The Destination name is the actual queue or topic name defined in the database.

• name - The name of the bean, this matches the name of a bean in the assembly descriptor (ejb-jar.xml).

• subscription-name: If this is a topic, the subscription name is defined in the subscription-name attribute.

• listener-threads: The listener threads are used to concurrently consume JMS messages. The default is one thread.

• transaction-timeout: This attribute controls the transaction timeout interval for any container-managed transactional MDB. The default is one day. If the transaction has not completed in this timeframe, the transaction is rolled back.

<method>

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

<method-intf>

The method-intf element 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. The method-intf element must be one of the following: Home or Remote.

<method-name>

The method-name element 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>

The method-param element contains the fully-qualified Java type name of a method parameter.

<method-params>

The method-params element 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 an EJB. It is used to specify initial deployment properties. After each deployment the deployment 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. (internal server value, do not edit)

• deployment-version - The version of OC4J this jar was deployed with, if it's not matching the current version then it will be redeployed. (internal server value, do not edit)

<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 usual JavaBeans specification and the type of the containing object has to have an empty constructor This is also designated within the EJB specification.

<resource-ref-mapping>

The resource-ref element is used for the declaration of a reference to an external resource such as a data source, JMS queue, or mail session. The resource-ref-mapping ties this to a JNDI-location when deploying.

Attributes:

• location - The JNDI location to look up the resource factory from.

• name - The resource-ref name. Matches the name of an resource-ref in ejb-jar.xml.

<resource-env-ref-mapping>

The resource-env-ref-mapping element element is used to map an administered object for a resource. For example, to use JMS, the bean must obtain both a JMS factory object and a destination object. These objects are retrieved at the same time from JNDI. The <resource-ref> element declares the JMS factory and the <resource-env-ref> elment is used to declare the destination. Thus, the <resource-env-ref-mapping> element maps the destination object. See "Using Logical Names in the JMS JNDI Lookup" for more information.

Attributes:

• location - The JNDI location from which to look up the administered resource.

• name - The resource-env-ref name in ejb-jar.xml.

<role-name>

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

<run-as-specified-identity>

You can specify 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 runtime mapping (to groups and users) of a role. Maps to a security-role of the same name in the assembly descriptor.

Attributes:

• impliesAll - Whether or not this mapping implies all users. The default is false.

• name - The name of the role

<session-deployment>

Deployment information for a session bean.

Attributes:

• pool-cache-timeout--How long to keep stateless sessions cached in the pool. Only applies to stateless session beans. Legal values are positive integer values or 'never'. For stateless session beans, if you specify a pool-cache-timeout, then at every pool-cache-timeout interval, all beans in the pool, of the corresponding bean type, are removed. If the value specified is zero or negative, then the pool-cache-timeout is disabled and beans are not removed from the pool.

  Default Value: 60 (seconds)

• call-timeout--The time (long milliseconds in decimal) to wait for any resource that the EJB uses, excluding database connections, if it is busy. After this times out, a RemoteException is thrown and the EJB is treated as involved in a deadlock. If value is set to 0, OC4J waits for the EJB "forever". This is the default.

• copy-by-value--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 is 'true'.

• local-wrapper--Name of the OC4J wrapper class for this bean. This is an internal server value and should not be edited.

• location--The JNDI-name that this bean will be bound to.

• max-instances - The number of maximum bean implementation instances to be kept instantiated or pooled. The default is 100. This applies only to stateless session beans.

• min-instances - The number of minimum bean implementation instances to be kept instantiated or pooled. The default is 0. This applies only to stateless session beans.

• max-tx-retries--The number of times to retry a transaction that was rolled back due to system-level failures. The default is 3. Within a transaction, the container uses the max-tx-retries value of the first invoked bean within the transaction. The performance guide recommends that you set this value to 0 and add retries only where errors are seen that could be resolved through a retry.

• name--The name of the bean, which matches the name of a bean in the assembly section of the EJB deployment descriptor (ejb-jar.xml).

• persistence-filename--Path to the file where sessions are stored across restarts.

• timeout--Inactivity timeout in seconds. If the value is zero or negative, then all timeouts are disabled. The default is 30 minutes. Every 30 seconds, the pool clean up logic is invoked. Within the pool clean up logic, only the sessions that timed out, by passing the timeout value, are deleted.

  Adjust the timeout based on your applications use of stateful session beans. For example, if stateful session beans are not removed explicitly by your application, and the application creates many stateful session beans, then you may want to lower the timeout value.

  If your application requires that a stateful session bean be available for longer than 30 minutes, then adjust the timeout value accordingly.

• wrapper--Name of the OC4J wrapper class for this bean. This is an internal server value and should not be edited.

<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>

You can specify that all methods of an AC4J EJB execute under the caller's identity.

<user>

A user that this security-role-mapping implies.

Attributes:

• name - The name of the user.

<value-mapping>

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

Attributes:

• immutable - Whether or not the value can be trusted to be immutable once added to the Collection/Map. Setting this to true will optimize database operations extensively. The default value is "true" for set-mapping and map-mappings and "false" for collection-mapping and list-mapping.

• type - The fully qualified class name of the type of the value. Examples are com.acme.OrderEntry, java.lang.String, and so on.