Oracle8i Enterprise JavaBeans Developer's Guide and Reference Release 3 (8.1.7) Part Number A83725-01 |
Library | Service | Contents | Index

## Enterprise JavaBean Deployment Descriptor

This is the main deployment descriptor that contains most of the information about the bean: the bean identification, security roles, transaction demarcation, and any optional environment definition.

- Header

- JAR file

- Enterprise JavaBeans Descriptor

- Application Assembler Section

- EJB Client JAR Section

### Header

The following is the required header for all Oracle8i EJB deployment descriptors. It details the XML version and the XML DTD file, which details the syntax required for the descriptor.

##### XML Version Number

    <?xml version="1.0"?>

##### DTD Filename

    <!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems Inc.//DTD Enterprise JavaBeans 1.1
    //EN" "ejb-jar.dtd">

### JAR file

The first element to be declared is the `<ejb-jar>` element. Within this element, you define two sections: the `<enterprise-beans>` section and the `<assembly-descriptor>` section.

Deployment Section | Description
`<enterprise-beans>` | This section defines each bean and each bean's environment.
`<assembly-descriptor>` | This section defines security roles and transactional attributes for the beans. If you decide to use the defaults, this section is optional.

The overall structure for the EJB deployment descriptor follows this syntax:

    <ejb-jar>                            //Start of JAR file descriptor
     <description> </description>        //Description of JAR file
     <enterprise-beans>                  //EJB Descriptor section
      . . .
     </enterprise-beans>
     <assembly-descriptor>               //Application Descriptor section
      . . .
     </assembly-descriptor>
     <ejb-client-jar>                    //specify output JAR file for
     ...                                 //client stubs
     </ejb-client-jar>
    </ejb-jar>

### Enterprise JavaBeans Descriptor

The beans are described within the `<enterprise-beans>` section. This section contains information such as the type of bean--entity or session, the home interface name, the remote interface name, the bean class name, and the type of persistence--container-managed or bean-managed. The following shows the elements contained within the `<enterprise-beans>` section.

    <enterprise-beans>                       //beginning of the EJB descriptor
     <entity> or <session>                   //define EJB type: entity or session
      <description> </description>           //text display description
      <ejb-name> </ejb-name>                 //logical name for the bean
      <home> </home>                         //home interface name
      <remote> </remote>                     //remote interface name
      <ejb-class> </ejb-class>               //bean class name
      <persistence-type> </persistence-type> //For entity beans: container or
                                             //bean-managed?
      <prim-key-class> </prim-key-class>     //For entity beans: primary key class
      <primkey-field> </prim-key-field>     //For entity beans: primary key field
      <reentrant> </reentrant>               //Reentrant boolean: True or False
      <cmp-field> </cmp-field>               //Container-managed
                                             //fields for entity beans
      <transaction-type> </transaction-type> //transaction information for bean
      <env-entry> </env-entry>               //bean environment definition
      <ejb-ref> </ejb-ref>                   //EJB environment definition
      <resource-ref> </resource-ref>         //database resource environment
      <security-role-ref> </security-role-ref>  //security role for bean
     </session> or </entity>
    </enterprise-beans>

#### Type of Bean

The first item you must define is whether the bean is a session or an entity bean. You do this with the `<entity>` or `<session>` element.

#### Bean Names

There are four names necessary to define the bean within the descriptor:

- The home interface is defined within the `<home>` element.

- The remote interface is defined within the `<remote>` element.

- The bean class is defined within the `<ejb-class>` element.

- The logical name within the JAR file is defined within the `<ejb-name>` element. You can do one of two things with this element. You can declare the actual JNDI name within this element or you can define a logical name that identifies your bean within the deployment descriptor. Ultimately, the `<ejb-name>` must resolve to the JNDI bound name for the bean. So, if you use a logical name, this name must be mapped to the JNDI name within the Oracle-specific deployment descriptor.

  #### Example A-1 Purchase Order Bean Descriptor

