| Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-02 |
|
 Previous |
 Next |
| Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-02 |
|
Previous |
Next |
This appendix describes the elements contained within the OC4J-specific EJB deployment descriptor orion-ejb-jar.xml. This deployment descriptor file conforms to the XML schema document (XSD) located at http://www.oracle.com/technology/oracleas/schema/orion-ejb-jar-10_0.xsd.
This appendix describes:
OC4J-Specific Deployment Descriptor for EJBs: Overall description of each element section.
Element Description: An alphabetical listing and description for each element.
For more information, see "Understanding EJB Deployment Descriptor Files"
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.
Oracle recommends that you add your OC4J-specific XML files within the recommended development structure as shown in Figure A-1.
Figure A-1 Development Application Directory Structure
Table A-2 describes all the attributes of the orion-ejb-jar.xml file <entity-deployment> element and indicates which options you configure in the orion-ejb-jar.xml file and which you configure using TopLink persistence API.
For example:
To configure <entity-deployment> attribute call-timeout, you must use the corresponding TopLink persistence API. If you set the call-timeout attribute in the orion-ejb-jar.xml file, OC4J will ignore it.
To configure <entity-deployment> attribute clustering-schema, you must use the orion-ejb-jar.xml file; there is no corresponding TopLink persistence API.
For EJB 3.0 applications, you access TopLink persistence API by augmenting orion-ejb-jar.xml configuration with TopLink-specific deployment descriptor files ejb3-toplink-sessions.xml and toplink-ejb-jar.xml. For more information, see "Customizing the TopLink Entity Manager".
For EJB 2.1 applications, you access TopLink persistence API using orion-ejb-jar.xml element pm-properties. For more information, see "Customizing the TopLink Persistence Manager".
|
Note: To modify TopLink deployment descriptor files, use the TopLink Workbench.For more information, see:
|
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> <persistence-manager ...></persistence-manager> <session-deployment ...></session-deployment> <entity-deployment ...></entity-deployment> <message-driven-deployment ...></message-driven-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:
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;
The <persistence-manager> section provides additional deployment information for the TopLink persistence manager for EJB 2.1 applications only. For EJB 3.0 applications, OC4J always uses the TopLink entity manager.
The <persistence-manager> section contains the following structure:
<persistence-manager name=... class=... descriptor=... >
<pm-properties>
<session-name>...</session-name>
<project-class>...</project-class>
<db-platform-class>...</db-platform-class>
<default-mapping db-table-gen=... >...</default-mapping>
<remote-relationships>...</remote-relationships>
<cache-synchronization mode=... >...</cache-synchronization>
<customization-class>...</customization-class>
</pm-properties>
</persistence-manager>
Multiple definitions of the <persistence-manager> element is not valid. If OC4J detects multiple definitions of the <persistence-manager> element at parse time, OC4J logs a warning message. In this case, OC4J uses only the first entry and ignores any subsequent entries.
If you want to explicitly specify the persistence manager, use the <persistence-manager> element name attribute. Valid values are:
toplink: selects the TopLink persistence manager (default).
orion: selects the deprecated Orion persistence manager.
If you are using the TopLink persistence manager and you name your TopLink deployment descriptor something other than toplink-ejb-jar.xml (see "What is the toplink-ejb-jar.xml File?"), specify the name using the <persistence-manager> element descriptor attribute.
The <pm-properites> element applies only to the TopLink persistence manager.
For more information, see:
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=...
tx-retry-wait=... name=... persistence-filename=... replication=...
timeout=... idletime=... memory-threshold=... max-instances-threshold=...
resource-check-interval=... passivate-count=... 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=... />
<message-destination-ref-mapping location=... name=... />
</session-deployment>
Table A-1 lists the attributes for the <session-deployment> element and indicates which are applicable to stateless session beans only, stateful session beans only, or both.
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 (where relevant), is described in:
The <ior-security-config> element is an interoperability element, which is discussed fully in the Interoperability chapter in the Oracle Containers for J2EE Services Guide.
The <env-entry-mapping> element maps environment variables to JNDI names and is discussed in "Configuring an Environment Reference to an Environment Variable".
The <ejb-ref-mapping> element maps any EJB references to JNDI names and is discussed in "Configuring an Environment Reference to an EJB".
The <resource-ref-mapping> element maps any EJB references to JNDI names and is discussed in "Resource Manager Connection Factory Environment 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> element is used to declare the destination. Thus, the <resource-env-ref-mapping> element maps the destination object. See "Resource Manager Connection Factory Environment References" for more information.
The <message-destination-ref-mapping> element is only used if you are using JMS 1.1. Use this element to map the message-destination-ref-name in the client deployment descriptor to another location that is available in the OC4J environment. It provides means of linking message consumers and producers to one or more common logical destinations. For more information, see "Configuring an Environment Reference to a JMS Destination Resource Manager Connection Factory (JMS 1.1)".
Table A-1 Attributes for the <session-deployment> Element
| Attribute | Stateless | Stateful | Description |
|---|---|---|---|
 |
