OC4J-Specific Deployment Descriptor for EJBs

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

local-location

The local JNDI name to which this EJB will be bound.

max-instances

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. Default is 0, which means infinite. This applies to both stateless and stateful session beans.

To disable instance pooling, set max-instances to any negative number in the orion-ejb-jar.xml file. This will create a new instance at the start of the EJB call and release it at the end of the call.

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. The default is 0.

For a stateful session bean, if a RuntimeException, Error, or RemoteException is thrown, the OC4J does not do a retry.

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.

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

transaction-timeout

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.

idletime

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

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

max-instances-threshold

Percentage of max-instances number of beans that can be in memory before passivation occurs.

Specify an integer that is translated as a percentage. If you define that the max-instances is 100 and the max-instances-threshold is 90%, then when the active bean instances is greater than or equal to 90, passivation of beans occurs. Default: 90%.

To disable, specify "never."

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.

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.

replication

Configuration of the state replication for stateful session beans. Values can be inherited (default) onShutdown, onRequestEnd, or none. See "State Replication" for more information.

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

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 "Configuring Exclusive Write Access to the Database" for more information.

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

location

The JNDI-name to which this bean will be bound.

local-location

Defines the local JNDI name to which this EJB 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 "How do You Avoid Database Resource Contention?" and Oracle Application Server Performance Guide.

locking-mode

This attribute applies only to Orion CMP.

For more information on TopLink CMP locking modes, see "Concurrency (Locking) Mode".

max-instances

The maximum number of bean implementation instances to be kept instantiated or pooled. The default is 0, which means infinite. See "Configuring Bean Instance Pool Size" for more information.

min-instances

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.

max-tx-retries

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.

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.

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.

findByPrimaryKey-lazy-loading

true or false

Default: true

connection-factory- location

ConnectionFactoryTimeout

The JNDI location of the connection factory to use. The JMS Destination Connection Factory is specified in this 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

DestinationLocation

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.

resource-adapter^Footref 1

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

name^Footref 1

Use attribute.

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

SubscriptionName

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

listener-threads

ListenerThreads

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

transaction-timeout

TransactionTimeout

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"

dequeue-retry-count

DequeueRetryCount

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:

• "Configuring Dequeue Retry Count and Interval"

• "Understanding OC4J EJB Application Clustering Services"

dequeue-retry-interval

DequeueRetryInterval

Specifies the interval between retries. The default is 60 seconds.

For more information, see:

• "Configuring Dequeue Retry Count and Interval"

• "Understanding OC4J EJB Application Clustering Services"

max-instances^Footref 1

Use attribute.

The maximum number of bean implementation instances to be kept instantiated or pooled. The default is 0, which means infinite. See "Configuring Bean Instance Pool Size" for more information.

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.

min-instances^Footref 1

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.

cache-timeout^Foot 1 

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)

max-delivery-count

MaxDeliveryCnt

The maximum number of times OC4J will attempt the immediate re delivery of a message to a message-driven bean's onMessage method if that method returns failure (fails to invoke an acknowledgment operation, throws an exception, or both). After this number of re deliveries, the message is deemed undeliverable and is handled according to the policies of your message service provider. For example, OracleAS JMS will put the message on its exception queue (jms/Oc4jJmsExceptionQueue).

For more information, see "Configuring Maximum Delivery Count".