The following defines the purchase order bean as an entity bean with the following components:

- home interface--`purchase.PurchaseOrderHome`

- remote interface--`purchase.PurchaseOrder`

- bean implementation--`purchaseServer.PurchaseOrderBean`

- logical name for the bean within the descriptor--`/test/purchase`

  Note: This example used the JNDI name, "`/test/purchase`", within the `<ejb-name>` element. If a logical name had been used, such as `PurchaseOrder`, then `PurchaseOrder` would have to be mapped to "`/test/purchase`" within the `<mappings>` element in the Oracle-specific deployment descriptor. See "Defining Mappings" for more information.

         <enterprise-beans>
            <entity>
               <description>no description</description>
               <ejb-name>test/purchase</ejb-name>
               <home>purchase.PurchaseOrderHome</home>
               <remote>purchase.PurchaseOrder</remote>
               <ejb-class>purchaseServer.PurchaseOrderBean</ejb-class>
               <persistence-type>Container</persistence-type>
               <prim-key-class>java.lang.String</prim-key-class>
               <reentrant>False</reentrant>
            </entity>
         </enterprise-beans>

#### Entity Bean Elements

Certain elements define items that pertain only to entity beans. These are as follows:

- Define the bean as container-managed or bean-managed through the `<persistence-type>` element. Value can be either "`Container`" or "`Bean`".

- Define the data fields for a container-managed persistent (CMP) entity bean with the `<cmp-field>` element. Each data field is listed within its own `<cmp-field>` `<field-name>` section.

- Define the primary key for the entity bean. Note that this is only required for CMP beans.

  The primary key can be declared as a single field of a Java type that is consistent with SQL types, such as `java.lang.String` or declared as a combination of several container-managed fields. The one restriction is that you cannot define the primary key to be a byte array that is mapped to a Long Raw column in the database.

  Primary Key Declaration | Methodology Required
  --- | ---
  Java data type consistent with SQL types | You declare the data type for the primary key within the `<prim-key-class>` element. Define the field that will become the primary key as CMP within a `<cmp-field>` element. Designate the CMP field by defining it within the `<primkey-field>` element.
  Combination of container-managed persistent fields for primary key | Define all fields within the primary key as CMP within the `<cmp-field>` element. Define a serializable class of the name `<``bean_name``>PK` that contains the names of the <`cmp-field>` elements that are included in the primary key. List the primary key class within the `<prim-key-class>` element.

  #### Example A-2 CMP Entity Bean

In this example, the customer bean is a CMP entity bean with a customer number as its primary key and two persistent fields: customer name and address.

- The bean is defined as container-managed persistent within the `<persistence-type>` element.

- The primary key is a customer id, `custid`, which is declared as `java.lang.String`.

  1. The `custid` is defined in a `<cmp-field>.`

  2. Map the `custid` to the primary key within `<primkey-field>`

  3. Declare the `custid`'s data type within the `<prim-key-class>` element.

- The other container-managed persistent fields are defined within the `<cmp-field>` elements as `name` and `addr`.

  Note: The method for translating the container-managed fields into actual persistent storage is dependent on the persistent manager that you choose. See "Defining Container-Managed Persistence" for more information.

  ####

      <enterprise-beans>
        <entity>
            <description>customer bean</description>
            <ejb-name>/test/customer</ejb-name>
            <home>customer.CustomerHome</home>
            <remote>customer.Customer</remote>
            <ejb-class>customerServer.CustomerBean</ejb-class>
            <persistence-type>Container</persistence-type>
            <prim-key-class>java.lang.String</prim-key-class>
            <primkey-field>custid</primkey-field>
            <reentrant>False</reentrant>
            <cmp-field><field-name>custid</field-name></cmp-field>
            <cmp-field><field-name>name</field-name></cmp-field>
            <cmp-field><field-name>addr</field-name></cmp-field>
        </entity>
      </enterprise-beans>

      Example A-3  CMP Entity Bean with Complex Primary Key

