EJB Deployment Descriptor Reference

 

This topic describes the XML DTD for the EJB deployment descriptor, as defined in the Enterprise JavaBeans Specification 1.1 published by Sun Microsystems, Inc.

This topic includes the following sections:

• About Deployment Descriptors

• DOCTYPE Declaration

• Summary of Deployment Descriptor Elements

• Description of Deployment Descriptor Elements

In addition to the standard EJB deployment descriptor provided by Sun Microsystems, Inc., WebLogic Enterprise (WLE) provides the WebLogic Enterprise EJB Extensions, which are XML elements used to further customize EJBs for the WebLogic Enterprise environment. For more information, see WebLogic Enterprise EJB Extensions Reference. For more information about deploying EJBs in the WebLogic Enterprise environment, see "Developing WebLogic Enterprise EJB Applications" in Getting Started.

Note: Material in this topic was republished with permission from Sun Microsystems, Inc.

 

---

About Deployment Descriptors

A deployment descriptor is a file that defines the following kinds of information:

• EJB structural information, such as the EJB name, class, home and remote interfaces, bean type (session or entity), environment entries, resource factory references, EJB references, security role references, as well as additional information based on the bean type.

• Application assembly information, such as EJB references, security roles, security role references, method permissions, and container transaction attributes. Specifying assembly descriptor information is an optional task that an Application Assembler performs.

For a complete discussion of the EJB deployment descriptor, see Chapter 16, "Deployment Descriptor," in the Enterprise JavaBeans Specification 1.1.

EJB Roles and Deployment Descriptors

Specifying deployment descriptor information is a required task that a Bean Provider performs. The Bean Provider creates a standard EJB deployment descriptor file using the XML markup conventions in accordance with the syntax described in the Enterprise JavaBeans Specification 1.1. Multiple EJBs can be defined in a single deployment descriptor. For more information about creating deployment descriptors, see the following documents:

• "Developing WebLogic Enterprise EJB Applications" in Getting Started

• Using the WebLogic EJB Deployer

An Application Assembler or Deployer may subsequently modify only certain information (such as the EJB name, values of environment entries, and description entries) in the deployment descriptor. The Deployer may use the WebLogic EJB Deployer to update certain settings in the deployment descriptor.

Thereafter, the Application Assembler creates a deployable EJB JAR file using the ejbc command-line tool, specifying the -i parameter and passing this filename (ejb-jar.xml). For more information about the ejbc command-line tool, see the Commands, Systems Processes, and MIB Reference.

File Formats

Deployment descriptors are stored in the EJB JAR file. The WebLogic EJB Deployer accepts standard, extended, and deployable EJB JAR files.

 

---

DOCTYPE Declaration

All valid EJB JAR deployment descriptors must contain the following DOCTYPE declaration:

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

 

---

Summary of Deployment Descriptor Elements

Table 1-1 describes the standard deployment descriptor elements.

Table 1-1 List of Standard Deployment Descriptor Elements

