Java Enterprise in a Nutshell (In a Nutshell (OReilly))

A.2. Enterprise JavaBeans (ejb-jar.xml)

Enterprise JavaBean components are deployed using a ejb-jar.xml deployment descriptor. The high-level descriptor summary for EJB deployment descriptors is shown in Figure A-8. The following sections provide details on each section of the descriptor. In all the diagrams in this section, deployment elements that were introduced in the EJB 2.1 specification are labelled with a "2.1" indicator. All other elements were present in the 2.0 (and possibly earlier) version of the EJB specification.

The format for an empty ejb-jar.xml file is shown in Example A-8.

Example A-8. EJB deployment descriptor header

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

The example references the XML schema for the EJB 2.1 deployment descriptor from the default location on the java.sun.com server. To reference the EJB 2.0 DTD instead (e.g., if you are using a J2EE 1.3 application server like JBoss 3.x or an EJB 2.0 container plug-in), you should start your deployment descriptor with the following DOCTYPE element and no schema reference:

<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN" "http://java.sun.com/dtd/ejb-jar_2_0.dtd"> <ejb-jar> . . . </ejb-jar>

A.2.1. Session EJB Declarations

Figure A-9 shows the elements used to declare session EJBs in your deployment descriptor.

Example A-9 shows sample session EJB declarations, annotated with descriptive comments.

Example A-9. Annotated session EJB declarations

<ejb-jar . . .> . . . <enterprise-beans> <!-- Declare session EJBs included in this archive. --> <session> <!-- A description of the session EJB being declared. --> <description>desc</description> <!-- A display name to be used in various tools. --> <display-name>name</display-name> <!-- Icon to display in tools. --> <icon> <small-icon>my/icon/file</small-icon> <large-icon>my/icon/file</large-icon> </icon> <!-- A unique name to be used to refer to this EJB component, either within this DD or from other deployment descriptors in the same application assembly. Note that this name is not a JNDI name, it is simply a label used to refer to this EJB from other descriptor elements. --> <ejb-name>MySessionEJB</ejb-name> <!-- The fully qualified class name of the remote home interface for this EJB. A session EJB must have either a remote or local home interface, but doesn't require both. If an EJB has a remote home interface, it must have a remote client interface as well. --> <home>my.home.interface</home> <!-- The remote client interface for this EJB. A session EJB must have either a remote or local client interface, but doesn't require both. If an EJB has a remote home interface, it must have a remote client interface as well. --> <remote>my.remote.interface</remote> <!-- This specifies the fully qualified class name of the local home interface for this EJB. A session EJB must have either a remote and/or local home interface, but doesn't require both. If an EJB has a local home interface, it must have a local client interface as well. --> <local-home>my.local.home.interface</local-home> <!-- This declares the fully qualified class name for the local client interface for this EJB. A session EJB must have either a remote or local client interface, but doesn't require both. If an EJB has a local home interface, it must have a local client interface as well. --> <local>my.local.interface</local> <!-- If you want to expose a SOAP service interface to your session bean, you must indicate here the JAX-RPC service interface your service will implement. Only stateless session beans can be published as web services. You'll also need to include a webservices.xml deployment descriptor with your EJB archive, to fully describe the web service (see section "Web Services - (webservices.xml)"). --> <service-endpoint>my.jaxrpc.service.interface</service-endpoint> <!-- The fully qualified name of the implementation class for the EJB. --> <ejb-class>my.impl.class</ejb-class> <!-- The type of the session bean. Allowed values are "Stateful" or "Stateless". The EJB container uses the session-type to determine what type of lifecycle management to apply to the bean. It also allows the server's deployment tools to validate the EJB (e.g., check its interfaces for required callbacks). --> <session-type>Stateless</session-type> <!-- The type of transaction management used by this EJB. The allowed values are "Bean" and "Container". The EJB container uses this value to determine what transaction management rules to apply to the EJB at runtime. --> <transaction-type>Container</transaction-type> <!-- Descriptions of the env-entry, ejb-ref, ejb-local-ref, resource-ref, and resource-env-ref elements can be found in Examples A-6 and A-7. --> <env-entry> <description>This env entry ...</description> <env-entry-name>env-var</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>var-value</env-entry-value> </env-entry> <ejb-ref> <description>A remote EJB I use...</description> <ejb-ref-name>ejb/remoteEJB</ejb-ref-name> <ejb-ref-type>Entity</ejb-ref-type> <home>other.ejb.home.interface</home> <remote>other.ejb.client.interface</remote> <ejb-link>other-ejb-name</ejb-link> </ejb-ref> <ejb-local-ref> <description>A local EJB I use...</description> <ejb-ref-name>ejb/localEJB</ejb-ref-name> <ejb-ref-type>Entity</ejb-ref-type> <local-home>other.ejb.localhome.interface</local-home> <local>other.ejb.localclient.interface</local> <ejb-link>other-ejb-name2</ejb-link> </ejb-local-ref> <resource-ref> <description>A resource factory I use...</description> <res-ref-name>jdbc/MyDB</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> <res-sharing-scope>Shareable</res-sharing-scope> </resource-ref> <resource-env-ref> <description>A resource I use...</description> <resource-env-ref-name>jms/MyQueue</resource-env-ref-name> <resource-env-ref-type>javax.jms.Queue </resource-env-ref-type> </resource-env-ref> <!-- A security-role-ref element declares a security role name that is used in this EJB component. Its use here is similar to its use in web components (see Example A-3). In EJBs, the role named here is used in a call to isCallerInRole( ) on the EJBContext. There must be a corresponding security-role element in the assembly-descriptor section of the descriptor, matching either the role-link value (if present) or the role-name (if no role-link is present). --> <security-role-ref> <!-- A text description of the role. --> <description>My admin role...</description> <!-- The role name as used in the EJB code. --> <role-name>admin</role-name> <!-- The role name referenced in the code can be linked to another security-role element (see the assembly-descriptor in Example A-13). If a role-link is not present, then the name used in the role-name must be declared as a security-role in the assembly-descriptor. --> <role-link>main-admin-role</role-link> <!-- --> </security-role-ref> <!-- The security-identity element is used to specify what identity is used to execute the methods of the EJB. If the use-caller-identity child element is used, then the identity of the caller is used to execute the EJB methods, and this identity is passed on to any EJB or other resources the EJB methods may invoke. If the run-as element is used, then the specified role name is used to execute the methods. --> <security-identity> <run-as> <role-name>admin</role-name> </run-as> </security-identity> </session> . . . </enterprise-beans> . . . </ejb-jar>