In this example, the customer bean is a CMP entity bean with a complex primary key defined within its own serializable class. In addition, the CMP bean declares two persistent fields: customer name and address.

- The bean is defined as container-managed persistent within the `<persistence-type>` element.

- The primary key is defined within the `customer.CustomerPK` class.

  1. The elements of the primary key are a customer last name and date of birth: `custname` and `dobirth`. Both fields are defined in a `<cmp-field>.`

  2. Declare the custid's data type within the `<prim-key-class>` element.

- The other container-managed persistent fields are defined within the `<cmp-field>` elements as `name` and `addr`.

  Note: The method for translating the container-managed fields into actual persistent storage is dependent on the persistent manager that you choose. See "Defining Container-Managed Persistence" for more information.

      <enterprise-beans>
        <entity>
            <description>customer bean</description>
            <ejb-name>/test/customer</ejb-name>
            <home>customer.CustomerHome</home>
            <remote>customer.Customer</remote>
            <ejb-class>customerServer.CustomerBean</ejb-class>
            <persistence-type>Container</persistence-type>
            <prim-key-class>customer.CustomerPK</prim-key-class>
            <reentrant>False</reentrant>
            <cmp-field><field-name>custname</field-name></cmp-field>
            <cmp-field><field-name>dobirth</field-name></cmp-field>
            <cmp-field><field-name>name</field-name></cmp-field>
            <cmp-field><field-name>addr</field-name></cmp-field>
        </entity>
      </enterprise-beans>

#### Environment Elements

You can create three types of environment elements that are accessible to your bean during runtime: environment variables, EJB references, and resource managers (JDBC `DataSource`). These environment elements are static and can not be changed by the bean.

ISVs typically develop EJBs that are independent from the EJB container. In order to distance the bean implementation from the container specifics, you can create environment elements that map to one of the following: defined variables, entity beans, or resource managers. This indirection enables the bean developer to refer to existing variables, EJBs, and a JDBC `DataSource` without specifying the actual name. These names are defined in the deployment descriptor and are linked to the actual names within the Oracle-specific deployment descriptor.

##### Environment variables