Element	Description	EJB Role
assembly-descriptor	Contains application-assembly information.	Application Assembler
cmp-field	Describes a container-managed field.	Bean Provider
container-transaction	Specifies how the container must manage transaction scopes for the EJB's method invocations.	Application Assembler
description	Provides text describing the parent element.	Bean Provider or Application Assembler
display-name	Specifies a short name that is intended to be displayed by tools.	Bean Provider
ejb-class	Specifies the fully qualified name of the EJB's class.	Bean Provider
ejb-jar	Root element of the EJB deployment descriptor.	All
ejb-link	Used in the ejb-ref element to specify that an EJB reference is linked to another EJB in the EJB JAR file.	Application Assembler
ejb-name	Specifies an EJB's name.	Bean Provider or Application Assembler
ejb-ref	Declares a reference to another EJB's home.	Bean Provider
ejb-ref-name	Specifies the name of an EJB reference, which is an entry in the EJB's environment.	Bean Provider
ejb-ref-type	Specifies the expected type (entity or session) of the referenced EJB.	Bean Provider
enterprise-beans	Declares one or more EJBs.	Bean Provider
entity	Declares an entity bean.	Bean Provider
env-entry	Declares an EJB's environment entries.	Bean Provider or Application Assembler
env-entry-name	Specifies the name of an EJB's environment entry.	Bean Provider or Application Assembler
env-entry-type	Specifies the fully qualified Java type of the environment entry value that is expected by the EJB's code.	Bean Provider or Application Assembler
env-entry-value	Specifies the value of an EJB's environment entry.	Bean Provider or Application Assembler
field-name	Specifies the name of a container-managed field.	Bean Provider
home	Specifies the fully qualified name of the EJB's home interface.	Bean Provider
large-icon	Specifies the name of a file containing a large (32 x 32) icon image. The filename is a relative path within the EJB JAR file.	Bean Provider
method	Denotes a method of an EJB's home or remote interface, or a set of methods.	Application Assembler
method-intf	Allows a method element to differentiate between the methods, with the same name and signature, that are defined in both the remote and home interfaces.	Application Assembler
method-name	Specifies the name of an EJB method, or the asterisk (*) character, which is used when the element denotes all the methods of an EJB's remote and home interfaces.	Application Assembler
method-param	Specifies the fully qualified Java type name of a method parameter.	Application Assembler
method-params	Contains a list of the fully qualified Java type names of the method parameters.	Application Assembler
method-permission	Specifies one or more security roles that are allowed to invoke one or more EJB methods.	Application Assembler
persistence-type	Specifies an entity bean's persistence management type (bean- or container-managed).	Bean Provider
prim-key-class	Specifies the fully qualified name of an entity bean's primary key class.	Bean Provider
primkey-field	Specifies the name of the primary key field for an entity with container-managed persistence.	Bean Provider
reentrant	Specifies whether an entity bean is reentrant (True) or not (False).	Bean Provider
remote	Specifies the fully qualified name of the EJB's remote interface.	Bean Provider
res-auth	Specifies whether the EJB code signs on programmatically to the resource manager, or whether the Container will sign on to the resource manager on behalf of the EJB. In the latter case, the Container uses information that is supplied by the Deployer.	Bean Provider
res-ref-name	Specifies the name of a resource factory reference.	Bean Provider
res-type	Specifies the type of the data source, which is the Java interface (or class) expected to be implemented by the data source.	Bean Provider
resource-ref	Declares the EJB's reference to an external resource.	Bean Provider
role-link	Links a security role reference to a defined security role.	Application Assembler
role-name	Specifies the name of a security role.	Application Assembler
security-role	Defines a security role.	Application Assembler
security-role-ref	Declares a security role reference in the EJB's code.	Bean Provider
session-type	Specifies the type of a session bean (stateful or stateless).	Bean Provider
session	Declares a session bean.	Bean Provider
small-icon	Specifies the name of a file containing a small (16 x 16) icon image. The filename is relative path within the EJB JAR file.	Bean Provider
transaction-type	Specifies the transaction management type of an EJB (bean- or container-managed).	Bean Provider
trans-attribute	Specifies how the container must manage the transaction boundaries when delegating a method invocation to an EJB's business method.	Application Assembler

 

---

Description of Deployment Descriptor Elements

assembly-descriptor

Synopsis

Contains application-assembly information.

Syntax

<!ELEMENT assembly-descriptor (security-role*, method-permission*, container-transaction*)>

EJB Role

Application Assembler

Used In

ejb-jar

cmp-field

Synopsis

Describes a container-managed field.

Syntax

<!ELEMENT cmp-field (description?, field-name)>

EJB Role

Bean Provider

Used In

entity

container-transaction

Synopsis

Specifies how the container must manage transaction scopes for the EJB's method invocations.

Syntax

<!ELEMENT container-transaction (description?, method+, trans-attribute)>