A.2.2. Message-Driven EJB Declarations

Figure A-10 shows the elements used to declare message-driven beans.

Example A-10 shows sample message-driven EJB declarations, annotated with descriptive comments.

Example A-10. Annotated message-driven EJB declarations

<ejb-jar . . .> . . . <enterprise-beans> . . . <!-- A message-driven element declares a message-driven EJB contained in this archive. --> <message-driven> <description>desc</description> <display-name>name</display-name> <icon> <small-icon>my/icon/file</small-icon> <large-icon>my/icon/file</large-icon> </icon> <!-- For descriptions of the following elements, see the session element in Example A-9. --> <ejb-name>MyMessageEJB</ejb-name> <ejb-class>my.impl.class</ejb-class> <messaging-type>javax.jms.MessageListener</messaging-type> <transaction-type>Container</transaction-type> <!-- The activation-config specifies parameters to be used when initializing the message destination associated with this message-driven bean. The standard properties that can be set for JMS-based EJBs are acknowledgeMode, messageSelector, destinationType, and subscriptionDurability. Specific application servers may support other property values in their messaging implementations (especially non-JMS ones), but you can't expect these to be honored by other app servers. --> <activation-config> <!-- The messageSelector property specifies a message selector to be used to filter messages received by the bean. The value must be a valid JMS message selector expression -- see Appendix E for the syntax of message selectors. --> <activation-config-property> <activation-config-property-name >messageSelector</activation-config-property-name> <activation-config-property-value> X = 'a' AND Y = 'b' </activation-config-property-value> </activation-config-property> <!-- The acknowledgeMode property declares how the bean acknowledges receipt of messages, if the EJB uses bean-managed transaction management (specified in the transaction-type element). The allowed values are "Auto-acknowledge" or "Dups-ok-acknowledge", corresponding to the JMS acknowledge types. If this element is not present, then "Auto-acknowledge" is assumed. --> <activation-config-property> <activation-config-property-name> acknowledgeMode</activation-config-property-name> <activation-config-property-value> Auto-acknowledge</activation-config-property-value> </activation-config-property> <!-- The destinationType property is a hint to the EJB container as to what kind of JMS destination this bean should be associated with. The value should be full class name of the JMS destination type. --> <activation-config-property> <activation-config-property-name> destinationType</activation-config-property-name> <activation-config-property-value> javax.jms.Queue</activation-config-property-value> </activation-config-property> <!-- If a topic destination is specified, this element indicates whether a durable subscription should be used for this EJB or not. Allowed values are "Durable" or "NonDurable". If no value is provided, then the durability of the subscription is at the discretion of the EJB container. --> <activation-config-property> <activation-config-property-name>subscriptionDurability </activation-config-property-name> <activation-config-property-value> Durable</activation-config-property-value> </activation-config-property> </activation-config> <!-- For full descriptions of the env-entry, ejb-ref, ejb-local-ref, resource-ref, and resource-env-ref elements, see Examples A-6 and A-7. --> <env-entry> <description>entry desc</description> <env-entry-name>name</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>value</env-entry-value> </env-entry> <ejb-ref> <description>desc</description> <ejb-ref-name>ejb/name</ejb-ref-name> <ejb-ref-type>Entity</ejb-ref-type> <home>homeClassName</home> <remote>remoteClass</remote> <ejb-link>ejbName</ejb-link> </ejb-ref> <ejb-local-ref> <description>desc</description> <ejb-ref-name>ejb/name</ejb-ref-name> <ejb-ref-type>Entity</ejb-ref-type> <local-home>homeClassName</local-home> <local>remoteClass</local> <ejb-link>ejbName</ejb-link> </ejb-local-ref> <resource-ref> <description>desc</description> <res-ref-name>jdbc/name</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> <res-sharing-scope>Shareable</res-sharing-scope> </resource-ref> <resource-env-ref> <description>desc</description> <resource-env-ref-name>context/name</resource-env-ref-name> <resource-env-ref-type> javax.jms.Queue</resource-env-ref-type> </resource-env-ref> <!-- For a full description of the security-identity element, see Example A-9. --> <security-identity> <run-as> <role-name>admin</role-name> </run-as> </security-identity> </message-driven> . . . </enterprise-beans> . . . </ejb-jar>

