View comments | RSS feed

Configuring Enterprise JavaBeans

This section discusses the standard EJB deployment descriptor, ejb-jar.xml, and the JRun-specific deployment descriptor, jrun-ejb-jar.xml. For more information, see the deployment descriptor documentation listed in the jrun_root/docs/descriptordocs/index.html file.

For information about EJB programming, see JRun Programmer's Guide and the resources listed in "About This Book".

JRun provides the following tools that let you develop, package, and deploy EJBs without working directly in the deployment descriptor files:

Understanding the ejb-jar.xml deployment descriptor

You use the standard EJB deployment descriptor, ejb-jar.xml, to configure the elements of an EJB module listed in the following table. A valid ejb-jar.xml file only requires a valid enterprise-beans section, in which the bean developer declares one or more beans. The assembler works with the enterprise-beans section and the assembly-descriptor section. The root element of the file is ejb-jar.

XML element
Required/
Optional

Description
description, display-name, small icon, large icon
Optional
Description, name, and images for use by tools.
enterprise-beans
Required
Declaration of one or more session, entity, or message-driven beans. The bean developer provides the initial values.
The assembler can modify or add the following information when adding an EJB module to an enterprise application:
  • Resource references
  • Security role references that can contain role-links between the security role references the EJB declares and the security roles the assembler defines
  • EJB references that can contain ejb-links to specific beans in an EJB module
relationships
Optional
Description of the relationships in which entity beans with container-managed persistence (CMP) 2.0 participate.
assembly-descriptor
Optional
Assembler's description of how multiple EJBs are composed into an application unit. Includes transaction attributes, method permissions, security roles, and excluded methods.
ejb-client-jar
Optional
Declaration of a JAR file containing the classes a client requires to access the EJB(s).

Understanding the enterprise-beans section

The enterprise-beans section of an ejb-jar.xml file is the only required section. This is where the bean developer declares the beans that are part of the application.

Common elements

The following table describes only those elements under the ejb-jar/enterprise-beans elements that are common to session, entity, and message-driven beans:

XML element
Required/
Optional

Description
session, entity, or message-driven
(parent element)
Required
Type of EJB.
description, display-name, small icon, large icon
Optional
Description, name, and images for use by tools.
ejb-name
Required
Name identifying the bean. If a JNDI name is not specified in a corresponding jndi-name element in the jrun-ejb-jar.xml file, JRun uses the ejb-name as the JNDI name.
You must include home and remote, local-home and local, or all four of the following elements:

home

Fully qualified name of the EJB's home interface.

local-home

Fully qualified name of the EJB's local home interface.

remote

Fully qualified name of the EJB's remote interface.

local