EJB Role

Application Assembler

Used In

assembly-descriptor

description

Synopsis

Provides text describing the parent element.

Syntax

<!ELEMENT description (#PCDATA)>

EJB Role

Bean Provider or Application Assembler

Used In

• cmp-field

• container-transaction

• ejb-jar

• entity

• env-entry

• ejb-ref

• method

• method-permission

• resource-ref

• security-role

• security-role-ref

• session

display-name

Synopsis

Specifies a short name that is intended to be displayed by tools.

Syntax

<!ELEMENT display-name (#PCDATA)>

EJB Role

Bean Provider

Used In

• ejb-jar

• session

• entity

ejb-class

Synopsis

Specifies the fully qualified name of the EJB's class.

Syntax

<!ELEMENT ejb-class (#PCDATA)>

EJB Role

Bean Provider

Used In

• entity

• session

ejb-jar

Synopsis

Root element of the EJB deployment descriptor.

Syntax

<!ELEMENT ejb-jar (description?, display-name?, small-icon?, large-icon?, enterprise-beans, assembly-descriptor?)>

EJB Role

All

ejb-link

Synopsis

Used in the ejb-ref element to specify that an EJB reference is linked to another EJB in the EJB JAR file.

Syntax

<!ELEMENT ejb-link (#PCDATA)>

Valid Values

The value of the ejb-link element must be the ejb-name of an EJB in the same EJB JAR file, or in another EJB JAR file in the same J2EE application unit.

EJB Role

Application Assembler

Used In

ejb-ref

ejb-name

Synopsis

Specifies an EJB's name.

Syntax

<!ELEMENT ejb-name (#PCDATA)>

Valid Values

• The name must be unique among the names of the EJBs in the same EJB JAR file.

• The name must conform to the lexical rules for an NMTOKEN.

EJB Role

Bean Provider or Application Assembler

Used In

• entity

• method

• session

ejb-ref

Synopsis

Declares a reference to another EJB's home.

Syntax

<!ELEMENT ejb-ref (description?, ejb-ref-name, ejb-ref-type, home, remote, ejb-link?)>

EJB Role

Bean Provider

Used In

• entity

• session

ejb-ref-name

Synopsis

Specifies the name of an EJB reference, which is an entry in the EJB's environment.

Syntax

<!ELEMENT ejb-ref-name (#PCDATA)>

Valid Values

It is recommended that name is prefixed with ejb/.

EJB Role

Bean Provider

Used In

ejb-ref

ejb-ref-type

Synopsis

Specifies the expected type (entity or session) of the referenced EJB.

Syntax

<!ELEMENT ejb-ref-type (#PCDATA)>

Valid Values

One of the following values:

• Entity

• Session

EJB Role

Bean Provider

Used In

ejb-ref

enterprise-beans

Synopsis

Declares one or more EJBs.

Syntax

<!ELEMENT enterprise-beans (session | entity)+>

EJB Role

Bean Provider

entity

Synopsis

Declares an entity bean.

Syntax

<!ELEMENT entity (description?, display-name?, small-icon?, large-icon?, ejb-name, home, remote, ejb-class, persistence-type, prim-key-class, reentrant, cmp-field*, primkey-field?, env-entry*, ejb-ref*, security-role-ref*, resource-ref*)>

Valid Values

• The optional primkey-field may be present in the descriptor if the entity's persistence-type is Container.

• At least one cmp-field element must be present in the descriptor if the entity's persistency-type is Container, and none must not be present if the entity's persistence-type is Bean.

EJB Role

Bean Provider

Used In

enterprise-beans

env-entry

Synopsis

Declares an EJB's environment entries.

Syntax

<!ELEMENT env-entry (description?, env-entry-name, env-entry-type, env-entry-value?)>

EJB Role

Bean Provider or Application Assembler

Used In

• entity

• session

env-entry-name

Specifies the name of an EJB's environment entry.

Syntax

<!ELEMENT env-entry-name (#PCDATA)>

EJB Role

Bean Provider or Application Assembler

Used In

env-entry

env-entry-type

Synopsis

Specifies the fully qualified Java type of the environment entry value that is expected by the EJB's code.

Syntax

<!ELEMENT env-entry-type (#PCDATA)>

Valid Values

One of the following values:

• java.lang.Boolean

• java.lang.String

• java.lang.Integer

• java.lang.Double

• java.lang.Byte

• java.lang.Short

• java.lang.Long

• java.lang.Float

EJB Role

Bean Provider or Application Assembler

Used In

env-entry

env-entry-value

Synopsis

Specifies the value of an EJB's environment entry.

Syntax

<!ELEMENT env-entry-value (#PCDATA)>

EJB Role

Bean Provider or Application Assembler

Used In

env-entry

field-name

Synopsis

Specifies the name of a container-managed field.

Syntax

<!ELEMENT field-name (#PCDATA)>

Valid Values

The name must be a public field of the EJB class or one of its superclasses.

EJB Role

Bean Provider

Used In

cmp-field

home

Synopsis

Specifies the fully qualified name of the EJB's home interface.

Syntax

<!ELEMENT home (#PCDATA)>

EJB Role

Bean Provider

Used In

• ejb-ref

• entity

• session

large-icon

Synopsis

Specifies the name of a file containing a large (32 x 32) icon image. The filename is a relative path within the EJB JAR file.

Syntax

<!ELEMENT large-icon (#PCDATA)>

Valid Values

• The image must be either in the JPEG or GIF format.

• The filename must end with the suffix.jpg or .gif, respectively.

EJB Role

Bean Provider

method

Synopsis

Denotes a method of an EJB's home or remote interface, or a set of methods.

Syntax

<!ELEMENT method (description?, ejb-name, method-intf?, method-name, method-params?)>

Valid Values

The ejb-name element must be the name of one of the EJBs declared in the deployment descriptor.

EJB Role

Application Assembler

Used In

• method-permission

• container-transaction

method-intf

Synopsis

Allows a method element to differentiate between the methods, with the same name and signature, that are defined in both the remote and home interfaces.

Syntax

<!ELEMENT method-intf (#PCDATA)>

Valid Values

One of the following values:

• Home

• Remote

EJB Role

Application Assembler

Used In

method

method-name

Synopsis

Specifies the name of an EJB method, or the asterisk (*) character, which is used when the element denotes all the methods of an EJB's remote and home interfaces.

Syntax

<!ELEMENT method-name (#PCDATA)>

EJB Role

Application Assembler

Used In

method

method-param

Synopsis

Specifies the fully qualified Java type name of a method parameter.

Syntax

<!ELEMENT method-param (#PCDATA)>

EJB Role

Application Assembler

Used In

method-params

method-params

Synopsis

Contains a list of the fully qualified Java type names of the method parameters.

Syntax

<!ELEMENT method-params (method-param*)>

EJB Role

Application Assembler

Used In

method

method-permission

Synopsis

Specifies one or more security roles that are allowed to invoke one or more EJB methods.

Syntax

<!ELEMENT method-permission (description?, role-name+, method+)>

Valid Values

• The security roles used in the method-permission element must be defined in the security-role element of the deployment descriptor.

• The methods must be methods defined in the EJB's remote and/or home interfaces.

EJB Role

Application Assembler

Used In

assembly-descriptor

persistence-type

Synopsis

Specifies an entity bean's persistence management type (bean- or container-managed).

Syntax

<!ELEMENT persistence-type (#PCDATA)>

Valid Values

One of the following values:

• Bean

• Container

EJB Role

Bean Provider

Used In

entity

prim-key-class

Synopsis

Specifies the fully qualified name of an entity bean's primary key class.

Syntax

<!ELEMENT prim-key-class (#PCDATA)>

Valid Values

If the definition of the primary key class is deferred to deployment time, the prim-key-class element should specify java.lang.Object.

EJB Role

Bean Provider

Used In

entity

primkey-field

Synopsis

Specifies the name of the primary key field for an entity with container-managed persistence.

Syntax

<!ELEMENT primkey-field (#PCDATA)>

Valid Values

• The primkey-field must be one of the fields declared in the cmp-field element.

• The type of the field must be the same as the primary key type.

EJB Role

Bean Provider

Used In

entity

reentrant

Synopsis

Specifies whether an entity bean is reentrant (True) or not (False).

Syntax

<!ELEMENT reentrant (#PCDATA)>

Valid Values

One of the following values:

• True

• False

EJB Role

Bean Provider

Used In

entity

remote

Synopsis

Specifies the fully qualified name of the EJB's remote interface.

Syntax

<!ELEMENT remote (#PCDATA)>

EJB Role

Bean Provider

Used In

• ejb-ref

• entity

• session

res-auth

Synopsis

Specifies whether the EJB code signs on programmatically to the resource manager, or whether the Container will sign on to the resource manager on behalf of the EJB. In the latter case, the Container uses information that is supplied by the Deployer.

Syntax

<!ELEMENT res-auth (#PCDATA)>

Valid Values

One of the following values:

• Application

• Container

EJB Role

Bean Provider

res-ref-name

Synopsis

Specifies the name of a resource manager connection factory reference.

Syntax

<!ELEMENT res-ref-name (#PCDATA)>

EJB Role

Bean Provider

Used In

resource-ref

res-type

Synopsis

Specifies the type of the data source, which is the Java interface (or class) expected to be implemented by the data source.

Syntax

<!ELEMENT res-type (#PCDATA)>

EJB Role

Bean Provider

Used In

resource-ref

resource-ref

Synopsis

Declares the EJB's reference to an external resource.

Syntax

<!ELEMENT resource-ref (description?, res-ref-name, res-type, res-auth)>

EJB Role

Bean Provider

Used In

• entity

• session

role-link

Synopsis

Links a security role reference to a defined security role.

Syntax

<!ELEMENT role-link (#PCDATA)>

Valid Values

The role-link element must contain the name of one of the security roles defined in the security-role elements.

EJB Role

Application Assembler

Used In

security-role-ref

role-name

Synopsis

Specifies the name of a security role.

Syntax

<!ELEMENT role-name (#PCDATA)>

Valid Values

The name must conform to the lexical rules for an NMTOKEN.

EJB Role

Application Assembler

Used In

• method-permission

• security-role

• security-role-ref

security-role

Synopsis

Defines a security role.

Syntax

<!ELEMENT security-role (description?, role-name)>

EJB Role

Application Assembler

Used In

assembly-descriptor

security-role-ref

Synopsis

Declares a security role reference in the EJB's code.

Syntax

<!ELEMENT security-role-ref (description?, role-name, role-link?)>

Valid Values

• The value of the role-name element must be the string used as the parameter to the EJBContext.isCallerInRole(String roleName) method.

• The value of the role-link element must be the name of one of the security roles defined in the security-role elements.

EJB Role

Bean Provider

Used In

• entity

• session

session-type

Synopsis

Specifies the type of a session bean (stateful or stateless).

Syntax

<!ELEMENT session-type (#PCDATA)>

Valid Values

One of the following values:

• Stateful

• Stateless

EJB Role

Bean Provider

session

Synopsis

Declares a session bean.

Syntax

<!ELEMENT session (description?, display-name?, small-icon?, large-icon?, ejb-name, home, remote, ejb-class, session-type, transaction-type, env-entry*, ejb-ref*, security-role-ref*, resource-ref*)>

EJB Role

Bean Provider

Used In

enterprise-beans

small-icon

Synopsis

Specifies the name of a file containing a small (16 x 16) icon image. The filename is relative path within the EJB JAR file.

Syntax

<!ELEMENT small-icon (#PCDATA)>

Valid Values

• The image must be either in the JPEG or GIF format.

• The filename must end with the suffix .jpg or .gif, respectively.

EJB Role

Bean Provider

transaction-type

Synopsis

Specifies the transaction management type of an EJB (bean- or container-managed).

Syntax

<!ELEMENT transaction-type (#PCDATA)>

Valid Values

One of the following values:

• Bean

• Container

EJB Role

Bean Provider

Used In

session

trans-attribute

Synopsis

Specifies how the container must manage the transaction boundaries when delegating a method invocation to an EJB's business method.

Syntax

<!ELEMENT trans-attribute (#PCDATA)>

Valid Values

One of the following values:

• NotSupported

• Supports

• Required

• RequiresNew

• Mandatory

• Never

EJB Role

Application Assembler

Used In

container-transaction

ID

Synopsis

The ID mechanism allows tools that produce additional deployment information (such as information beyond the standard EJB deployment descriptor information) to store the nonstandard information in a separate file, and easily refer from these tools-specific files to the information in the standard deployment descriptor.

The EJB architecture does not allow the tools to add the nonstandard information into the EJB deployment descriptor.

Syntax

<!ATTLIST assembly-descriptor id ID #IMPLIED>

<!ATTLIST cmp-field id ID #IMPLIED>

<!ATTLIST container-transaction id ID #IMPLIED>

<!ATTLIST description id ID #IMPLIED>

<!ATTLIST display-name id ID #IMPLIED>

<!ATTLIST ejb-class id ID #IMPLIED>

<!ATTLIST ejb-jar id ID #IMPLIED>

<!ATTLIST ejb-link id ID #IMPLIED>

<!ATTLIST ejb-name id ID #IMPLIED>

<!ATTLIST ejb-ref id ID #IMPLIED>

<!ATTLIST ejb-ref-name id ID #IMPLIED>

<!ATTLIST ejb-ref-type id ID #IMPLIED>

<!ATTLIST enterprise-beans id ID #IMPLIED>

<!ATTLIST entity id ID #IMPLIED>

<!ATTLIST env-entry id ID #IMPLIED>

<!ATTLIST env-entry-name id ID #IMPLIED>

<!ATTLIST env-entry-type id ID #IMPLIED>

<!ATTLIST env-entry-value id ID #IMPLIED>

<!ATTLIST field-name id ID #IMPLIED>

<!ATTLIST home id ID #IMPLIED>

<!ATTLIST large-icon id ID #IMPLIED>

<!ATTLIST method id ID #IMPLIED>

<!ATTLIST method-intf id ID #IMPLIED>

<!ATTLIST method-name id ID #IMPLIED>

<!ATTLIST method-param id ID #IMPLIED>

<!ATTLIST method-params id ID #IMPLIED>

<!ATTLIST method-permission id ID #IMPLIED>

<!ATTLIST persistence-type id ID #IMPLIED>

<!ATTLIST prim-key-class id ID #IMPLIED>

<!ATTLIST primkey-field id ID #IMPLIED>

<!ATTLIST reentrant id ID #IMPLIED>

<!ATTLIST remote id ID #IMPLIED>

<!ATTLIST res-auth id ID #IMPLIED>

<!ATTLIST res-ref-name id ID #IMPLIED>

<!ATTLIST res-type id ID #IMPLIED>

<!ATTLIST resource-ref id ID #IMPLIED>

<!ATTLIST role-link id ID #IMPLIED>

<!ATTLIST role-name id ID #IMPLIED>

<!ATTLIST security-role id ID #IMPLIED>

<!ATTLIST security-role-ref id ID #IMPLIED>

<!ATTLIST session-type id ID #IMPLIED>

<!ATTLIST session id ID #IMPLIED>

<!ATTLIST small-icon id ID #IMPLIED>

<!ATTLIST transaction-type id ID #IMPLIED>

<!ATTLIST trans-attribute id ID #IMPLIED>