Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
WebLogic Enterprise Doc Home   |   Enterprise JavaBeans Topics   |   Previous Topic   |   Next Topic   |   Contents   |   Index

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.

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.

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.

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

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">

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

Contains application-assembly information.

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

Application Assembler

ejb-jar

Describes a container-managed field.

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

Bean Provider

entity

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

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

Application Assembler

assembly-descriptor

Provides text describing the parent element.

<!ELEMENT description (#PCDATA)>

Bean Provider or Application Assembler

• cmp-field

• container-transaction

• ejb-jar

• entity

• env-entry

• ejb-ref

• method

• method-permission

• resource-ref

• security-role

• security-role-ref

• session

display-name

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

<!ELEMENT display-name (#PCDATA)>

Bean Provider

• ejb-jar

• session

• entity

ejb-class

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

<!ELEMENT ejb-class (#PCDATA)>

Bean Provider

• entity

• session

ejb-jar

Root element of the EJB deployment descriptor.

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

All

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

<!ELEMENT ejb-link (#PCDATA)>

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.

Application Assembler

ejb-ref

Specifies an EJB's name.

<!ELEMENT ejb-name (#PCDATA)>

• 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

• entity

• method

• session

ejb-ref

Declares a reference to another EJB's home.

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

Bean Provider

• entity

• session

ejb-ref-name

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

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

It is recommended that name is prefixed with ejb/.

Bean Provider

ejb-ref

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

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

One of the following values:

• Entity

• Session

EJB Role

Bean Provider

ejb-ref

Declares one or more EJBs.

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

Bean Provider

Declares an entity bean.

<!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*)>

• 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

enterprise-beans

Declares an EJB's environment entries.

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

Bean Provider or Application Assembler

• entity

• session

env-entry-name

Specifies the name of an EJB's environment entry.

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

Bean Provider or Application Assembler

env-entry

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

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

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

env-entry

Specifies the value of an EJB's environment entry.

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

Bean Provider or Application Assembler

env-entry

Specifies the name of a container-managed field.

<!ELEMENT field-name (#PCDATA)>

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

Bean Provider

cmp-field

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

<!ELEMENT home (#PCDATA)>

Bean Provider

• ejb-ref

• entity

• session

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.

<!ELEMENT large-icon (#PCDATA)>

• 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

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

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

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

Application Assembler

• method-permission

• container-transaction

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.

<!ELEMENT method-intf (#PCDATA)>

One of the following values:

• Home

• Remote

EJB Role

Application Assembler

method

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.

<!ELEMENT method-name (#PCDATA)>

Application Assembler

method

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

<!ELEMENT method-param (#PCDATA)>

Application Assembler

method-params

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

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

Application Assembler

method

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

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

• 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

assembly-descriptor

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

<!ELEMENT persistence-type (#PCDATA)>

One of the following values:

• Bean

• Container

EJB Role

Bean Provider

entity

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

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

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

Bean Provider

entity

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

<!ELEMENT primkey-field (#PCDATA)>

• 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

entity

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

<!ELEMENT reentrant (#PCDATA)>

One of the following values:

• True

• False

EJB Role

Bean Provider

entity

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

<!ELEMENT remote (#PCDATA)>

Bean Provider

• ejb-ref

• entity

• session

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.

<!ELEMENT res-auth (#PCDATA)>

One of the following values:

• Application

• Container

EJB Role

Bean Provider

Specifies the name of a resource manager connection factory reference.

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

Bean Provider

resource-ref

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

<!ELEMENT res-type (#PCDATA)>

Bean Provider

resource-ref

Declares the EJB's reference to an external resource.

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

Bean Provider

• entity

• session

role-link

Links a security role reference to a defined security role.

<!ELEMENT role-link (#PCDATA)>

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

Application Assembler

security-role-ref

Specifies the name of a security role.

<!ELEMENT role-name (#PCDATA)>

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

Application Assembler

• method-permission

• security-role

• security-role-ref

security-role

Defines a security role.

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

Application Assembler

assembly-descriptor

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

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

• 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

• entity

• session

session-type

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

<!ELEMENT session-type (#PCDATA)>

One of the following values:

• Stateful

• Stateless

EJB Role

Bean Provider

Declares a session bean.

<!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*)>

Bean Provider

enterprise-beans

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

<!ELEMENT small-icon (#PCDATA)>

• 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

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

<!ELEMENT transaction-type (#PCDATA)>

One of the following values:

• Bean

• Container

EJB Role

Bean Provider

session

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

<!ELEMENT trans-attribute (#PCDATA)>

One of the following values:

• NotSupported

• Supports

• Required

• RequiresNew

• Mandatory

• Never

EJB Role

Application Assembler

container-transaction

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.

<!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>