A.2.3. Entity EJB Declarations

Figure A-11 shows the descriptor elements used to declare entity EJBs.

Example A-11 shows sample entity EJB declarations, annotated with descriptive comments.

Example A-11. Annotated entity EJB declarations

<ejb-jar . . .> . . . <enterprise-beans> . . . <!-- Each entity element declares an entity EJB contained in the archive. In addition to the basic EJB details (home, client, implementation classes, etc.), the elements here describe how persistence should be managed for the entity bean, and for CMP, details on the abstract schema elements to be used for this EJB. --> <entity> <description>My entity EJB</description> <display-name>my-entity-ejb</display-name> <!-- Icon for tools. --> <icon> <small-icon>my/icon/file</small-icon> <large-icon>my/icon/file</large-icon> </icon> <!-- For descriptions of the following elements, see the session element in Example A-9. --> <ejb-name>MyEntityEJB</ejb-name> <home>my.home.interface</home> <remote>my.remote.interface</remote> <local-home>my.local.home.interface</local-home> <local>my.local.interface</local> <ejb-class>my.impl.class</ejb-class> <!-- Indicate how the persistence for the entity EJB is managed. Allowed options are "Bean" or "Container". In you use bean-managed persistence, then you must provide the necessary persistence logic code in your EJB class. If you use container-managed persistence, there are additional deployment elements that must be defined below. --> <persistence-type>Container</persistence-type> <!-- The fully qualified class name of the type used for this EJB's primary key. --> <prim-key-class>classname</prim-key-class> <!-- Indicates whether the EJB's methods are reentrant or not. --> <reentrant>false</reentrant> <!-- Indicates the version of container-managed persistence to be used for this EJB. Allowed values are "1.x", indicating CMP as defined in the EJB 1.1 specification, or "2.x", indicating CMP as defined in EJB 2.0/2.1. If this element isn't present, an EJB 2.x container will assume the value is 2.x. This element should be used only with EJBs that specify container-managed persistence in the persistence-type above. --> <cmp-version>2.x</cmp-version> <!-- If CMP is used, this element specifies the abstract "table" name for the EJB, to be used in EJB-QL queries. --> <abstract-schema-name>MyEntity</abstract-schema-name> <!-- If CMP is used, these elements declare the container- managed fields present on the EJB. --> <cmp-field> <!-- A description of the field. --> <description>A persisted field...</description> <!-- The name of the CMP field. In EJB 2.x CMP, the field name is an abstract "column" name, used in EJB-QL queries. It also implies the presence of JavaBean-style get/set accessors for this field on the EJB implementation class. --> <field-name>myPersistentField</field-name> </cmp-field> <!-- If CMP is used and if the EJB has a single-field primary key, this element is used to specify which cmp-field is the EJB's primary key. If the EJB has multiple fields in its primary key, then a primary key class must be used, and the primary key class (declared in the prim-key-class element above) must have public data members that map to cmp-fields on this EJB. --> <primkey-field>primkey-fieldname</primkey-field> <!-- For descriptions of the env-entry, ejb-ref, ejb-local-ref, resource-ref, and resource-local-ref elements, see Examples A-6 and A-7.--> <env-entry> <description>This env entry ...</description> <env-entry-name>env-var</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>var-value</env-entry-value> </env-entry> <ejb-ref> <description>A remote EJB I use...</description> <ejb-ref-name>ejb/remoteEJB</ejb-ref-name> <ejb-ref-type>Entity</ejb-ref-type> <home>other.ejb.home.interface</home> <remote>other.ejb.client.interface</remote> <ejb-link>other-ejb-name</ejb-link> </ejb-ref> <ejb-local-ref> <description>A local EJB I use...</description> <ejb-ref-name>ejb/localEJB</ejb-ref-name> <ejb-ref-type>Entity</ejb-ref-type> <local-home>other.ejb.localhome.interface</local-home> <local>other.ejb.localclient.interface</local> <ejb-link>other-ejb-name2</ejb-link> </ejb-local-ref> <resource-ref> <description>A resource factory I use...</description> <res-ref-name>jdbc/MyDB</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> <res-sharing-scope>Shareable</res-sharing-scope> </resource-ref> <resource-env-ref> <description>A resource I use...</description> <resource-env-ref-name>jms/MyQueue</resource-env-ref-name> <resource-env-ref-type>javax.jms.Queue </resource-env-ref-type> </resource-env-ref> <!-- For descriptions of the security-role-ref and security-identity elements, see Example A-3. --> <security-role-ref> <description>My admin role</description> <role-name>admin</role-name> <role-link>main-admin-role</role-link> </security-role-ref> <security-identity> <use-caller-identity/> </security-identity> <!-- If CMP is used, query elements are used to define the logic behind finder and select methods, using EJB-QL. --> <query> <!-- A description of the query. --> <description>This is a finder query...</description> <!-- A declaration of the finder or select method that this query is bound to. --> <query-method> <!-- The name of the select or finder method. --> <method-name>findByMyPersistentField</method-name> <!-- A list of the method arguments, used to distinguish overloaded finder or select methods. The method-param elements must be listed here in order of the corresponding method signature. An empty method-params element can be used if the method has no arguments or if there is only a single version of the named method. --> <method-params> <!-- Each method-param element specifies the fully qualified Java type of a parameter in the method. --> <method-param>my.finder.arg.type</method-param> </method-params> </query-method> <!-- Used to specify whether EJBs returned as the result of this query method should be returned using their remote or local client interfaces. Allowed values are "Remote" or "Local". --> <result-type-mapping>Local</result-type-mapping> <!-- The ejb-ql element contains the EJB-QL query string that defines this finder or select method. See Appendix C for a full description of the EJB-QL syntax. --> <ejb-ql>SELECT e FROM my-ejb-table e WHERE e.my-persistent-field IS NOT NULL</ejb-ql> </query> </entity> <entity> <ejb-name>MySlaveEJB</ejb-name> <ejb-class>my.slave.ejb.class</ejb-class> <persistence-type>Container</persistence-type> <prim-key-class>my.slave.primkey.class</prim-key-class> <reentrant>false</reentrant> </entity> . . . </enterprise-beans> . . . </ejb-jar>