|
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 Default Values: 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. |
|
|
|
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'. |
|
|
|
|
You can set an idle timeout for each bean. When this timeout expires, passivation occurs. Set this attribute to the appropriate number of seconds. Default: 300 seconds. (5 min.). To disable, specify "never." |
|
|
|
The local JNDI name to which this EJB will be bound. |
|
|
|
Name of the OC4J local home wrapper class for this bean. This is an internal server value and should not be edited. |
|
|
|
The JNDI-name to which this bean will be bound. |
|
|
|
The number of bean instances allowed in memory—either instantiated or pooled. When this value is reached, OC4J attempts to passivate beans using the least recently used (LRU) algorithm. To allow an infinite number of bean instances, the To disable instance pooling, set For more information, see: |
|
|
|
|
Percentage of Specify an integer that is translated as a percentage. If you define that the To disable, specify "never." |
|
|
|
This parameter specifies the number of times to retry a transaction that was rolled back due to system-level failures. The default is 0. For a stateful session bean, if a Generally, we recommend that you 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 in this case, you should leave max-tx-retries=0. See the EJB section in the Oracle Application Server Performance Guide for more information. |
|
|
|
|
This attribute defines a threshold for how much used JVM memory is allowed before passivation should occur. Specify an integer that is translated as a percentage. When reached, beans are passivated, even if their idle timeout has not expired. Default: 80%. To disable, specify "never." |
|
|
 |
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. |
|
|
|
The name of the bean, which matches the name of a bean in the assembly section of the EJB deployment descriptor ( |
|
|
|
|
This attribute is an integer that defines the number of beans to be passivated if any of the resource thresholds have been reached. Passivation of beans is performed using the least recently used algorithm. Default: one-third of the |
|
|
|
Path to the file where sessions are stored across restarts. |
|
|
|
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) |
|
|
|
|
Configuration of the state replication for stateful session beans. Values can be |
|
|
|
|
The container checks all resources at this time interval. At this time, if any of the thresholds have been reached, passivation occurs. Default: 180 sec. (3 min.). To disable, specify "never." |
|
|
|
|
The maximum number of seconds that a stateful session bean may be inactive before being subject to pool clean up. If the value is zero or negative, then all timeouts are disabled. 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 1800 seconds (equal to 30 minutes), then adjust the timeout value accordingly. Default Value: 1800 seconds |
|
|
|
The maximum number of seconds that OC4J will wait for a transaction started by this stateless or stateful session bean to commit or rollback. If the value is zero or negative, the timeout is disabled. |
|
|
|
This parameter specifies the time to wait in seconds between retrying the transaction. The default is 60 seconds. |
|
|
|
Name of the OC4J wrapper class for this bean. This is an internal server value and should not be edited. |
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=...
disable-default-persistent-unit=...
do-select-before-insert=... isolation=...
location=... local-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>
Table A-2 lists the attributes for the <entity-deployment> element.
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 (where relevant), are described in:
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.
The <primkey-mapping> element maps the primary key to the CMP field it represents. In this release, this feature is not configured in orion-ejb-jar.xml. You configure this feature using TopLink persistence API.
For more information, see:
Oracle TopLink Developer's Guide
The <cmp-field-mapping> element maps each <cmp-field> element to its database row. For more information, see "What are Container-Managed Persistence Fields?".
The <finder-method> element is used to create finder methods for EJB 1.1 entity beans. For more information on EJB 3.0 and EJB 2.1, see "How Do You Query for an EJB 2.1 Entity Bean?"
The <env-entry-mapping> element maps environment variables to JNDI names and is discussed in "Configuring an Environment Reference to an Environment Variable".
The <ejb-ref-mapping> element maps any EJB references to JNDI names and is discussed in "Configuring an Environment Reference to an EJB".
The <service-ref-mapping> element maps any EJB references to a Web service and is discussed in "Configuring an Environment Reference to a Web Service"
The <resource-ref-mapping> element maps any EJB references to JNDI names and is discussed in "Resource Manager Connection Factory Environment 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> element is used to declare the destination. Thus, the <resource-env-ref-mapping> element maps the destination object. See "Resource Manager Connection Factory Environment References" for more information.
The <message-destination-ref-mapping> element is only used if you are using JMS 1.1. Use this element to map the message-destination-ref-name in the client deployment descriptor to another location that is available in the OC4J environment. It provides means of linking message consumers and producers to one or more common logical destinations. For more information, see "Configuring an Environment Reference to a JMS Destination Resource Manager Connection Factory (JMS 1.1)".
The <commit-option> element determines an entity bean instance's state at transaction commit time and offers the flexibility to allow OC4J to optimize certain application conditions and is discussed in "What are Entity Bean Commit Options?".
Table A-2 Attributes for the <entity-deployment> Element
| Attribute | Configurable in orion-ejb-jar.xml | Configurable Using TopLink Persistence API | Description |
|---|---|---|---|
|
|
|
Using TopLink persistence API, you can specify the maximum time OC4J will wait for a query to return a result. A query timeout ensures that your application does not block forever over a hung or lengthy query that does not return in a timely fashion. You can specify a query timeout at the descriptor and query level. A descriptor-level query timeout applies to all queries on the descriptor's reference class. Specify a descriptor-level query timeout to apply the same timeout to all queries on a particular object type. A query-level query timeout applies to that query only. For more information, see:
|
|
|
|
|
Do not use. Not needed in this release. |
|
|
|
|
Whether or not to copy (clone) all the incoming and outgoing parameters in EJB calls. Set to |
|
|
|
|
The name of the data source used if using container-managed persistence. |
|
|
|
|
Using TopLink persistence API, you can configure OC4J for either deferred or non-deferred changes. By default, TopLink defers all changes until commit time: this is the most efficient approach that produces the least number of data source interactions. Alternatively, you can configure an entity bean's descriptor for nondeferred changes. This means that as you change the persistent fields of the entity bean, OC4J modifies the relational schema immediately. For more information, see "Non-Deferred Changes" in the Oracle TopLink Developer's Guide. |
|
|
|
|
By default, OC4J enables the deployment of EJB 3.0 entities without a For more information, see "Understanding the OC4J Default Persistence Unit". |
|
|
|
|
TopLink does not perform a select before writing out changes. Oracle recommends using optimistic locking to handle the possibility of concurrent overwrites. For more information, see "Concurrency (Locking) Mode". |
|
|
|
|
Using TopLink persistence API, OC4J assumes exclusive write access to the entity instances because TopLink uses its unit of work transaction space to calculate change sets and write out the changes. The unit of work transaction space is separate from the shared session cache. For more information, see "Unit of Work Architecture" in the Oracle TopLink Developer's Guide. |
|
|
|
|
Using TopLink persistence API, you can configure fetch groups, which allow you to retrieve a subset of a bean's attributes. This is equivalent of lazy loading. For more information, see "Using Queries with Fetch Groups" in the Oracle TopLink Developer's Guide. |
|
|
|
|
Using TopLink persistence API, you can configure whether or not OC4J executes persistence-related lifecycle methods even if OC4J does not believe that any of the persistence data has changed. When set to true, this option means that OC4J will still execute the EJB lifecycle by invoking the For more information, see "Configuring a Descriptor With EJB Information" in the Oracle TopLink Developer's Guide |
|
|
|
|
Using TopLink persistence API, database transaction isolation levels are not that relevant to TopLink because it provides an object cache and unit of work transaction space. Consider configuring TopLink unit of work and cache isolation levels instead. Handling locking through database isolation levels is rarely done. Typically, locking is done through optimistic or pessimistic locking. You can configure transaction isolation level on a TopLink database login: this setting applies to all beans and transactions that use the database login. By default, TopLink uses whatever isolation level is set on the database. For more information, see:
|
|
|
|
|
Defines the local JNDI name to which this EJB will be bound |
|
|
|
|
Name of the OC4J local home wrapper class for this bean. This is an internal server value and should not be edited. |
|
|
|
|
The JNDI-name to which this bean will be bound. |
|
|
|
|
Using TopLink persistence API, you can configure the following locking modes:
For more information, see "Concurrency (Locking) Mode". |
|
|
|
|
The maximum number of bean implementation instances to be kept instantiated or pooled. The default is 0, which means infinite. To disable instance pooling, set See "Configuring Bean Instance Pool Size" for more information. |
|
|
|
|
This parameter specifies the number of times to retry a transaction that was rolled back due to system-level failures. The default is 0. Generally, we recommend that you 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 in this case, you should leave max-tx-retries=0. Default Value: 0. See the EJB section in the Oracle Application Server Performance Guide for more information. |
|
|
|
|
The minimum number of bean implementation instances to be kept instantiated or pooled. The default is 0. See "Configuring Bean Instance Pool Size" for more information. |
|
|
|
|
The name of the bean, which matches the name of a bean in the assembly section of the EJB deployment descriptor ( |
|
|
|
|
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. See "Configuring Bean Instance Pool Timeouts for Entity Beans" for more information |
|
|
|
|
Using TopLink persistence API, you can specify the name of the database table associated with this bean. For more information, see "Configuring Associated Tables" in the Oracle TopLink Developer's Guide |
|
|
|
|
Using TopLink persistence API, the TopLink unit of work always calculates a change set and generates an update statement for changed fields only. |
|
|
|
|
Using TopLink persistence API, you can configure an invalidation policy to For more information, see "Cache Invalidation" in the Oracle TopLink Developer's Guide. |
|
|
|
|
Name of the OC4J remote home wrapper class for this bean. This is an internal server value and should not be edited. |
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=...
dequeue-retry-count=... dequeue-retry-interval=... >
<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-destination-ref-mapping location=... name=... />
<config-property>
<config-property-name> ... </config-property-name>
<config-property-value> ... </config-property-value>
</config-property>
</message-driven-deployment>
Table A-3 lists the attributes for the <message-driven-deployment> element and their J2CA message service provider resource adapter <config-property> equivalents (where appropriate).
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:
For information on message service providers that OC4J supports, see "What Message Providers Can I use with My MDB?".
The <env-entry-mapping> element maps environment variables to JNDI names and is discussed in "Configuring an Environment Reference to an Environment Variable".
The <ejb-ref-mapping> element maps any EJB references to JNDI names and is discussed in "Configuring an Environment Reference to an EJB".
The <resource-ref-mapping> element maps any resource manager references to JNDI names and is discussed in "Resource Manager Connection Factory Environment 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> element is used to declare the destination. Thus, the <resource-env-ref-mapping> element maps the destination object. See "Configuring an Environment Reference to a JMS Destination or Connection Resource Manager Connection Factory (JMS 1.0)" for more information.
The <message-destination-ref-mapping> element is only used if you are using JMS 1.1. Use this element to map the message-destination-ref-name in the client deployment descriptor to another location that is available in the OC4J environment. It provides means of linking message consumers and producers to one or more common logical destinations. For more information, see "Configuring an Environment Reference to a JMS Destination Resource Manager Connection Factory (JMS 1.1)".
The <config-property> element is only used if you are using a J2CA message service provider. Use this element to set J2CA resource adapter configuration properties. When OC4J deploys an MDB configured to use a J2CA message service provider, OC4J provides the MDB's activation specification to the resource adapter. This specification includes the properties you set in the <config-property> element.
For more information, see:
Table A-3 Attributes for the <message-driven-deployment> Element
| Attribute | <config-property> Equivalent | Description |
|---|---|---|
|
|
Use attribute. |
This parameter specifies how long to keep message-driven beans cached in the pool. If you specify a pool-cache-timeout, then at every 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 cache-timeout is disabled and beans are not removed from the pool. Default Value: 60 (seconds) |
|
The JNDI location of the connection factory to use. The JMS |
||
|
Specifies how often the listener thread tries to re-acquire the JMS session once database failover has ocurred. The default is "0." This value is only for CMT transactions in an MDB. For more information, see: |
||
|
Specifies the interval between retries. The default is 60 seconds. For more information, see: |
||
|
The JNDI location of the destination (queue/topic) to use. The JMS |
||
|
The listener threads are used to concurrently consume JMS messages. The default is one thread. Topics can only have one thread. Queues can have more than one. For more information, see "Configuring Listener Threads". |
||
|
The maximum number of times OC4J will attempt the immediate re delivery of a message to a message-driven bean's For more information, see "Configuring Maximum Delivery Count". |
||
|
|
Use attribute. |
The maximum number of bean implementation instances to be kept instantiated or pooled. The default is 0, which means infinite. To disable instance pooling, set For message-driven beans, the default pooling setting is typically appropriate. Change this value only if MDB lifecycle methods are very expensive and you need fine-grained control over how often instances are created and managed in the pool. See "Configuring Bean Instance Pool Size" for more information. |
|
|
Use attribute. |
The minimum number of bean implementation instances to be kept instantiated or pooled. The default is 0. See "Configuring Bean Instance Pool Size" for more information. |
|
|
Use attribute. |
The name of the bean, which matches the name of a bean in the assembly section of the EJB deployment descriptor ( |
|
|
Use attribute. |
The name of the resource adapter instance that this MDB uses. Applicable only if this MDB is using a J2CA message service provider. In order for the MDB to be activated by messages received by the resource adapter, the MDB and resource adapter must be connected. For more information, see "Configuring a Message Service Provider Using J2CA". |
|
If this is a topic, the subscription name is defined in the |
||
|
This attribute controls the transaction timeout interval (in seconds) for any container-managed transactional MDB. The default is one day or 86,400 seconds. If the transaction has not completed in this time frame, the transaction is rolled back. This applies to both normal JMS and J2CA resource adapter-based message providers. For more information, see "Configuring a Transaction Timeout for a Message-Driven Bean" |
Footnote 1 J2CA message service provider resource adapters read this attribute but ignore all other <message-driven-deployment> attributes. For other <message-driven-deployment> attributes, use the resource adapter equivalent <config-property>.
If you still use EJB 1.1 CMP entity beans, use the following elements to map the CMP fields to the database.
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>
<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>
</cmp-field-mapping>
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:
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>
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>>
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" for more information.
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".
The mapping of the assembly descriptor elements.
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.
Specifies 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.
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.
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.
The default method access policy for methods not tied to a method-permission.
A short description.
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.
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.
The beans contained in this EJB JAR file.
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.
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.
do-select-before insert - If false, you 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 we recommend setting 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. Default Value: true
exclusive-write-access - 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. In this case, it increases the performance for common bean operations and enables better caching. The default is false.
findByPrimaryKey-lazy-loading="true|false" - 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 is false. See "Configuring Lazy Loading on Finder Methods" for more information.
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 "How do You Avoid Database Resource Contention?" and Oracle 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.
locking-mode - The concurrency modes configure when to block to manage resource contention or when to execute in parallel. For more information, see "How do You Avoid Database Resource Contention?" and Oracle 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 0, which means infinite. To disable instance pooling, set max-instances to any negative number. This will create a new instance at the start of the EJB call and release it at the end of the call. See "Configuring Bean Instance Pool Size" for more information.
min-instances - The number of minimum bean implementation instances to be kept instantiated or pooled. The default is 0. See "Configuring Bean Instance Pool Size" 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 0. Leave the 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 leave this value at 0 and add retries only where errors are seen that could be resolved through a retry.
tx-retry-wait—This parameter specifies the time to wait in seconds between retrying the transaction. The default is 60 seconds.
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.
wrapper - Name of the OC4J remote home wrapper class for this bean. (internal server attribute, do not edit)
Specified the configuration for persisting an entity reference through 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.
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.
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.
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 advanced 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".
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 is false. See "Configuring Lazy Loading on Finder Methods" for more information.
prefetch-size - Oracle JDBC drivers include extensions that allow you to 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. The number of rows to prefetch can be set as desired. The default number of rows to prefetch to the client is 10. The number set here is passed along to the JDBC driver. See the Oracle Database JDBC Developer's Guide and Reference for more information on using prefetch with a JDBC driver.
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.
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.
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:
Specifies a mapping of the map key. Map keys are always immutable.
Attributes:
Maps multiple <message-destination-ref> elements to the same destination. Using the <message-destination-ref> element link attribute, you can associate multiple <message-destination-ref> elements with the same <message-destination>. Using the <message-destination-mapping>, you can bind the <message-destination> with a destination resource.
Attributes:
Maps the <message-destination-ref> in the client deployment descriptor to another location that is available in the OC4J environment. For more information, see "Configuring an Environment Reference to a JMS Destination Resource Manager Connection Factory (JMS 1.1)".
Attributes:
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. Topics can only have one thread; queues can have more than one thread.
transaction-timeout: This attribute controls the transaction timeout interval (in seconds) for any container-managed transactional MDB. The default is one day or 86,400 seconds. If the transaction has not completed in this time frame, the transaction is rolled back.
dequeue-retry-count—Specifies how often the listener thread tries to re-acquire the JMS session once database failover has incurred. This value is only for CMT transactions in an MDB. The default is "0." See "Understanding OC4J EJB Application Clustering Services" for more information.
dequeue-retry-interval—Specifies the interval between retries. The default is 60 seconds.
Specify the methods (and possibly parameters of that method) of the bean.
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.
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.
The method-param element contains the fully-qualified Java type name of a method parameter.
The method-params element contains a list of the fully-qualified Java type names of the method parameters.
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)
Designates how the primary key is mapped.
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.
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:
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> element is used to declare the destination. Thus, the <resource-env-ref-mapping> element maps the destination object. See "Resource Manager Connection Factory Environment References" for more information.
Attributes:
The runtime mapping (to groups and users) of a role. Maps to a security-role of the same name in the assembly descriptor.
Attributes:
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". The default is 90,000.
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 - This attribute controls the number of bean instances allowed in memory—either instantiated or pooled. When this value is reached, the container attempts to passivate the oldest bean instance from memory. If unsuccessful, the container waits the number of milliseconds set in the call-timeout attribute to see if a bean instance is removed from memory, either through passivation, its remove() method, or bean expiration, before a TimeoutExpiredException is thrown back to the client. To allow an infinite number of bean instances, the max-instances attribute can be set to zero. To disable instance pooling, set max-instances to any negative number. This will create a new instance at the start of the EJB call and release it at the end of the call. Default is 0, which is infinite. This applies to both stateless and stateful session beans. See "Configuring Bean Instance Pool Size" for more information.
max-instances-threshold - This attribute defines the percentage of max-instances number of beans that can be in memory before passivation occurs. When this threshold is reached, passivation of beans occurs. For example, if max-instances is 100 beans, when max-instances-threshold reaches 90, OC4J begins passivation.
max-tx-retries—The number of times to retry a transaction that was rolled back due to system-level failures. The default is 0. 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 leave this value to 0 and add retries only where errors are seen that could be resolved through a retry.
tx-retry-wait—This parameter specifies the time to wait in seconds between retrying the transaction. The default is 60 seconds.
memory-threshold - This attribute defines a threshold for how much used JVM memory is allowed before passivation should occur. Specify an integer that is translated as a percentage. When reached, beans are passivated, even if their idle timeout has not expired. Default: 80%. To disable, specify "never."
min-instances - The number of minimum bean implementation instances to be kept instantiated or pooled. The default is zero. This applies only to stateless session beans.
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).
resource-check-interval - The container checks all resources at this time interval. At this time, if any of the thresholds have been reached, passivation occurs. Default: 180 sec. (3 min.). To disable, specify "never."
passivate-count - This attribute is an integer that defines the number of beans to be passivated if any of the resource thresholds have been reached. Passivation of beans is performed using the least recently used algorithm. Default: one-third of the max-instances attribute. You can disable this attribute by setting the count to zero or a negative number.
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.
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.
A user that this security-role-mapping implies.
Attributes:
name - The name of the user.
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.
