EJB.11.4 Application Assembler s Responsibilities

EJB.11.4 Application Assembler's Responsibilities

This section describes the view and responsibilities of the application assembler.

There is no mechanism for an application assembler to affect enterprise beans with bean-managed transaction demarcation. The application assembler must not define transaction attributes for an enterprise bean with bean-managed transaction demarcation .

The application assembler can use the transaction attribute mechanism described below to manage transaction demarcation for enterprise beans using container-managed transaction demarcation.

EJB.11.4.1 Transaction Attributes

Note

The transaction attributes may be specified either by the bean provider or by the application assembler.

A transaction attribute is a value associated with a method of an enterprise bean's remote or home interface. The transaction attribute specifies how the container must manage transactions for a method when a client invokes the business method via the enterprise bean home or remote interface.

The transaction attribute must be specified for the following remote and home interface methods :

• For a session bean, the transaction attributes must be specified for the methods defined in the bean's remote interface and all the direct and indirect superinterfaces of the remote interface, excluding the methods of the javax.ejb.EJBObject interface. Transaction attributes must not be specified for the methods of a session bean's home interface.

• For an entity bean, the transaction attributes must be specified for the methods defined in the bean's remote interface and all the direct and indirect superinterfaces of the remote interface, excluding the getEJBHome , getHandle , getPrimaryKey , and isIdentical methods; and for the methods defined in the bean's home interface and all the direct and indirect superinterfaces of the home interface, excluding the getEJBMetaData and getHomeHandle methods.

Providing the transaction attributes for an enterprise bean is an optional requirement for the application assembler, because, for a given enterprise bean, the application assembler must either specify a value of the transaction attribute for all the methods of the remote and home interfaces for which a transaction attribute must be specified, or the assembler must specify none . If the transaction attributes are not specified for the methods of an enterprise bean, the deployer will have to specify them.

Enterprise JavaBeans defines the following values for the transaction attribute:

• NotSupported

• Required

• Supports

• RequiresNew

• Mandatory

• Never

Refer to Section EJB.11.6.2 for the specification of how the value of the transaction attribute affects the transaction management performed by the container.

If an enterprise bean implements the javax.ejb.SessionSynchronization interface, the application assembler can specify only the following values for the transaction attributes of the bean's methods: Required , RequiresNew , or Mandatory .

The above restriction is necessary to ensure that the enterprise bean is invoked only in a transaction. If the bean were invoked without a transaction, the container would not be able to send the transaction synchronization calls.

The tools used by the application assembler can determine if the bean implements the javax.ejb.SessionSynchronization interface, for example, by using the Java programming language reflection API on the enterprise bean's class.

The following is the description of the deployment descriptor rules that the application assembler uses to specify transaction attributes for the methods of the enterprise beans' remote and home interfaces. (See Section EJB.16.5 for the complete syntax of the deployment descriptor.)

The application assembler uses the container-transaction elements to define the transaction attributes for the methods of the enterprise beans' remote and home interfaces. Each container-transaction element consists of a list of one or more method elements and the trans-attribute element. The container-transaction element specifies that all the listed methods are assigned the specified transaction attribute value. It is required that all the methods specified in a single container- transaction element be methods of the same enterprise bean.

The method element uses the ejb- name , method-name , and method-params elements to denote one or more methods of an enterprise bean's home and remote interfaces. There are three legal styles of composing the method element:

Style 1:

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

This style is used to specify a default value of the transaction attribute for the methods for which there is no Style 2 or Style 3 element specified. There must be at most one container-transaction element that uses the Style 1 method element for a given enterprise bean.

Style 2:

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

This style is used for referring to a specified method of the remote or home interface of the specified enterprise bean. If there are multiple methods with the same overloaded name, this style refers to all the methods with the same name. There must be at most one container-transaction element that uses the Style 2 method element for a given method name. If there is also a container- transaction element that uses the Style 1 element for the same bean, the value specified by the Style 2 element takes precedence.

Style 3:

 <method>       <ejb-name>  EJBNAME  </ejb-name>       <method-name>  METHOD  </method-name>       <method-params>            <method-param>  PARAMETER_1  </method-param>            ...            <method-param>  PARAMETER_N  </method-param>       </method-params>  </method> 

This style is used to refer to a single method within a set of methods with an overloaded name. The method must be one defined in the remote or home interface of the specified enterprise bean. If there is also a container-transaction ele-ment that uses the Style 2 element for the method name, or the Style 1 element for the bean, the value specified by the Style 3 element takes precedence.

The optional method-intf element can be used to differentiate between methods with the same name and signature that are defined in both the remote and home interfaces.

The following is an example of the specification of the transaction attributes in the deployment descriptor. The updatePhoneNumber method of the EmployeeRecord enterprise bean is assigned the transaction attribute Mandatory ; all other methods of the EmployeeRecord bean are assigned the attribute Required . All the methods of the enterprise bean AardvarkPayroll are assigned the attribute RequiresNew .

 <ejb-jar>     ...     <assembly-descriptor>        ...        <container-transaction>           <method>              <ejb-name>EmployeeRecord</ejb-name>              <method-name>*</method-name>           </method>           <trans-attribute>Required</trans-attribute>        </container-transaction>        <container-transaction>           <method>              <ejb-name>EmployeeRecord</ejb-name>              <method-name>updatePhoneNumber</method-name>           </method>           <trans-attribute>Mandatory</trans-attribute>        </container-transaction>        <container-transaction>           <method>              <ejb-name>AardvarkPayroll</ejb-name>              <method-name>*</method-name>           </method>           <trans-attribute>RequiresNew</trans-attribute>        </container-transaction>     </assembly-descriptor>  </ejb-jar>