Skip Headers
Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide
10g (10.1.3.5.0)
E13981-01
Go to Documentation Home
Home		 Go to Book List
Book List		 Go To Table Of Contents
Contents		 Go To Index
Index		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

<entity-deployment>

The <entity-deployment> section provides additional deployment information for an EJB 2.x or EJB 1.1 entity bean deployed within this JAR file.


Note:

All <entity-deployment> attributes and sub-elements apply only to EJB 2.x or EJB 1.1 entity beans. They are not applicable to JPA entities.

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=... remote=... jndi-properties=... />
  <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>

For information on each of these elements and sub-elements, see the following:

Examples

For entity bean examples, which include <entity-deployment> configuration (where relevant), see "Implementing an EJB 2.1 Entity Bean".

<entity-deployment> Attributes

Table A-2 lists the attributes for the <entity-deployment> element.

For more information about OC4J support for TopLink persistence, see "TopLink Persistence Support".

Table A-2 Attributes for the <entity-deployment> Element

Attribute Configurable in orion-ejb-jar.xml Configurable Using TopLink Persistence API Description

call-timeout

Unsupported

Supported

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 the following:

clustering-schema

Supported

Unsupported

Do not use. Not needed in this release.

copy-by-value

Supported

Unsupported

Whether or not to copy (clone) all the incoming and outgoing parameters in EJB calls. Set to false if you are certain that your application does not assume copy-by-value semantics for a speed-up.

The default value is true.

data-source

Supported

Unsupported

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

delay-updates-until-commit

Unsupported

Supported

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.

disable-default-persistent-unit

Supported

Unsupported

By default, OC4J enables the deployment of EJB 3.0 entities without a persistence.xml file if your application only uses the OC4J default persistence unit. To disable this feature, set to true.

The default is false.

For more information, see "Understanding OC4J Persistence Unit Defaults".

do-select-before-insert

Unsupported

Unsupported

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

exclusive-write-access

Unsupported

Supported

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.

findByPrimaryKey-lazy-loading

Unsupported

Supported

Using TopLink persistence API, you can configure fetch groups, which let you 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.

force-update

Unsupported

Supported

Using TopLink persistence API, you can configure whether or not OC4J executes persistence-related life cycle 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 life cycle by invoking the ejbStore method. This manages data in transient fields and sets appropriate persistent fields during the ejbStore method. For example, an image might be kept in one format in memory, but stored in a different format in the database.

The default value is false.

For more information, see "Configuring a Descriptor With EJB Information" in the Oracle TopLink Developer’s Guide

isolation

Unsupported

Supported

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 the following:

local-location

Supported

Unsupported

Defines the local JNDI name to which this bean will be bound

local-wrapper

Supported

Unsupported

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

location

Supported

Unsupported

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

locking-mode

Unsupported

Supported

Using TopLink persistence API, you can configure the following locking modes:

  • Optimistic Locking: Multiple users have read access to the data. When a user attempts to make a change, the application checks to ensure the data has not changed since the user read the data. TopLink supports version (recommended), timestamp, and field-level locking.

  • Pessimistic Locking: The first user who accesses the data with the purpose of updating it locks the data until completing the update. 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.

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

For more information, see "Concurrency (Locking) Mode".

max-instances

Supported

Unsupported

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

max-tx-retries

Supported

Unsupported

This parameter specifies the number of times to retry a transaction that was rolled back due to system-level failures.

The default value is 0.

Generally, Oracle recommends 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.

min-instances

Supported

Unsupported

The minimum number of bean implementation instances to be kept instantiated or pooled.

The default value is 0.

See "Configuring Bean Instance Pool Size" for more information.

name

Supported

Unsupported

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

Supported

Unsupported

The amount of time in seconds that the bean implementation instances are to be kept in the "pooled" (unassigned) state. Specifying any negative number retains the instances until they are garbage collected. The default is 60. See "Configuring Bean Instance Pool Timeouts for Entity Beans" for more information

table

Unsupported

Supported

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

tx-retry-wait

Supported

Unsupported

This parameter specifies the time to wait in seconds between retrying the transaction. The default is 60 seconds.Foot 1 

update-changed-fields-only

Unsupported

Supported

Using TopLink persistence API, the TopLink unit of work always calculates a change set and generates an update statement for changed fields only.

validity-timeout

Unsupported

Supported

Using TopLink persistence API, you can configure an invalidation policy to

For more information, see "Cache Invalidation" in the Oracle TopLink Developer’s Guide.

wrapper

Supported

Unsupported

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

Footnote 1  you specify this attribute, you cannot enable XML validation (see "Validating XML Files").

<ior-security-config>

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

<primkey-mapping>

The <primkey-mapping> element maps the primary key to the container-managed persistent field it represents. In this release, this feature is not configured in orion-ejb-jar.xml file. OC4J automatically makes this configuration. To manually configure this feature, you use TopLink persistence API.

For more information, see the following:

<cmp-field-mapping>

If you still use EJB 1.1 entity beans with container-managed persistence, use the <cmp-field-mapping> element to map the container-managed persistent fields to the database.

The following are the XML elements used for container-managed persistent data field mapping within the orion-ejb-jar.xml file for EJB 1.1 entity beans with container-managed persistence:

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

For EJB 3.0 entities and EJB 2.1 entity beans, this feature is not configured in orion-ejb-jar.xml file. OC4J automatically makes this configuration. To manually configure this feature, you use TopLink persistence API.

For more information, see the following:

<finder-method>

The <finder-method> element is used to create finder methods for EJB 1.1 entity beans.

For more information, see the following:

<env-entry-mapping>

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

<ejb-ref-mapping>

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

<service-ref-mapping>

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"

<resource-ref-mapping>

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

<resource-env-ref-mapping>

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.

<message-destination-ref-mapping>

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

<commit-option>

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. This is discussed in "What are Entity Bean Commit Options?".

  Previous
Previous 		 Next
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go To Table Of Contents
Contents		 Go To Index
Index		 Go to Feedback page
Contact Us