Fully qualified name of the EJB's local interface.
ejb-class
Required
Fully qualified name of the EJB's implementation class.
env-entry
(zero or more)
Optional
EJB's environment entry.
ejb-ref
(zero or more)
Optional
Reference in EJB code to another EJB's home, which allows bean-to-bean method calls.
In the role of assembler, you can include an optional ejb-link element to specify that an EJB reference is linked to an EJB in the same enterprise application. If the EJB is in a different EJB module, you must precede the ejb-name value with the relative path to the EJB module followed by a pound sign (#).
If the other EJB's jrun-ejb-jar.xml file changes its default JNDI name in an ejb-ref element, or the EJB is not in the same EJB module or enterprise application, this EJB's jrun-ejb-jar.xml file must contain a corresponding ejb-local-ref element that contains its JNDI name.
ejb-local-ref
(zero or more)
Optional
Reference in EJB code to another EJB's local home, which allows bean-to-bean method calls.
In the role of assembler, you can include an optional ejb-link element to specify that an EJB local reference is linked to an EJB in the same enterprise application. If the EJB is in a different EJB module, you must precede the ejb-name value with the relative path to the EJB module and a pound sign (#).
If the other EJB's jrun-ejb-jar.xml file changes the default JNDI name of its local home in an ejb-local-ref element, or the EJB is not in the same EJB module or enterprise application, this EJB's jrun-ejb-jar.xml file must contain a corresponding ejb-local-ref element that contains its JNDI name.
security-role-ref
(zero or more)
(not message-driven beans)
Optional
Reference in EJB code to a security role.
security-identity
Optional
Whether to use the caller's associated security role or a specific run-as security role for execution of the EJB's methods. Contains either an empty use-caller-identity element or a run-as element that contains description (optional) and role-name elements.
resource-ref
(zero or more)
Optional
Reference in EJB code to an external resource.
resource-env-ref
(zero or more)
Optional
Reference in EJB code to an administered object associated with an external resource.

Required session bean elements

In addition to the elements required for all types of beans, session beans require the following elements under the ejb-jar/enterprise-beans/session elements:
XML element
Description
session-type
Whether the session bean is a stateful session or stateless session bean; values are Stateful and Stateless.
transaction-type
Whether the EJB uses bean-managed or container-managed transactions; values are Bean and Container.

Required entity bean elements

In addition to the elements required for all types of beans, entity beans require the following elements under the ejb-jar/enterprise-beans/entity elements.
XML element
Description
persistence-type
Whether persistence is container-managed or bean-managed; the values are Container and Bean.
prim-key-class
Fully qualified name of an entity bean's primary-key class. If the bean developer defers the definition of the primary key class until deployment time, set it to java.lang.Object.
reentrant
Boolean value specifying whether the bean is reentrant, which means it can invoke methods on itself or call another bean that invokes a method on it.
abstract-schema-name
Name of the abstract schema type of an entity bean using cmp-version 2.x and EJB Query Language (EJB QL) queries.

Required message-driven bean elements

In addition to the elements required for all types of beans, message-driven beans require the following element under the ejb-jar/enterprise-beans/message-driven elements:
XML element
Description
transaction-type
Whether the EJB uses bean-managed or container-managed transactions; values are Bean and Container.

Understanding the assembly-descriptor section

In the assembly-descriptor section of an ejb-jar.xml file, the assembler defines security roles, method permissions, transaction attributes for EJBs that use container-managed transactions, and methods to exclude from deployment. All of the top-level assembly descriptor elements are optional and are described in the following table:
XML element
Description
security-role
(zero or more)
Declaration of a security role. Must match a security role defined in the JRun environment; for more information, see JRun Administrator's Guide.
method-permission
(zero or more)
Specification that one or more security roles can invoke one or more enterprise bean methods.
container-transaction
(zero or more)
How the container must manage transaction scopes for the EJB's method invocations. Specify one of the following transaction attributes in a trans-attribute element:
  • NotSupported
  • Supports
  • Required
  • RequiresNew
  • Mandatory
  • Never
exclude-list
Set of methods marked as uncallable. Methods in the exclude list are not callable.

Examples: ejb-jar.xml deployment descriptors

The following deployment descriptors provides configuration information for a stateless session bean, a BMP entity bean, a CMP 1.1 entity bean, and a CMP 2.0 entity bean. You can also view the ejb-jar.xml files of the applications on the JRun samples server in the jrun_root/servers/samples directory.

ejb-jar.xml: stateless session bean declaration, assembly descriptor

<?xml version="1.0"?>
<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//
DTD EnterpriseJavaBeans 2.0//EN" "http://java.sun.com/dtd/
ejb-jar_2_0.dtd">
<ejb-jar>
  <enterprise-beans>
    <session>
      <ejb-name>CreditCard</ejb-name>
      <home>compass.CreditCardHomeRemote</home>
      <remote>compass.CreditCardRemote</remote>
      <ejb-class>compass.CreditCardBean</ejb-class>
      <session-type>Stateless</session-type>
      <transaction-type>Container</transaction-type>
      <security-identity><use-caller-identity/></security-identity>
    </session>
  </enterprise-beans>
  <assembly-descriptor>
    <security-role>
      <role-name>everyone</role-name>
    </security-role>
    <method-permission>
      <role-name>everyone</role-name>
      <method>
      <ejb-name>CreditCard</ejb-name>
      <method-name>*</method-name>
      </method>
    </method-permission>
    <container-transaction>
      <method>
        <ejb-name>CreditCard</ejb-name>
        <method-name>*</method-name>
      </method>
      <trans-attribute>Required</trans-attribute>
    </container-transaction>
  </assembly-descriptor>
</ejb-jar>

ejb-jar.xml: BMP entity bean declaration, assembly descriptor

<?xml version="1.0"?>
<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//
DTD EnterpriseJavaBeans 2.0//EN" "http://java.sun.com/dtd/
ejb-jar_2_0.dtd">
<ejb-jar>
  <enterprise-beans>
    <entity>
      <ejb-name>Order</ejb-name>
      <home>compass.OrderHomeRemote</home>
      <remote>compass.OrderRemote</remote>
      <ejb-class>compass.OrderBean</ejb-class>
      <persistence-type>Bean</persistence-type>
      <prim-key-class>java.lang.Integer</prim-key-class>
      <reentrant>False</reentrant>
      <security-identity><use-caller-identity/></security-identity>
    </entity>
  </enterprise-beans>
  <assembly-descriptor>
    <security-role>
      <role-name>everyone</role-name>
    </security-role>
    <method-permission>
      <role-name>everyone</role-name>
      <method>
      <ejb-name>Order</ejb-name>
      <method-name>*</method-name>
      </method>
    </method-permission>
    <container-transaction>
      <method>
      <ejb-name>Order</ejb-name>
      <method-name>*</method-name>
      </method>
      <trans-attribute>Required</trans-attribute>
    </container-transaction>
  </assembly-descriptor>
</ejb-jar>

ejb-jar.xml: CMP 1.1 entity bean declaration

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0/
/EN" "http://java.sun.com/j2ee/dtds/ejb-jar_2_0.dtd">
<ejb-jar>

   <enterprise-beans>
      <entity>
         <ejb-name>Employee</ejb-name>
         <ejb-class>samples.cmp11.EmployeeBean</ejb-class>
         <home>samples.cmp11.EmployeeHome</home>
         <remote>samples.cmp11.Employee</remote>
         <persistence-type>Container</persistence-type>
         <primkey-field>employeeId</primkey-field>
         <prim-key-class>java.lang.String</prim-key-class>
         <reentrant>True</reentrant>
         <cmp-version>1.x</cmp-version>
         <cmp-field>
            <field-name>employeeId</field-name>
         </cmp-field>
         <cmp-field>
            <field-name>firstName</field-name>
         </cmp-field>
         <cmp-field>
            <field-name>lastName</field-name>
         </cmp-field>
         <cmp-field>
            <field-name>phone</field-name>
         </cmp-field>
      </entity>
   </enterprise-beans>
</ejb-jar>

ejb-jar.xml: CMP 2.0 entity bean declaration

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0/
/EN" "http://java.sun.com/j2ee/dtds/ejb-jar_2_0.dtd">
<ejb-jar>
   <enterprise-beans>
      <entity>
         <ejb-name>samples/cmp20/Employee</ejb-name>
         <ejb-class>samples.cmp20.EmployeeBean</ejb-class>
         <home>samples.cmp20.EmployeeHome</home>
         <remote>samples.cmp20.Employee</remote>
         <persistence-type>Container</persistence-type>
         <prim-key-class>java.lang.String</prim-key-class>
         <reentrant>True</reentrant>
         <primkey-field>employeeId</primkey-field>
         <abstract-schema-name>employeeschema</abstract-schema-name>
         <cmp-version>2.x</cmp-version>
         <cmp-field>
            <field-name>employeeId</field-name>
         </cmp-field>
         <cmp-field>
            <field-name>firstName</field-name>
         </cmp-field>
         <cmp-field>
            <field-name>lastName</field-name>
         </cmp-field>
         <cmp-field>
            <field-name>phone</field-name>
         </cmp-field>
         <query>
            <query-method>
               <method-name />
               <method-params />
            </query-method>
            <return-type-mapping>Local</return-type-mapping>
            <ejb-ql>SELECT OBJECT(o) FROM employeeschema AS o</ejb-ql>
         </query>
         <query>
            <query-method>
               <method-name />
               <method-params />
            </query-method>
            <return-type-mapping>Local</return-type-mapping>
            <ejb-ql>SELECT OBJECT(o) FROM employeeschema AS o WHERE o.lastName =
      ?1</ejb-ql>
         </query>
      </entity>
   </enterprise-beans>
</ejb-jar>

Understanding the jrun-ejb-jar.xml deployment descriptor

The JRun-specific EJB deployment descriptor, jrun-ejb-jar.xml, is not required in all situations. You use it to configure elements specific to JRun and not included in the ejb-jar.xml file, such as JNDI names, resource mappings, and JDBC mappings that specify the SQL used to create, load, store, find, and remove CMP 1.1 entity beans.

Note:   You can automatically generate an jrun-ejb-jar.xml file. For more information, see "Working with JRun-specific deployment descriptors," in Chapter�3.

The jrun-ejb-jar.xml file contains the following top-level elements under jrun-ejb-jar:
XML element
Description
description
Description of the EJB module.
source
JNDI name of the data source to be used to deploy the bean(s) or execute a SQL statement.
enterprise-beans
Elements corresponding to the enterprise-beans section in the ejb-jar.xml file. Use this section to configure JNDI mappings, resource mappings, EJB clustering, stateful session bean timeout values, and stateless session bean instance pool sizes.

Understanding the enterprise-beans section

This section describes the subelements of enterprise beans.

Common elements

The following table describes the elements under the jrun-ejb-jar/enterprise-beans elements that are common to session, entity, and message-driven beans; only the ejb-name and jndi-name elements are required:
XML element
Description
session, entity, or message-driven
(parent element)
Type of EJB.
ejb-name
Name that identifies the EJB.
jndi-name
JNDI name of the EJB. If you do not specify a JNDI name here, JRun uses the ejb-name as the JNDI name.
tx-domain-name
Name of the transaction domain in which EJB transactions will take place.
ejb-ref
A mapping between the ejb-ref-name the bean developer provides and its JNDI name. The deployer provides the JNDI name.
This elementis required only to to bind an EJB class into JNDI more than once.
ejb-local-ref
A mapping between the local home's ejb-ref name provided by the EJB developer and its JNDI name. The deployer provides the actual JNDI name.
This element is required only to bind an EJB class into JNDI more than once.
resource-env-ref
A mapping between the resource-env-ref-name that the bean developer provides and its JNDI name. The deployer provides the JNDI name.
This elementis required only to bind an administered object into JNDI more than once.
resource-ref
A mapping between the resource-ref-name that the bean developer provides and its JNDI name. The deployer provides the JNDI name.
This element is required only to bind a resource into JNDI more than once.
cluster-home
Whether the EJB home should be clustered for this bean. If clustering is enabled in the jrun_root/servers/jrun_server/SERVER-INF/jrun.xml file, this value is true by default. You can override this behavior on a bean-by-bean basis using this element.
cluster-object
Whether the EJB object should be clustered for this bean. If clustering is enabled in the jrun_root/servers/jrun_server/SERVER-INF/jrun.xml file, this value is true by default. You can override this behavior on a bean-by-bean basis using this element.

Session bean elements

In addition to the elements required for all types of beans, session bean configuration can include the following optional elements under the jrun-ejb-jar/enterprise-beans/session elements:
XML element
Description
timeout
Timeout value, in seconds, of a stateful session bean. The EJB instance is passivated (disassociated from its EJB object to conserve memory) if left idle for this period of time.
instance-pool
The maximum and minimum size parameters for stateless session bean instance pools.

Entity bean elements

In addition to the elements required for all types of beans, entity bean configuration can include the following optional elements under the jrun-ejb-jar/enterprise-beans/entity elements:
XML element
Description
commit-option
Commit option as described in the EJB 2.0 specification. Valid values are A, B, and C.
always-dirty
Empty XML element that forces synchronization with the data source at the ends of transactions, even when the entity bean's fields have not changed.
jdbc-mappings
Information specific to JRun and not declared in the ejb-jar.xml file about the CMP mappings for a CMP 1.1 entity bean. The contained jdbc-mapping elements specify the SQL used to create, load, store, find, and remove entity beans.

Message-driven bean elements

In addition to the elements required for all types of beans, message-driven bean configuration can include the following optional elements under the jrun-ejb-jar/enterprise-beans/entity elements:
XML element
Description
message-driven-subscription
Client ID to be used by the message-driven container for durable subscription handling
message-driven-destination
Destination the message-driven container uses

Examples: jrun-ejb-jar.xml deployment descriptors

The following deployment descriptors provide configuration information for a stateful session bean, a stateless session bean, and a CMP 1.1 entity bean. You can also view the jrun-ejb-jar.xml files of the applications on the JRun samples server in the jrun_root/servers/samples directory.

jrun-ejb-jar.xml: stateful session bean declaration

This example sets a stateful session bean's JNDI name, disables its home and object clustering, and sets its timeout value.

<?xml version="1.0"?>
<!DOCTYPE jrun-ejb-jar PUBLIC '-//Macromedia, Inc.//DTD jrun-ejb-jar 4.0//EN'
'http://jrun.macromedia.com/dtds/jrun-ejb-jar.dtd'>
<jrun-ejb-jar>
  <enterprise-beans>
    <session>
      <ejb-name>StatefulEJB</ejb-name>
      <jndi-name>StatefulEJB</jndi-name>
      <cluster-home>false</cluster-home>
      <cluster-object>false</cluster-object>
      <timeout>900</timeout>
    </session>
  </enterprise-beans>
</jrun-ejb-jar>

jrun-ejb-jar.xml: stateless session bean declaration

This example sets a stateless session bean's JNDI name and maximum and minimum instance pool sizes; also see the corresponding "ejb-jar.xml: stateless session bean declaration, assembly descriptor".

<?xml version="1.0"?>
<!DOCTYPE jrun-ejb-jar PUBLIC '-//Macromedia, Inc.//DTD jrun-ejb-jar 4.0//EN'
'http://jrun.macromedia.com/dtds/jrun-ejb-jar.dtd'>
<jrun-ejb-jar>
  <enterprise-beans>
    <session>
      <ejb-name>CreditCard</ejb-name>
      <jndi-name>ejb/CreditCard</jndi-name>
      <cluster-home>False</cluster-home>
      <cluster-object>False</cluster-object>
      <instance-pool>
        <minimum-size>1</minimum-size>
        <maximum-size>5</maximum-size>
      </instance-pool>
    </session>
  </enterprise-beans>
</jrun-ejb-jar>

jrun-ejb-jar.xml: CMP 1.1 entity bean declaration

This example sets a CMP 1.1 entity bean's JNDI name and JDBC mappings; also see the corresponding "ejb-jar.xml: CMP 1.1 entity bean declaration".

<?xml version="1.0"?>
<!DOCTYPE jrun-ejb-jar PUBLIC '-//Macromedia, Inc.//DTD jrun-ejb-jar 4.0//EN'
'http://jrun.macromedia.com/dtds/jrun-ejb-jar.dtd'>
<jrun-ejb-jar>
  <enterprise-beans>
    <entity>
      <ejb-name>Employee</ejb-name>
      <jndi-name>Employee</jndi-name>
      <jdbc-mappings>
        <jdbc-mapping>
          <name>create</name>
          <statement>
            <action>INSERT INTO employees (employee_id , first_name , last_name,
      phone) VALUES ( ? , ? , ? , ?)</action>
            <source>samples</source>
            <params>
              <param>
                 <name>employeeId</name>
                 <type>VARCHAR</type>
              </param>
              <param>
                 <name>firstName</name>
                 <type>VARCHAR</type>
              </param>
              <param>
                 <name>lastName</name>
                 <type>VARCHAR</type>
              </param>
              <param>
                 <name>phone</name>
                 <type>VARCHAR</type>
              </param>
            </params>
          </statement>
        </jdbc-mapping>
        <jdbc-mapping>
          <name>load</name>
          <statement>
            <action>SELECT employee_id, first_name, last_name, phone FROM employees
      WHERE employee_id=?</action>
            <source>samples</source>
            <params>
              <param>
                 <name>employeeId</name>
                 <type>VARCHAR</type>
              </param>
            </params>
            <fields>
              <field>employeeId</field>
              <field>firstName</field>
              <field>lastName</field>
              <field>phone</field>
            </fields>
          </statement>
        </jdbc-mapping>
        <jdbc-mapping>
          <name>remove</name>
          <statement>
            <action>DELETE FROM employees WHERE employee_id=?</action>
            <source>samples</source>
            <params>
              <param>
                 <name>employeeId</name>
                 <type>VARCHAR</type>
              </param>
            </params>
          </statement>
        </jdbc-mapping>
        <jdbc-mapping>
          <name>store</name>
          <statement>
            <action>UPDATE employees SET first_name=?, last_name=?, phone=? WHERE
      employee_id=?</action>
            <source>samples</source>
            <params>
              <param>
                 <name>firstName</name>
                 <type>VARCHAR</type>
              </param>
              <param>
                 <name>lastName</name>
                 <type>VARCHAR</type>
              </param>
              <param>
                 <name>phone</name>
                 <type>VARCHAR</type>
              </param>
              <param>
                 <name>employeeId</name>
                 <type>VARCHAR</type>
              </param>
            </params>
          </statement>
        </jdbc-mapping>
        <jdbc-mapping>
          <name>findAll</name>
          <statement>
            <action>SELECT employee_id FROM employees</action>
            <source>samples</source>
            <fields>
              <field>employeeId</field>
            </fields>
          </statement>
        </jdbc-mapping>
        <jdbc-mapping>
          <name>findByLastName</name>
          <statement>
            <action>SELECT employee_id FROM employees WHERE last_name=?1</action>
            <source>samples</source>
            <params>
              <param>
                 <name>lastName</name>
                 <type>VARCHAR</type>
              </param>
            </params>
            <fields>
              <field>employeeId</field>
            </fields>
          </statement>
        </jdbc-mapping>
        <jdbc-mapping>
          <name>findByPrimaryKey</name>
          <statement>
            <action>SELECT employee_id FROM employees WHERE employee_id=?</action>
            <source>samples</source>
            <params>
              <param>
                 <name>employeeId</name>
                 <type>VARCHAR</type>
              </param>
            </params>
            <fields>
              <field>employeeId</field>
            </fields>
          </statement>
        </jdbc-mapping>
      </jdbc-mappings>
    </entity>
  </enterprise-beans>

Comments


sosher said on May 15, 2002 at 4:49 PM :
This is missing an example of the jrun-ejb-jar.xml for EJB 2.0 CMP.
Chetan Arora said on Aug 7, 2003 at 2:53 AM :
I've been reading the entire doc about sescriptors, sample application too is provided but that s not of a very great help. the logic involved is not a core issue involved , u sholud come up witha graphical representation of the directory structure, and let users understand which file is to be stored where, which would make the application run. Again, u must have writren this soewhere in the docs but that s too scattered .Please make a pictorila directorty structure specying the storage of java & descriptor files.
jrunrandy said on Aug 11, 2003 at 7:38 AM :
Look in jrun_root/docs/descriptordocs/index.html to see deployment descriptors in pictorial/javadocs format.
johnqueso said on Feb 11, 2004 at 12:42 PM :
What is the default trans-attribute value, if I don't specify a container-transaction elment in the assembly-descriptor for an EJB method?
Davotoula said on Nov 18, 2004 at 8:58 AM :
Same question as above... OC4J 9.0.4 (Oracle) default is Required...
jrunrandy said on Nov 19, 2004 at 8:51 AM :
I asked one of the JRun developers and this is what he said:

" If the transaction attribute is not specified, then the default is 'Required'. "
emilesvt said on Jan 5, 2005 at 12:10 PM :
I'm having some problems with CMR in the jrun-ejb-jar.xml file. I have an entity that has a 1 to many relationship to another entity. There is a jdbc mapping that the app server is using to pull all child records during entity load, I have let the app server generate this and the name is "jrunmy<something>", ie jrunmyTasks, jrunmyNotes. I need a good example of CMR in JRUN and I just can't find any. Can they be provided please?

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/jrun/4/Assembly_and_Deployment_Guide/descriptors5.htm