A.2.4. Entity EJB Relationship Declarations

Figure A-12 shows the elements used to declare relationships between entity EJBs.

Example A-12 shows sample entity relationship declarations, annotated with descriptive comments.

Example A-12. Annotated entity EJB relationship declarations

<ejb-jar . . .> . . . <!-- The relationships element defines persistence relationships between CMP entity EJBs and specifies how to manage the persistent relationships. --> <relationships> <!-- An overall description of the relationships. --> <description>desc</description> <!-- Each ejb-relation element declares a persistence relationship between two CMP entity EJBs declared in this archive. --> <ejb-relation> <!-- Description of the relation. --> <description>desc</description> <!-- A unique name for the relation. --> <ejb-relation-name>name</ejb-relation-name> <!-- The two roles involved in the relationship are defined with two relationship-role elements. Each element defines one end of the relation. --> <ejb-relationship-role> <!-- Description of the role. --> <description>The master role in the relation</description> <!-- The name of the role in the relationship. --> <ejb-relationship-role-name>master </ejb-relationship-role-name> <!-- The multiplicity of this end of the relationship. Allowed values are "One" or "Many". --> <multiplicity>One</multiplicity> <!-- If this element is present, it indicates that a deletion of the EJB on the other end of the relationship should invoke a cascading delete of the EJB(s) on this end of the relationship. --> <cascade-delete/> <!-- The name of the EJB (from its ejb-name element) to be used for this end of the relationship. --> <relationship-role-source> <!-- A description of the role source. --> <description>desc</description> <!-- The name of the EJB at this end of the relationship. The name must correspond to the ejb-name element of a CMP EJB declared in this ejb-jar. --> <ejb-name>MyEntityEJB</ejb-name> </relationship-role-source> <!-- A field name to be used to access this relationship from the source EJB. If this element is present, JavaBean-style get/set accessors will be assumed to exist on the EJB implementation class to access the EJBs at the other end of this relationship. If this element is not present, then the relationship cannot be accessed from this EJB. --> <cmr-field> <description>This field...</description> <cmr-field-name>slaves</cmr-field-name> </cmr-field> </ejb-relationship-role> <!-- The opposite role to that defined above. --> <ejb-relationship-role> <description>desc</description> <ejb-relationship-role-name>slave </ejb-relationship-role-name> <multiplicity>Many</multiplicity> <cascade-delete/> <relationship-role-source> <description>desc</description> <ejb-name>MySlaveEJB</ejb-name> </relationship-role-source> <cmr-field> <description>This field...</description> <cmr-field-name>master</cmr-field-name> </cmr-field> </ejb-relationship-role> </ejb-relation> </relationships> . . . </ejb-jar>

