The <session> and <entity> elements, which describe session and entity beans, usually contain many nested elements. The lists of allowable subelements are similar, so we’ll discuss the <session> and <entity> elements together.

Like the <ejb-jar> element, a <session> or <entity> element can optionally contain <description>, <display-name>, <small-icon>, and <large-icon> elements. These are fairly self-explanatory and, in any case, have the same meanings as when they appear in the <ejb-jar> element. The <description> lets you provide a comment that describes the enterprise bean; the <display-name> is used by deployment tools to represent the enterprise bean; and the two icon elements are used to represent the enterprise bean in visual environments. The icon elements must point to JPEG or GIF images within the JAR file. The other elements are more interesting:

The <message-driven> element describes message-driven bean deployments. <message-driven> elements occur after <entity> and <session> elements within the <enterprise-bean> element. Like the <entity> and <session> elements, the <message-driven> element can optionally have <description>, <display-name>, <small-icon>, and <large-icon> elements. These elements are used primarily by visual deployment tools to represent the message-driven bean. The <message-driven> element also requires the declaration of the <ejb-name>, <ejb-class>, <transaction-type>, and <security-id-entity> elements. In addition, it contains the standard JNDI ENC elements <env-entry>, <ejb-ref>, <ejb-local-ref>, <resource-ref>, and <resource-env-ref>. These are fairly self-explanatory and have the same meaning as they did in the <entity> and <session> elements.

The elements specific to the message-driven bean are different in EJB 2.1 and EJB 2.0.