you can create environment variables that your bean can access through a lookup on the `InitialContext`. These variables are defined within an `<env-entry>` element and can be of the following types: `String`, `Integer`, `Boolean`, `Double`, `Byte`, `Short`, `Long`, and `Float`. The name of the environment variable is defined within `<env-entry-name>`, the type is defined in `<env-entry-type>`, and its initialized value is defined in `<env-entry-value>`. The `<env-entry-name>` is relative to the "`java:comp/env"` context.

For example, the following two environment variables are declared within the XML deployment descriptor for `java:comp/env/minBalance` and `java:comp/env/maxCreditBalance`.

    <env-entry>
         <env-entry-name>minBalance</env-entry-name>
         <env-entry-type>java.lang.Integer</env-entry-type>
         <env-entry-value>500</env-entry-value>
        </env-entry>
    <env-entry>
         <env-entry-name>maxCreditBalance</env-entry-name>
         <env-entry-type>java.lang.Integer</env-entry-type>
         <env-entry-value>10000</env-entry-value>
    </env-entry>

Within the bean's code, you would access these environment variables through the `InitialContext`, as follows:

    InitialContext ic = new InitialContext();
    Integer min = (Integer)ic.lookup("java:comp/env/minBalance");
    Integer max = (Integer) ic.lookup("java:comp/env/maxCreditBalance"));

Notice that to retrieve the values of the environment variables, you prefix each environment element with "`java:comp/env/`", which is the location that the container stored the environment variable.

##### Environment References To Other Enterprise JavaBeans

You can define a reference to an EJB within the deployment descriptor. If you know that your bean will call out to another bean, you can define this reference within the deployment descriptors. The `deployejb` tool binds the EJB reference to the bean's home interface, which enables the target bean to be retrieved without the originating bean needing to know the exact JNDI name for the target. Either way, you use JNDI to retrieve the target bean's home. Once retrieved, the bean referenced by the returned EJB reference is instantiated in the same session.

Declaring the target bean as an environment EJB reference provides a level of indirection, so that the originating bean can refer to the target bean with a logical name. This is useful when the target bean's JNDI name within the name space may be different depending on the operating environment.

To define an EJB within the environment, you provide the following:

1. Name--provide a logical name for the target bean. This name is what the bean uses within the JNDI URL for accessing the target bean. The name should begin with "`ejb/`", such as "`ejb/myEmployee`", and will be available within the "`java:comp/env/ejb`" context.

2. Type--define whether the bean is a session or an entity bean. Value should be either "`Session`" or "`Entity`".

3. Home--provide the fully qualified home interface name.

4. Remote--provide the fully qualified remote interface name.

5. LinkÞ--provide a name that links this EJB reference with the actual JNDI URL.

   As shown in Figure A-1, the logical name for the bean is mapped to the JNDI name by providing the same link name, "`HelloWorldBean`", in both the `<ejb-link>` in the EJB deployment descriptor and the `<ejb-name>` within the `<ejb-mapping>` element in the Oracle-specific deployment descriptor.

   Note: Using the `<ejb-link>` field to map a logical name to a JNDI URL defined within the Oracle-specific deployment descriptor is a different implementation than stated within the Enterprise JavaBeans 1.1 specification.

   #### Figure A-1 EJB Reference Mapping

   #### Example A-4 Defining an EJB Reference Within the Environment

The following example defines a reference to the `Hello` bean, as follows:

1. The logical name used for the target bean within the originating bean is "`java:comp/env/ejb/HelloWorld`".

2. The target bean is a session bean.

3. Its home interface is `hello.HelloHome`; its remote interface is `hello.Hello`.

4. The link to the JNDI URL for this bean is defined in the Oracle-specific deployment descriptor under the "`HelloWorldBean`" name.

As shown in Figure A-1, the `<ejb-link>` is mapped to `<ejb-name>` within the `<ejb-mapping>` element in the Oracle-specific deployment descriptor by providing the same logical name in both elements. The Oracle-specific deployment descriptor would have the following definition to map the logical bean name of "`java:comp/env/ejb/HelloWorld`" to the JNDI URL "`/test/myHello`".

Note: For more information on the Oracle-specific deployment descriptor, see "Oracle-Specific Deployment Descriptor".

To invoke this bean from within your implementation, you use the <`ejb-ref-name`> defined in the deployment descriptor. You prefix this name with "`java:comp/env/ejb/`", which is where the container places the EJB references defined in the deployment descriptor.

    InitialContext ic = new InitialContext();
    HelloHome hh = (HelloHome)ic.lookup("java:comp/env/ejb/HelloWorld");

##### Environment References To Resource Manager Connection Factory References

The resource manager connection factory references can include resource managers such as JMS, mail, XML, and JDBC DataSource objects. In this release, the only resource manager connection factory that Oracle8i supports is the JDBC `DataSource`.

Similar to the EJB references, you can access a database through JDBC either using the traditional method or by creating an environment element for a JDBC `DataSource`.

In order to create an environment element for your JDBC `DataSource`, you must do the following:

1. Bind your JDBC `DataSource` within the JNDI name space.

2. Create a logical name within the EJB deployment descriptor. This name should always start with "`java:comp/env/jdbc`".

3. Map the logical name within the EJB deployment descriptor to the JNDI name, created in step 1, within the Oracle-specific deployment descriptor.

As shown in Figure A-2, the JDBC `DataSource` was bound to the JNDI name "`test/OrderDataSource`". The logical name that the bean knows this resource as is "`jdbc/OrderDB`". These names are mapped together within the Oracle-specific deployment descriptor. Thus, within the bean's implementation, the bean can retrieve the connection to `OrderDataSource` by using the "`java:comp/env/jdbc/OrderDB`" environment element.

#### Figure A-2 JDBC Resource Manager Mapping

The JDBC `DataSource` environment element is defined with the following information:

Element | Description
--- | ---
`<res-ref-name>` | The logical name of the JDBC DataSource to be used within the originating bean. The name should be prefixed with "`jdbc`/". In our example, the logical name for our ordering database is "`jdbc/OrderDB`".
`<res-type>` | The Java type of the resource. For JDBC, this is `javax.sql.DataSource`.
`<res-auth>` | Define who is responsible for signing on to the database. At this time, the only value supported is "`Application`". The application provides the authentication information for the database by providing the username and password within the DataSource.

#### Example A-5 Defining an environment element for JDBC Connection

The environment element is defined within the EJB deployment descriptor by providing the logical name, "`jdbc/OrderDB`", its type of `javax.sql.DataSource`, and the authenticator of "`Application`".

The environment element of "`jdbc/OrderDB`" is mapped to the JNDI bound name for the connection, "`test/OrderDataSource`" within the Oracle-specific deployment descriptor.

Once deployed, your application can retrieve the JDBC DataSource as follows:

    javax.sql.DataSource db;
    java.sql.Connection conn;
    .
    .
    .
    db = (javax.sql.DataSource) initCtx.lookup("java:comp/env/jdbc/OrderDB");
    conn = db.getConnection();

#### Bean Services

The transaction, security, and reentrancy for the bean is defined by the following elements:

- Define reentrancy for the bean through the `<reentrant>` element. Value should be either "`True`" or "`False`".

- Define the type of transaction demarcation for a session bean through the `<transaction-type>` element. Value should be "`Bean`" if the session bean uses bean demarcation or "`Container`" if the session bean uses container demarcation for its transaction control.

  Note that the transaction information--for both session and entity beans--is defined in more detail within the `<assembly-descriptor>` section. See "Defining Transactions" for more information.

- Define the security role logical name for the bean with the `<security-role-ref>` element. This refers to a security role name used within the bean and should map to an actual security role defined within the `<assembly-descriptor>` section. See "Defining Security" for more information.

  #### Example A-6 Reentrancy, Transaction Demarcation, and Security Role

The following example defines a customer bean that is not reentrant, uses bean-demarcated transactions, and uses the "`CustRole`" logical name within the bean implementation when referring to its security role. This role name is mapped to SCOTT.

    <enterprise-beans>
      <session>
         <ejb-name>CustomerBean</ejb-name>
         <home>customer.CustomerHome</home>
         <remote>customer.Customer</remote>
         <ejb-class>customerServer.CustomerBean</ejb-class>
         <reentrant>False</reentrant>
         <transaction-type>Bean</transaction-type>
         <security-role-ref>
           <role-name>CustRole</role-name>
           <role-link>SCOTT</role-link>
         </security-role-ref>
      </session>
    </enterprise-beans>

### Application Assembler Section

The application assembler adds generic information about all of the beans in this descriptor in the `<assembly-descriptor>` section. This section has the following structure:

    <assembly-descriptor>
     <security-role> </security-role>
     <method-permission> </method-permission>
     <container-transaction>  </container-transaction>
    </assembly-descriptor>

These sections describe the security and transaction attributes.

#### Defining Security

You can manage some of your security for the user and method permissions from within the deployment descriptor. If you do not specify any method permissions, the default is that no users are allowed access.

In addition, as shown in Figure A-3, you can use a logical name for a role within your bean implementation, and map this logical name to the correct database role or user. The mapping of the logical name to a database role is specified in the Oracle-specific deployment descriptor. See "Security Role" for more information.

#### Figure A-3 Security Mapping

If you use a logical name for a database role within your bean implementation for methods such as `isCallerInRole`, you can map the logical name to an actual database role by doing the following:

1. Declare the logical name within the `<enterprise-beans>` section `<security-role-ref>` element. For example, to define a role used within the purchase order example, you may have checked, within the bean's implementation, to see if the caller had authorization to sign a purchase order. Thus, the caller would have to be signed in under a correct role. In order for the bean to not need to be aware of database roles, you can check `isCallerInRole` on a logical name, such as `POMgr`, since only purchase order managers can sign off on the order. Thus, you would define the logical security role, POMgr within the `<security-role-ref><role-name>` element within the `<enterprise-beans>` section, as follows:

       <enterprise-beans>
       ...
         <security-role-ref>
          <role-name>POMgr</role-name>
          <role-link>SCOTT</role-link>
         </security-role-ref>
       </enterprise-beans>

   The `<role-link>` element within the `<security-role-ref>` element can be the actual database role, which is defined further within the `<assembly-descriptor>` section. Alternatively, it can be another logical name, which is still defined more in the `<assembly-descriptor>` section and is mapped to an actual database role within the Oracle-specific deployment descriptor.

2. Define the role and the methods that it applies to. In the purchase order example, any method executed within the `PurchaseOrder` bean must have authorized itself as SCOTT. Note that `PurchaseOrder` is the name declared in the `<entity` | `session><ejb-name>` element.

   Thus, the following defines the role as SCOTT, the EJB as `PurchaseOrder`, and all methods by denoting the '*' symbol.

   Note: SCOTT is the same as the `<role-link>` element within the `<enterprise-beans>` section. This ties the logical name of `POMgr` to the SCOTT definition.

       <assembly-descriptor>
        <security-role>
         <description>Role needed purchase order authorization</description>
         <role-name>SCOTT</role-name>
        </security-role>
        <method-permission>
         <role-name>SCOTT</role-name>
         <method>
          <ejb-name>PurchaseOrder</ejb-name>
          <method-name>*</method-name>
         </method>
        </method-permission>
       ...
       </assembly-descriptor>

After performing both steps, you can refer to POMgr within the bean's implementation and the container translates POMgr to SCOTT.

The `<method>` element is used to define one or more methods within an interface or implementation. According to the EJB specification, this definition can be of one of three forms:

1. Defining all methods within a bean by specifying the bean name and using the '*' character to denote all methods within the bean, as follows:

       <method>
       	<ejb-name>EJBNAME</ejb-name>
       	<method-name>*</method-name>
       </method>

2. Defining a specific method that is uniquely identified within the bean. Use the appropriate interface name and method name, as follows:

       <method>
       	<ejb-name>myBean</ejb-name>
       	<method-name>myMethodInMyBean</method-name>
       </method>

   Note: If there are multiple methods with the same overloaded name, the element of this style refers to all the methods with the overloaded name.

3. Defining a method with a specific signature among many overloaded versions, as follows:

       <method>
       	<ejb-name>myBean</ejb-name>
       	<method-name>myMethod</method-name>
       	<method-params>
       		<method-param>javax.lang.String</method-param>
       		<method-param>javax.lang.String</method-param>

       	<method-params>
       <method>

   The parameters are the fully-qualified Java types of the method's input parameters. If the method has no input arguments, the <`method-params`> element contains no elements. Arrays are specified by the array element's type, followed by one or more pair of square brackets, such as `int`[][].

4. Defining a specific method name that is defined in two or more interfaces. You could have the same method name defined both in the bean implementation and within either the remote or home interface. In this case, you must specify which method you are defining by using the <`method-intf`> element, as follows:

       <method>
       	<ejb-name>EmployeeService</ejb-name>
       	<method-intf>Remote</method-intf>
       	<method-name>create</method-name>
       	<method-params>
       		<method-param>java.lang.String</method-param>
       		<method-param>java.lang.String</method-param>
       	</method-params>
       </method>

   Defining the remote interface in the <`method-intf`> element differentiates the `create(String, String)` method defined in the remote interface from the `create(String, String)` method defined in the home interface, which would be defined as follows:

       <method>
       	<ejb-name>EmployeeService</ejb-name>
       	<method-intf>Home</method-intf>
       	<method-name>create</method-name>
       	<method-params>
       		<method-param>java.lang.String</method-param>
       		<method-param>java.lang.String</method-param>
       	</method-params>
       </method>

   Note: The <`method-intf`> element must be defined before the <`method-name`> element.

#### Defining Transactions

Entity beans can only use container-managed transactions; session beans can use either bean-managed or container-managed transactions. If you have a session bean, you define whether it uses bean or container-managed transactions within the `<enterprise-beans>` section with the `<transaction-type>` element. Values should be either "`Bean`" or "`Container`". For example, the following defines a session bean as a bean-managed transactional bean:

    <enterprise-beans>
     <session>
      . . .
      <transaction-type>Bean</transaction-type>
     </session>
    </enterprise-beans>

For container-managed beans, you define the how the container maintains the transactions for the bean through transaction attributes. The transaction attributes define in what situations to start a new transaction, to continue an existing transaction, and others. If you have a bean-managed bean, you do not define any of these attributes for the bean. However, if your bean-managed bean invokes another bean, the target bean can be either bean or container-managed.

The transaction attributes are specified in the <trans-attribute> element and are detailed in Table A-1.

Table A-1 Transaction Attributes

Transaction Attribute | Description
--- | ---
`NotSupported` | The bean is not involved in a transaction. If the client calls the bean while involved in a transaction, the client's transaction is suspended, the bean executes, and when the bean returns to the client, the client's transaction is resumed.
`Required` | The bean must be involved in a transaction. If the client is involved in a transaction, the bean uses the client's transaction. If the client is not involved in a transaction, the container starts a new transaction for the bean.
`Supports` | Whatever transactional state that the client is involved in is used for the bean. If the client has begun a transaction, the client's transaction context is used by the bean. If the client is not involved in a transaction, neither is the bean.
`RequiresNew` | Whether the client is involved in a transaction or not, this bean requires a new transaction that exists only for itself. If the client calls while involved in a transaction, the client's transaction is suspended until the bean completes.
`Mandatory` | The client must be involved in a transaction before invoking this bean. The bean uses the client's transaction context.
`Never` | The bean is not involved in a transaction. Furthermore, the client cannot be involved in a transaction when calling the bean. If the client is involved in a transaction, a `RemoteException` is thrown.

You can define the transaction attributes on a whole bean or on an individual method within the bean. Each definition is contained within the `<container-transaction>` element. If you are defining an attribute for the entire bean, you supply the bean name (the `<ejb-name>` defined within the `<session>` or `<entity>` element) within the `<container-transaction>` `<method>` `<ejb-name>` element.

The following example defines the following:

- All methods (denoted by the '*' character) within the `PurchaseOrder` bean must have a transaction (Required).

  Note: The methods can be specified exactly as within the <`method-permission`> element. See "Defining Security" for more information.

- The `price` method within the `PurchaseOrder` bean must always have a new transaction (RequiresNew).

      <assembly-descriptor>
      ...
       <container-transaction>
        <method>
          <ejb-name>PurchaseOrder</ejb-name>
          <method-name>*</method-name>
         </method>
         <trans-attribute>Required</trans-attribute>
       </container-transaction>
       <container-transaction>
        <method>
          <ejb-name>PurchaseOrder</ejb-name>
          <method-name>price</method-name>
         </method>
         <trans-attribute>RequiresNew</trans-attribute>
       </container-transaction>
       . . .
      </assembly-descriptor>

Finally, if you are using two-phase commit for your global transaction, you must provide the `UserTransaction` object's JNDI name to the `<transaction-manager>` element within the Oracle-specific deployment descriptor. See "Defining Two Phase Commit Engine for Transactions" for more information.

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index