A.2.5. Cross-Component Runtime Settings

Figure A-13 shows the elements used to define cross-component runtime settings for EJB components.

Example A-13 shows sample cross-component runtime settings, annotated with descriptive comments.

Example A-13. Annotated cross-component runtime settings

<ejb-jar . . .> . . . <!-- This element contains various cross-component details about how the EJBs contained in the ejb-jar file should be managed at runtime. These details can be changed at deployment time by the application assembler. --> <assembly-descriptor> <!-- Each security-role element declares a security role used in EJBs in this ejb-jar module. Each named role must be mapped to a physical group/identity within the runtime security environment of the EJB/J2EE server. --> <security-role> <!-- Description of the role. --> <description>desc</description> <!-- The name of the role. This name must be mapped to a physical group/identity in the security environment in the EJB/J2EE server. --> <role-name>main-admin-role</role-name> </security-role> <!-- Each method-permission element declares the permissions to be used to control access to EJB methods. --> <method-permission> <!-- Description of the method permission. --> <description>desc</description> <!-- Each permission must include either a list of role-name elements, indicating the roles being given permissions to execute the methods in this method-permission, or it must include an empty "unchecked" element, indicating that the methods specified in the list are to be executed without checking the client's identity. If a list of role-name elements is given, each role-name must match a security-role defined above. --> <unchecked/> <!-- A list of one or more method elements, specifying the set of methods whose permissions are being set. Each method element specifies one or more methods on a specific EJB in this archive. Wildcards are used to indicate multiple methods. --> <method> <!-- Description of the method. --> <description>This method set...</description> <!-- The name of the EJB whose methods are being specified. The ejb-name element must match the ejb-name element of an EJB declared in this descriptor. --> <ejb-name>MySessionEJB</ejb-name> <!-- Limits the method definitions to a specific interface on the EJB. Allowed values of the method-intf element are "Home" for the remote home interface, "Remote" for the remote client interface, "LocalHome" for the local home interface, and "Local" for the local client interface. If this element is not present, the methods are chosen from all of these interfaces on the EJB. --> <method-intf>Local</method-intf> <!-- The name of the method(s). The allowed values are either a full method name, or an asterisk, "*", indicating that all of the EJB's methods (limited by the method-intf, if present) are being selected. --> <method-name>setName</method-name> <!-- A specification of the parameters in the method signature. This element can be used to chose a specific method when a method name has been overloaded in an EJB. --> <method-params> <!-- Each method-param element specifies the fully qualified Java type of a parameter in the method. --> <method-param>java.lang.String</method-param> </method-params> </method> </method-permission> <!-- Used to specify how transactions should be managed for a set of methods on an EJB. --> <container-transaction> <!-- Description of the element. --> <description>The transactions here...</description> <!-- A set of method(s) for which transaction management is being defined. The method element is described above as part of the method-permission element. --> <method> <description>This method...</description> <ejb-name>MyEntityEJB</ejb-name> <method-intf>Remote</method-intf> <method-name>getName</method-name> <method-params/> </method> <!-- The transaction support to be offered by the method(s) specified above. Allowed values are "NotSupported", "Supports", "Required", "RequiresNew", "Mandatory", and "Never". --> <trans-attribute>NotSupported</trans-attribute> </container-transaction> <!-- Declare message destinations (queues or topics) used by components in this module. Any destinations declared here will need to be configured in the target application server. --> <message-destination> <message-destination-name >MyMessageDestination</message-destination-name> </message-destination> <!-- An exclude-list can be used to specify methods on the EJBs in this archive that should not be called by any clients. --> <exclude-list> <!-- Description of exclude list. --> <description>These methods are excluded...</description> <!-- List of methods that should be considered uncallable. The method element is described fully in the method-permission element, above. --> <method> <description>Tis method is dangerous...</description> <ejb-name>MyEntityEJB</ejb-name> <method-name>doSomethingBad</method-name> <method-params> <method-param>java.lang.Object</method-param> </method-params> </method> </exclude-list> </assembly-descriptor> <!-- If this element is present, the J2EE server's deployment tools should generate a jar file with the given filename that contains all of the classes (including container-generated classes) required by a client in order to use the contained EJB components. These classes include remote and local stub implementations for the EJB's remote home and client interfaces, among other things. This jar file can then be included in other J2EE components or application clients if they reference the EJBs in this archive. --> <ejb-client-jar>myClientJar.jar</ejb-client-jar> </ejb-jar>