<message-selector>
<![CDATA[
    TotalCharge >500.00 AND ((TotalCharge /ItemCount)>=75.00)
    AND State IN ('MN','WI','MI','OH')";]]>
</message-selector>

<query>
    <query-method>
        ...
    </query-method>
    <ejb-ql>
        <![CDATA[
            SELECT OBJECT(r ) FROM Reservation r
            WHERE r.amountPaid  > 300.00
        ]]>
    </ejb-ql>
 </query>

If a single field in the bean can serve naturally as a unique identifier, you can use that field as the primary key. Optionally, a custom primary key can be used as a compound primary key. In the Cabin EJB, for example, the primary key type could be the CabinPK, which is mapped to the bean class fields id and name, as shown here (the CabinBean is using bean-managed persistence to better illustrate):

public class CabinBean implements javax.ejb.EntityBean {

    public int id;
    public String name;
    public int deckLevel;
    public int ship;
    public int bedCount;
 
    public CabinPK ejbCreate(int id, String name) {
        this.id = id;
        this.name = name;
        return null;
    }
    ...
}

In Chapter 4, we used the appropriate primitive wrapper, java.lang.Integer, instead of the custom CabinPK class, and defined the CabinBean as:

public class CabinBean implements javax.ejb.EntityBean {

    public int id;
    public String name;
    public int deckLevel;
    public int ship;
    public int bedCount;
 
    public Integer ejbCreate(int id) {
        this.id = id;
        return null;
    }
    ...
}

This simplifies things a lot. Instead of taking the time to define a custom primary key like CabinPK, we simply use the appropriate wrapper. To do this, we need to add a <primkey-field> element to the Cabin EJB’s deployment descriptor, so it knows which field to use as the primary key. We also need to change the <prim-key-class> element to state that the Integer class is being used to represent the primary key. Here’s how the Cabin EJB’s deployment descriptor would need to change to use Integer as the primary key field:

<entity>
    <description>
        This Cabin enterprise bean entity represents a cabin on 
        a cruise ship.
    </description>
    <ejb-name>CabinEJB</ejb-name>
    <home>com.titan.cabin.CabinHome</home>
    <remote>com.titan.cabin.Cabin</remote>
    <ejb-class>com.titan.cabin.CabinBean</ejb-class>
    <persistence-type>Bean</persistence-type>
    <prim-key-class>java.lang.Integer</prim-key-class>
    <reentrant>False</reentrant>

    <cmp-field><field-name>id</field-name></cmp-field>
    <cmp-field><field-name>name</field-name></cmp-field>
    <cmp-field><field-name>deckLevel</field-name></cmp-field>
    <cmp-field><field-name>ship</field-name></cmp-field>
    <cmp-field><field-name>bedCount</field-name></cmp-field>
    <primkey-field>id</primkey-field>
</entity>

Simple primary key fields are not limited to the primitive wrapper classes (Byte, Boolean, Integer, and so on); any container-managed field can be used as a primary key, as long as it is serializable. String types are probably the most common, but other types, such as java.lang.StringBuffer, java.util.Date, or even java.util.Hashtable are also valid. Custom types can also be primary keys, provided they are serializable. Use common sense when choosing a primary key: since it is used as an index to the data in the database, it should be lightweight.

// bean class for bean that uses a deferred primary key 
public class HypotheticalBean implements javax.ejb.EntityBean {
    ...
    public java.lang.Object ejbCreate( ) {
        ...
        return null;
    }
    ...
}

// home interface for bean with deferred primary key
public interface HypotheticalHome extends javax.ejb.EJBHome {
    public Hypothetical create( ) throws ...;
    public Hypothetical findByPrimaryKey(java.lang.Object key) throws ...;
}

// primkey-field declaration for the Hypothetical bean
...
<entity>
    <ejb-name>HypotheticalEJB</ejb-name>
    ...
    <persistence-type>Container</persistence-type>
    <prim-key-class>java.lang.Object</prim-key-class>
    <reentrant>False</reentrant>
    <cmp-field><field-name>creationDate</field-name></cmp-field>
    ...
</entity>

A deployment descriptor can define environment entries, values similar to properties the bean can read when it is running. The bean can use environment entries to customize its behavior, find out about how it is deployed, and so on.

The <env-entry> element is used to define environment entries. This element contains the subelements <description> (optional), <env-entry-name> (required), <env-entry-type> (required), and <env-entry-value> (optional). Here is a typical <env-entry> declaration:

<env-entry>
    <env-entry-name>minCheckNumber</env-entry-name>
    <env-entry-type>java.lang.Integer</env-entry-type>
    <env-entry-value>2000</env-entry-value>
</env-entry>

The <env-entry-name> is relative to the "java:comp/env" context. For example, the minCheckNumber entry can be accessed using the path "java:comp/env/minCheckNumber" in a JNDI ENC lookup:

InitialContext jndiContext = new InitialContext( );
Integer miniumValue = (Integer)
    jndiContext.lookup("java:comp/env/minCheckNumber");

The <env-entry-type> can be of type String or one of several primitive wrapper types, including Integer, Long, Double, Float, Byte, Boolean, and Short.

The <env-entry-value> is optional. The value can be specified by the bean developer or deferred to the application assembler or deployer.

In EJB, references to other beans can be local or remote. In EJB 2.1 you can also reference a web Service object that provides access to an EJB endpoint (see Chapter 15 to learn more about EJB endpoints).

<ejb-ref>
    <ejb-ref-name>ejb/ProcessPaymentHomeRemote</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <home>com.titan.processpayment.ProcessPaymentHomeRemote</home>
    <remote>com.titan.processpayment.ProcessPaymentHomeRemote</remote>
</ejb-ref>

InitialContext jndiContext = new InititalContext( );
Object ref = jndiContext.lookup("java:comp/env/ejb/ProcessPaymentHomeRemote");
ProcessPaymentHomeRemote home = (ProcessPaymentHomeRemote)
    PortableRemoteObject.narrow(ref, ProcessPaymentHomeRemote.class);

<ejb-jar>
    <enterprise-beans>
        <session>
            <ejb-name>TravelAgentEJB</ejb-name>
            <remote>com.titan.travelagent.TravelAgentRemote</remote>
            ...
            <ejb-ref>
                <ejb-ref-name>ejb/ProcessPaymentHome</ejb-ref-name>
                <ejb-ref-type>Session</ejb-ref-type>
                <home>com.titan.processpayment.ProcessPaymentHomeRemote</home>
                <remote>com.titan.processpayment.ProcessPaymentRemote</remote>
                <ejb-link>ProcessPaymentEJB</ejb-link>
            </ejb-ref>
            ...
        </session>

        <session>
            <ejb-name>ProcessPaymentEJB</ejb-name>
            <remote>com.titan.processpayment.ProcessPaymentRemote</remote>
            ...
        </session>
        ...
    </enterprise-beans>
    ...
</ejb-jar>

<ejb-local-ref>
    <ejb-ref-name>ejb/CruiseHomeLocal</ejb-ref-name>
    <ejb-ref-type>Entity</ejb-ref-type>
    <local-home>com.titan.cruise.CruiseHomeLocal</local-home>
    <local>com.titan.cruise.CruiseLocal</local>
    <ejb-link>CruiseEJB</ejb-link>
</ejb-local-ref>
<ejb-local-ref>
    <ejb-ref-name>ejb/CabinHomeLocal</ejb-ref-name>
    <ejb-ref-type>Entity</ejb-ref-type>
    <local-home>com.titan.cabin.CabinHomeLocal</local-home>
    <local>com.titan.cabin.CabinLocal</local>
    <ejb-link>CabinEJB</ejb-link>
</ejb-local-ref>

InitialContext jndiContext = new InititalContext( );
CabinHome home = (CabinHome)
    jndiContext.lookup("java:comp/env/ejb/CabinHomeLocal");

Enterprise beans also use the JNDI ENC to look up external resources, such as database connections, that they need to access. The mechanism for doing this is similar to the mechanism used for referencing other beans and environment entries: the external resources are mapped into a name within the JNDI ENC namespace. For external resources, the mapping is performed by the <resource-ref> element.

The <resource-ref> element contains the <description> (optional), <res-ref-name> (required), <res-type> (required), and <res-auth> (required) subelements.

Here is a <resource-ref> declaration used for a DataSource connection factory:

<resource-ref>
    <description>DataSource for the Titan database</description>
    <res-ref-name>jdbc/titanDB</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
</resource-ref>

The <res-ref-name> is relative to the "java:comp/env" context. Although not a requirement, it is a good idea to place connection factories under a subcontext that describes the resource type. For example:

Here is how a bean would use JNDI to look up a resource—in this case, a DataSource:

InitialContext jndiContext = new InitialContext( );
DataSource source = (DataSource)
    jndiContext.lookup("java:comp/env/jdbc/titanDB");

The <res-type> element declares the fully qualified class name of the connection factory. In this example, the <res-type> is javax.sql.DataSource.

The <res-auth> element tells the server who is responsible for authentication. It can have one of two values: Container or Application. If Container is specified, the container will automatically perform authentication (sign-on or login) to use the resource, as specified at deployment time. If Application is specified, the bean itself must perform authentication before using the resource. Here’s how a bean might sign on to a connection factory when Application is specified for <res-auth>:

InitialContext jndiContext = new InitialContext( );
DataSource source = (DataSource)
    jndiContext.lookup("java:comp/env/jdbc/titanDB");

String loginName = ejbContext.getCallerPrincipal( ).getName( );
String password = ...; // get password from somewhere

// use login name and password to obtain a database connection
java.sql.Connection con = source.getConnection(loginName, password);

TopicConnectionFactory factory = (TopicConnectionFactory)
    jndiContext.lookup("java:comp/env/jms/TopicFactory");
        
Topic topic = (Topic)
    jndiContext.lookup("java:comp/env/ejb/TicketTopic");

<resource-ref>
    <res-ref-name>jms/TopicFactory</res-ref-name>
    <res-type>javax.jms.TopicConnectionFactory</res-type>
    <res-auth>Container</res-auth>
</resource-ref>
<resource-ref>
    <res-ref-name>jdbc/titanDB</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
</resource-ref>
<resource-env-ref>
    <resource-env-ref-name>jms/TicketTopic</resource-env-ref-name>
    <resource-env-ref-type>javax.jms.Topic</resource-env-ref-type>
</resource-env-ref>

<resource-ref>
    <res-ref-name>jdbc/titanDB</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
   <res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>

EJB 2.1 includes a new element, <service-ref>, that is used to bind a JAX-RPC Service to the JNDI ENC. The modified TravelAgent EJB declares a <service-ref> element that looks like this:

<ejb-jar 
 xmlns="http://java.sun.com/xml/ns/j2ee"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

                      xmlns:chargeIt="http://charge-it.com/Processor"
 xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                    http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd"
 version="2.1">
   <enterprise-beans>
     <session>
       <ejb-name>TravelAgentEJB</ejb-name>
       ...
       <service-ref>
                  <service-ref-name>service/ChargeItProcessorService</service-ref-name>
                  <service-interface>com.charge_it.ProcessorService</service-interface>
                  <wsdl-file>META-INF/wsdl/ChargeItProcessor.wsdl</wsdl-file>
                  <jaxrpc-mapping-file>META-INF/mapping.xml</jaxrpc-mapping-file>
                  <service-qname>chargeIt:ProcessorService</service-qname>
                         </service-ref>
      ...
    </session>
  </enterprise-beans>
  ...
</ejb-jar>

The <service-ref-name> element declares the JNDI ENC lookup name of the JAX-RPC Service: it is always relative to the "java:comp/env" context. For more details about various web service deployment descriptors, see Chapter 15.

The <security-role-ref> element defines the security roles that are used by a bean and maps them into the security roles that are in effect for the runtime environment. It can contain three subelements: an optional <description>, a <role-name> (required), and an optional <role-link>.

Here’s how security roles are defined. When a role name is used in the EJBContext.isCallerInRole(String roleName) method, the role name must be statically defined (it cannot be derived at runtime) and it must be declared in the deployment descriptor using the <security-role-ref> element:

<-- security-role-ref declaration for Account bean -->
<entity>
    <ejb-name>AccountEJB</ejb-name>
    ...
    <security-role-ref>
        <description>
            The caller must be a member of this role in 
            order to withdraw over $10,000
        </description>
        <role-name>Manager</role-name>
        <role-link>Administrator</role-link>
    </security-role-ref>
    ...
</entity>

The <role-name> defined in the deployment descriptor must match the role name used in the EJBContext.isCallerInRole( ) method. Here is how the role name is used in the bean’s code:

// Account bean uses the isCallerInRole( ) method
public class AccountBean implements EntityBean {
    int id;
    double balance;
    EntityContext context;

    public void withdraw(Double withdraw) throws AccessDeniedException {
        
        if (withdraw.doubleValue( ) > 10000) {
            boolean isManager = context.isCallerInRole("Manager");
            if (!isManager) {
                // only Managers can withdraw more than 10k
                throw new AccessDeniedException( );
            }
        }
        balance = balance - withdraw.doubleValue( );
    }
    ...
}

The <role-link> element is optional; it can be used to map the role name used in the bean to a logical role defined in a <security-role> element in the <assembly-descriptor> section of the deployment descriptor. If no <role-link> is specified, the deployer must map the <security-role-ref> to an existing security role in the target environment.

EJB QL statements are declared in <query> elements in an entity bean’s deployment descriptor. In the following listing, you can see that findByName( ) and ejbSelectShips( ) methods were declared in the <query> elements of the Cruise EJB deployment descriptor:

<ejb-jar>
    <enterprise-beans>
        <entity>
            <ejb-name>ShipEJB</ejb-name>
            ...
            <abstract-schema-name>Ship</abstract-schema-name>
            ...
        </entity>
        <entity>
            <ejb-name>CruiseEJB</ejb-name>
            ...
            <reentrant>False</reentrant>
            <abstract-schema-name>Cruise</abstract-schema-name>
            <cmp-version>2.x</cmp-version>
            <cmp-field>
                <field-name>name</field-name>
            </cmp-field>
            <primkey-field>id</primkey-field>
            <query>
                <query-method>
                    <method-name>findByName</method-name>
                    <method-params> 
                  <mehod-param>java.lang.String</method-param>
                    </method-params>
                </query-method>
                <ejb-ql>
                  SELECT OBJECT(c) FROM Cruise c WHERE c.name = ?1
                </ejb-ql>
            </query>
            <query>
                <query-method>
                    <method-name>ejbSelectShips</method-name>
                    <method-params></method-params>
                </query-method>
                <result-type-mapping>Remote</result-type-mapping>
                <ejb-ql>
                    SELECT OBJECT(s) FROM Ship AS s
                </ejb-ql>
            </query>
        </entity>
    </enterprise-beans>
</ejb-jar>

The <query> element contains two primary elements; the <query-method> element identifies the find method of the remote or local home interface, and the <ejb-ql> element declares the EJB QL statement. The <query> element binds the EJB QL statement to the proper find method. The syntax of EJB QL may cause problems for the XML parser; you may need to wrap the query in a CDATA section. See the sidebar “CDATA Sections” for more details.

When two find methods in the local and remote home interfaces have the same method name and parameters, the query declaration applies to both methods. The container returns the proper type for each query method: queries that use the remote home return one or more remote EJB objects, and queries that use the local home return one or more local EJB objects. This feature allows you to define the behavior of both the local and remote home find methods using a single <query> element—which is convenient if you want local clients to have access to the same find methods as remote clients.

The <result-type-mapping> element can be used to declare whether a select method should return local or remote EJB objects. The value Local indicates that a method should return local EJB objects; Remote indicates remote EJB objects. If the <result-type-mapping> element is not declared, the default is Local. In the <query> element for the ejbSelectShips( ) method, the <result-type-mapping> is declared as Remote, which means the query should return remote EJB object types (i.e., remote references to the Ship EJB).

Every entity bean that is referenced in an EJB QL statement must have an abstract schema name , which is declared by the <abstract-schema-name> element. No two entity beans may have the same abstract schema name. In the entity element that describes the Cruise EJB, the abstract schema name is Cruise, while the Ship EJB’s abstract schema name is Ship. The <ejb-ql> element contains an EJB QL statement that uses this identifier in its FROM clause.

In Chapter 7, you learned that the abstract persistence schema of an entity bean is defined by its <cmp-field> and <cmr-field> elements. The abstract schema name is also an important part of the abstract persistence schema. EJB QL statements are always expressed in terms of the abstract persistence schemas of entity beans. EJB QL uses the abstract schema names to identify entity bean types, the container-managed persistence (CMP) fields to identify specific entity bean data, and the container-managed relationship (CMR) fields to create paths for navigating from one entity bean to another.