Sun Microsystem Inc

Chapter 16 Deployment descriptor

This chapter defines the deployment descriptor that is part of the ejb-jar file. Section 16.1 provides an overview of the deployment descriptor. Sections 16.2 through 16.4 describe the information in the deployment descriptor from the perspective of the EJB roles responsible for providing the information. Section 16.5 defines the deployment descriptor’s XML DTD. Section 16.7 provides a complete example of a deployment descriptor of an assembled application.

16.1 Overview

The deployment descriptor is part of the contract between the ejb-jar file producer and consumer. This contract covers both the passing of enterprise beans from the Bean Provider to Application Assembler, and from the Application Assembler to the Deployer.

An ejb-jar file produced by the Bean Provider contains one or more enterprise beans and typically does not contain application assembly instructions. An ejb-jar file produced by an Application Assembler contains one or more enterprise beans, plus application assembly information describing how the enterprise beans are combined into a single application deployment unit.

The J2EE specification defines how enterprise beans and other application components contained in multiple ejb-jar files can be assembled into an application.

Sun Microsystems Inc.

The role of the deployment descriptor is to capture the declarative information (i.e information that is not included directly in the enterprise beans’ code) that is intended for the consumer of the ejb-jar file.

There are two basic kinds of information in the deployment descriptor:

•Enterprise beans’ structural information. Structural information describes the structure of an enterprise bean and declares an enterprise bean’s external dependencies. Providing structural information in the deployment descriptor is mandatory for the ejb-jar file producer. The structural information cannot, in general, be changed because doing so could break the enterprise bean’s function.

•Application assembly information. Application assembly information describes how the enterprise bean (or beans) in the ejb-jar file is composed into a larger application deployment unit. Providing assembly information in the deployment descriptor is optional for the ejb-jar file producer. Assembly level information can be changed without breaking the enterprise bean’s function, although doing so may alter the behavior of an assembled application.

16.2Bean Provider’s responsibilities

The Bean Provider is responsible for providing the structural information for each enterprise bean in the deployment descriptor.

The Bean Provider must use the enterprise-beans element to list all the enterprise beans in the ejb-jar file.

The Bean Provider must provide the following information for each enterprise bean:

•Enterprise bean’s name. The Bean Provider must assign a logical name to each enterprise bean in the ejb-jar file. There is no architected relationship between this name, and the JNDI

Sun Microsystem Inc

API name that the Deployer will assign to the enterprise bean. The Bean Provider specifies the enterprise bean’s name in the ejb-name element.

•Enterprise bean’s class. The Bean Provider must specify the fully-qualified name of the Java class that implements the enterprise bean’s business methods. The Bean Provider specifies the enterprise bean’s class name in the ejb-class element.

•Enterprise bean’s home interfaces. The Bean Provider must specify the fully-qualified name of the enterprise bean’s home interface in the home element.

•Enterprise bean’s remote interfaces. The Bean Provider must specify the fully-qualified name of the enterprise bean’s remote interface in the remote element.

•Enterprise bean’s type. The enterprise beans types are session and entity. The Bean Provider must use the appropriate session or entity element to declare the enterprise bean’s structural information.

•Re-entrancy indication. The Bean Provider must specify whether an entity bean is re-entrant or not. Session beans are never re-entrant.

•Session bean’s state management type. If the enterprise bean is a Session bean, the Bean Provider must use the session-type element to declare whether the session bean is stateful or stateless.

•Session bean’s transaction demarcation type. If the enterprise bean is a Session bean, the Bean Provider must use the transaction-type element to declare whether transaction demarcation is performed by the enterprise bean or by the Container.

•Entity bean’s persistence management. If the enterprise bean is an Entity bean, the Bean Provider must use the persistence-type element to declare whether persistence management is performed by the enterprise bean or by the Container.

•Entity bean’s primary key class. If the enterprise bean is an Entity bean, the Bean Provider specifies the fully-qualified name of the Entity bean’s primary key class in the prim-key-class element. The Bean Provider must specify the primary key class for an

Sun Microsystems Inc.

Entity with bean-managed persistence, and may (but is not required to) specify the primary key class for an Entity with container-managed persistence.

•Container-managed fields . If the enterprise bean is an Entity bean with container-managed persistence, the Bean Provider must specify the container-managed fields using the cmp-fields elements.

•Environment entries. The Bean Provider must declare all the enterprise bean’s environment entries as specified in Subsection 14.2.1.

•Resource manager connection factory references.The Bean Provider must declare all the enterprise bean’s resource manager connection factory references as specified in Subsection 14.4.1.

•EJB references. The Bean Provider must declare all the enterprise bean’s references to the homes of other enterprise beans as specified in Subsection 14.3.1.

•Security role references. The Bean Provider must declare all the enterprise bean’s references to security roles as specified in Subsection 15.2.5.3.

The deployment descriptor produced by the Bean Provider must be well formed in the XML sense, and valid with respect to the DTD in Section 16.5. The content of the deployment descriptor must conform to the semantics rules specified in the DTD comments and elsewhere in this specification. The deployment descriptor must refer to the DTD using the following statement:

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

16.3 Application Assembler’s responsibility

The Application Assembler assembles enterprise beans into a single deployment unit. The Application Assembler’s input is one or more ejb-jar files provided by one or more Bean Providers, and the output is also one or more ejb-jar files. The Application Assembler can combine multiple input ejb-jar files into a single output ejb-jar file, or split an input ejb-jar file into multiple output ejb-jar files. Each output ejb-jar file is either a deployment unit intended for the Deployer, or a partially assembled application that is intended for another Application Assembler.

The Bean Provider and Application Assembler may be the same person or organization. In such a case, the person or organization performs the responsibilities described both in this and the previous sections.

Sun Microsystem Inc

The Application Assembler may modify the following information that was specified by the Bean Provider:

•Enterprise bean’s name. The Application Assembler may change the enterprise bean’s name defined in the ejb-name element.

•Values of environment entries. The Application Assembler may change existing and/or define new values of environment properties.

•Description fields . The Application Assembler may change existing or create new description elements.

The Application Assembler must not, in general, modify any other information listed in Section 16.2 that was provided in the input ejb-jar file.

In addition, the Application Assembler may, but is not required to, specify any of the following application assembly information:

•Binding of enterprise bean references. The Application Assembler may link an enterprise bean reference to another enterprise bean in the ejb-jar file. The Application Assembler creates the link by adding the ejb-link element to the referencing bean.

•Security roles. The Application Assembler may define one or more security roles. The security roles define the recommended security roles for the clients of the enterprise beans. The Application Assembler defines the security roles using the security-role elements.

•Method permissions. The Application Assembler may define method permissions. Method permission is a binary relation between the security roles and the methods of the remote and home interfaces of the enterprise beans. The Application Assembler defines method permissions using the method-permission elements.

•Linking of security role references. If the Application Assembler defines security roles in the deployment descriptor, the Application Assembler must link the security role references declared by the Bean Provider to the security roles. The Application Assembler defines these links using the role-link element.

•Transaction attributes. The Application Assembler may define the value of the transaction attributes for the methods of the remote and home interfaces of the enterprise beans that require container-managed transaction demarcation. All Entity beans and the Session beans declared by the Bean Provider as transaction-type Container require container-managed transaction demarcation. The Application Assembler uses the container-transaction elements to declare the transaction attributes.

If an input ejb-jar file contains application assembly information, the Application Assembler is allowed to change the application assembly information supplied in the input ejb-jar file. (This could happen when the input ejb-jar file was produced by another Application Assembler.)