7.4 Deployment Descriptors

Deployment descriptors describe the contents of deployment units and configure components and applications to their environment. They also externalize the relationships between components, so those relationships can be managed without writing or changing program code. Deployment tools usually automatically generate deployment descriptors, so you do not have to edit and manage them directly.

There are five types of deployment descriptors, each of which corresponds to a type of deployment unit:

• EJB deployment descriptors are defined in the Enterprise JavaBeans specification.
• Web deployment descriptors are defined in the Java Servlet specification.
• Application and application client deployment descriptors are both defined in the J2EE platform specification.
• Resource adapter deployment descriptors for Java Connectors are defined by the J2EE Connector architecture specification.

Each deployment descriptor type is defined in its corresponding specification as an XML Document Type Definition (DTD).

Deployment descriptors contain information used by a component's container and also contain information that the component can access directly by way of the JNDI. The JNDI is a standard interface to an enterprise object name service.

7.4.1 J2EE Naming Environment

J2EE containers provide their components with a naming environment, which the component uses to look up client components, resources, and configuration information by name.

A component's deployment descriptor both specifies and resolves the explicit dependencies between the component and its environment. A component provider must declare any names a component uses in the component's deployment descriptor. An application assembler and/or deployer resolves each name by setting its value in a deployment descriptor. At runtime, a component instance looks up the resource or configuration information using a JNDI naming context provided by the container.

The JNDI naming context is the component's API for accessing the naming environment. To avoid collision with names of other enterprise resources in JNDI, and to avoid portability problems, all names in a J2EE application should begin with the string java:comp/env. Because all instances of a particular application component share naming environment entries, components may not change values in the naming context.

The naming context serves two general purposes: It provides parameters for component behavior and it decouples components from resources and from each other.

When a component is written in terms of parameters in the naming environment, its behavior can be changed externally instead of by changing code. A component provider can write component code whose behavior depends on the value of an environment entry, which is a named value defined by the component provider in the component's deployment descriptor. The assembler and/or deployer customizes the component's behavior by setting the environment entry's value.

An example of a component customized by an environment entry appears in Section 7.4.2.1.1.

Using environment entries to create configurable components is a BluePrints best practice. Parameterized components are more flexible than those that require code changes to modify behavior.

The naming environment's second purpose is to provide components with access to other components and resources by name, instead of directly. Decoupling components from one another provides two major benefits. First, a component's implementation can change with no impact on components referring to it, as long as the referenced component's public interface does not change. Second, because component instances are always accessed through a home interface rather than created by direct construction, the container can interpose on method calls and manage the component instance life cycle.

Users in different roles each use the naming environment in a different way. The component provider writes code that looks up components and resources by name in the naming environment, and declares usage of that name in the referencing component's deployment descriptor. The assembler and/or deployer configures the name to correspond to an object in the target environment, binding the name to a component or resource.

For examples of decoupling component code from other components, see Section 7.4.2.1.2. An example of decoupling component code from resources appears in Section 7.4.2.1.3.

The J2EE platform specification requires that components access one another and all external resources by way of the naming environment instead of loading component and connection factory classes directly. Decoupling components from resources and from each other lets the container make efficient decisions about how components access one another. Decoupling components from their resources provides deployment flexibility because each resource's implementation can be changed with no changes to component code.

7.4.2 Specifying Deployment Descriptor Elements

This section describes how to define specific deployment descriptor elements. It begins by describing elements common to all component types, and then covers elements specific to enterprise beans and Web components.

There are deployment descriptor elements common across the different J2EE component types. These include environment entries, references to enterprise beans, references to connection factories, references to resources in the environment, and security-related elements.

Environment entries allow customization of a component during deployment or assembly without the need to access or change the component's source code.

Customization requires cooperation between developer roles. A component provider writes component code whose behavior depends on the value of an environment entry, then defines the environment entry name and type in the component's deployment descriptor. An application assembler or deployer sets the environment entry's value to configure component behavior without changing the source code. An application assembler may set some environment entries to configure components for an application. A deployer may change values previously assigned by component providers and/or application assemblers to configure the application to its environment. The deployer must ensure that the values of all the environment entries declared by a component are set to meaningful values. The application component provider or application assembler may include a <description> element in each environment entry to help the deployer with this task. Description elements also commonly appear as help text in deployment tools.

Environment entries are declared with the env-entry element. Code Example 7.8 uses an environment entry to determine whether to send confirmation e-mail when an order is processed. Code Example 7.9 shows how to set the value of the environment entry.

public static boolean getSendConfirmationMail() {
	boolean boolVal = false;
	try {
		InitialContext ic = new InitialContext();
		Boolean bool = (Boolean)
			ic.lookup(
				"java:comp/env/ejb/CRMmail/SendConfirmationMail");
		if (bool != null) {
			boolVal = bool.booleanValue();
		}
	} catch (NamingException ne) {
		...
	}
	return boolVal;
}

<env-entry>
	<description>
		If true, customer receives confirmation e-mail 
		when an order is received
	</description>
	<env-entry-name>CRMmail/sendConfirmationMail</env-entry-name>
	<env-entry-type>java.lang.Boolean</env-entry-type>
	<env-entry-value>false</env-entry-value>
</env-entry>

7.4.2.1.2 Declaring and Resolving References to Enterprise Beans

J2EE components look up enterprise bean home interface references by name using JNDI. The deployment descriptors of both the referencing and referenced beans link the two beans together.

A component (an enterprise bean or Web-tier component) looks up an enterprise bean with JNDI using a logical name, which is the referencing component's local name for the reference. The application component provider indicates the lookup dependency by declaring all logical names used by a component in that component's deployment descriptor. Each enterprise bean in the application has an ejb-name, which is a global identifying name assigned by the application assembler. The application assembler resolves lookup dependencies by mapping logical names to ejb-names in the referencing component's deployment descriptor.

Code Example 7.10 through Code Example 7.12, taken from the sample application, illustrate how deployment descriptors link together a reference from a component to the referenced bean's home interface. Figure 7.4 graphically demonstrates the relationships between these code samples.

In Code Example 7.10, ShoppingClientControllerEJB performs a JNDI lookup of logical name java:comp/env/ejb/cart. (In other words, it looks up cart in the ejb subcontext of the environment naming context java:comp/env.

)

Figure 7.4 An Enterprise Bean Reference Resolves to a Home Interface

Code Example 7.11 shows part of the deployment descriptor for the referencing bean (ShoppingClientControllerEJB) that resolves the lookup of ejb/cart. The component provider declares and names an enterprise bean reference, using an ejb-ref-name element within an ejb-ref element. The reference's logical name is ejb/cart (relative to java:comp/env). The application assembler resolves the lookup dependency by adding an ejb-link element to the ejb-ref element, binding that lookup to the ejb-name TheCart.

Code Example 7.12 is an excerpt from the ShoppingCart bean's deployment descriptor. A session element declares the enterprise bean, and an ejb-name element within the session element defines the bean's ejb-name (TheCart). Among other things, the session element declares the bean's home interface class.

Figure 7.4 shows a direct mapping from a home interface name to the actual home interface; in J2EE implementations, the map from an ejb-name to the actual component is vendor-specific. For example, the J2EE reference implementation maps the ejb-name to the JNDI name of the bean's actual home interface in a separate XML file containing vendor-specific deployment information. See Section 7.5.2.1 on page 244 for an example and additional explanation.

An application assembler is usually the role that chooses ejb-names and binds them to logical names (with ejb-link), because the application assembler usually handles tying components together into applications. The deployer must ensure that all enterprise bean ejb-ref references are resolved (using ejb-link) to valid ejb-name elements in the referenced bean's deployment descriptor. Deployment verification tools can check that all such references are consistent.

public class ShoppingClientControllerEJB implements SessionBean {
	public ShoppingCart getShoppingCart() {
		if (cart == null) {
			try {
				ShoppingCartHome cartHome = 
					EJBUtil.getShoppingCartHome();
				cart = cartHome.create();
			} catch (CreateException ce) {
				...
			}
		}
		return cart;
	}
}
public static ShoppingCartHome getShoppingCartHome() {
	try {
		InitialContext initial = new InitialContext();
		Object objref = initial.lookup("java:comp/env/ejb/cart");
		return (ShoppingCartHome) PortableRemoteObject.
			narrow(objref, ShoppingCartHome.class);
	} catch (NamingException ne) {
		throw new GeneralFailureException(ne);
	}
}

<session>
	<ejb-name>TheShoppingClientController</ejb-name>
	<home>com.sun.estore.control.ejb.
		ShoppingClientControllerHome</home>
	...
	<ejb-ref>
		<ejb-ref-name>ejb/cart</ejb-ref-name>
		<ejb-link>TheCart</ejb-link>
		<ejb-ref-type>Session</ejb-ref-type>
		<home>com.sun.blueprints.cart.ejb.ShoppingCartHome</home>
		<remote>com.sun.blueprints.cart.ejb.ShoppingCart</remote>
	</ejb-ref>
	...
</session>

<session>
	<display-name>TheCart</display-name>
	<ejb-name>TheCart</ejb-name>
	<home>com.sun.blueprints.cart.ejb.ShoppingCartHome</home>
	<remote>com.sun.blueprints.cart.ejb.ShoppingCart</remote>
	<ejb-class>com.sun.blueprints.cart.ejb.ShoppingCartEJB</ejb-
class>
	<session-type>Stateful</session-type>
	<transaction-type>Container</transaction-type>
</session>

While this mechanism may at first seem complicated, it provides the required late binding between application components. The referencing bean's deployment descriptor both declares an explicitly named dependency of the bean on its environment and resolves that dependency by providing the ejb-name of the referenced bean. The referenced bean's deployment descriptor defines the global ejb-name that serves as the reference target.

An enterprise bean that is a target of ejb-link can be in the same EJB module or in another EJB module within the same J2EE application. The target enterprise bean must be type-compatible with the declared enterprise bean reference. This means that the target enterprise bean must be of the type indicated in the ejb-ref-type element and that the home and remote elements of the target enterprise bean must be type-compatible with the home and remote elements declared in the enterprise bean reference.

Always define all external resource references in a component's deployment descriptor. Even if your platform implementation indicates the JNDI name for a resource, the container is required by the specification to provide access only if the resource reference is declared in the deployment descriptor. Accessing JNDI objects without declaring them as external references may work for some implementations, but such behavior is not portable, and is not guaranteed to work properly. This advice also applies to environment resource references and EJB references (see the next section), and to all J2EE module types.

A connection factory is an object that creates connections to a resource manager. For example, an object that implements the javax.sql.DataSource interface is a connection factory for java.sql.Connection objects, which are connections to database management systems.

Declaration and resolution of connection factory references is similar to declaration and resolution of enterprise beans. A component provider declares a lookup of a connection factory using a resource-ref element in the referencing component's deployment descriptor and gives the reference a logical name (that is, the name by which the component looks up the connection factory) using a res-ref-name element. This allows the component module consumer (that is, application assembler or deployer) to discover all the connection factory references used by the component. The component provider also indicates the type of the connection factory, not the type of connection the factory produces. For example, a JDBC connection factory's type is DataSource, not Connection.

The deployer must bind the connection factory references to the actual resource factories configured in the target environment. The details of how to accomplish this binding are specific to the implementation. For example, in the J2EE reference implementation, a deployer uses the JNDI LinkRef mechanism to create a symbolic link to the actual JNDI name of the connection factory, which is defined by the container. The deployer must also provide any additional configuration information that the resource manager needs to open and manage the resource.

Code Example 7.13 illustrates the mail connection factory reference in the entry for the Mailer enterprise bean.

<session>
	<display-name>TheMailer</display-name>
	<ejb-name>TheMailer</ejb-name>
	<home>com.sun.blueprints.mail.ejb.MailerHome</home>
	<remote>com.sun.blueprints.mail.ejb.Mailer</remote>
	...
	<resource-ref>
		<res-ref-name>mail/MailSession</res-ref-name>
		<res-type>javax.mail.Session</res-type>
		<res-auth>Container</res-auth>
	</resource-ref>
</session>

Note that the connection factory type must be compatible with the type declared in the res-type element. The res-auth subelement of the resource-ref element specifies whether resource sign on is managed by an application component or by its container. See Section 6.4.5.1 on page 196 for more information on resource sign on.

The Mailer enterprise bean calls MailHelper to open a mail session. Code Example 7.14 contains the code from the MailHelper class that requests a mail session object declared as java:comp/env/mail/MailSession in the JNDI context.

public void createAndSendMail(String to, String subject,
									String htmlContents) {
	try {
		InitialContext ic = new InitialContext();
		Session session = (Session) ic.
			lookup("java:comp/env/mail/MailSession");
		...
	}
} 

By default, enterprise beans in the same transaction context may share connections to a resource. Where possible, it is good practice to allow the application server to optimize efficiency by sharing connections. In some cases, sharing can cause incorrect component behavior; for example, a connection may be session-based, requiring sign on or maintaining state that might be interfered with by other components. In these cases, turn off connection sharing by setting the connection factory's res-sharing-scope deployment descriptor element to Unshareable.

Resource environment references are like connection factory references, except that the logical name resolves to the actual resource instead of resolving to a factory that creates connections to the resource. An application component provider declares references to resources in the environment using a resource-env-ref element in the referencing component's deployment descriptor. The application component provider defines the reference's logical name (using resource-ref-env-name) and type (using resource-ref-env-type).

The deployer binds the resource environment reference to the actual resource in the container. As for connection factories, the mechanism for associating resource environment references with actual resources is vendor-specific.

For example, the sample application includes a Web service that sends purchase orders to suppliers based on incoming orders. Code Example 7.15, derived from the sample application, shows code of a message-driven enterprise bean looking up a message queue to which the component sends purchase orders. Notice that the queue's logical name is in JNDI subcontext java:comp/env/jms, because the resource is a JMS Queue. Code Example 7.16 shows the part of the message-driven bean's deployment descriptor that declares and names the resource environment reference. The actual runtime resolution of the resource reference is performed by the container in an implementation-specific way.

String spqName = "java:comp/env/
jms/SUPPLIER_PURCHASE_ORDER_QUEUE";
InitialContext ic = new InitialContext();
Queue supplierPoQueue = (Queue)ic.lookup(spqName);

<message-driven>
	<ejb-name>ORDER_APPROVAL_MDB_QUEUE</ejb-name>
	...
	<resource-env-ref>
		<resource-env-ref-name>
			jms/SUPPLIER_PURCHASE_ORDER_QUEUE
		</resource-env-ref-name>
		<resource-env-ref-type>
			javax.jms.Queue
		</resource-env-ref-type>
	</resource-env-ref>
</message-driven>

7.4.2.1.5 Security Elements

An application component provider uses the security-role element to define logical security roles that can be assumed by an authenticated principal. Code Example 7.17 illustrates how the sample application defines the gold_customer security role.

<security-role> 
	<role-name>gold_customer</role-name> 
</security-role>

The security-role-ref element is used to link a role name used by the method isCallerInRole with a security role. In the sample application, this method is used by the Order entity bean to enforce business rules based on whether the user is a preferred customer.

Code Example 7.18 and Code Example 7.19 illustrate how the security-role-ref element establishes a link between the string GOLD_CUSTOMER used by method isCallerInRole to the security role named gold_customer.

private int getBonusMiles() {
	int miles = (totalPrice >= 100) ? 1000 : 500;
	if (context.isCallerInRole("GOLD_CUSTOMER"))
		miles += 1000;
	return miles; 
}

<security-role-ref>
	<role-name>GOLD_CUSTOMER</role-name> 
	<role-link>gold_customer</role-link> 
</security-role-ref>

An application component provider declaratively controls access to an enterprise bean's methods by specifying the method-permission element in the enterprise bean's deployment descriptor. The component provider defines this element to list the set of methods that can be accessed by each security role. The authorization scenario described in Section 9.3.8 on page 302 illustrates how method-permission elements affect the execution of enterprise bean methods.

Enterprise beans have component-specific deployment descriptor elements for persistence and transaction control.

Transaction elements are deployment descriptor elements that control an enterprise bean's transactional behavior. An enterprise bean requires a transaction element that indicates whether the bean uses container- or bean-managed transaction demarcation. If transaction demarcation is container-managed, the bean's methods also have transaction attributes.

An application assembler must ensure that transaction attributes are defined for all methods of the deployed enterprise beans that use container-managed transaction demarcation. If the transaction attributes have not been assigned by the application component provider, they must be assigned by the application assembler. Code Example 7.20 illustrates how transaction attributes are declared for an Account entity bean. The container-transaction element for Account specifies that when method changeContactInformation is invoked, it must be within the scope of a transaction. See Section 8.6.3 on page 264 for detailed information about the values that a transaction attribute can take.

<container-transaction>
	<method>
		<ejb-name>TheAccount</ejb-name>
		<method-intf>Remote</method-intf>
		<method-name>changeContactInformation</method-name>
		<method-params>
			<method-param>
				com.sun.blueprints.util.ContactInformation
			</method-param>
		</method-params>
	</method>
	<trans-attribute>Required</trans-attribute>
</container-transaction>

The application component provider must specify whether a bean manages its own persistence or uses container-managed persistence. When a bean uses container-managed persistence, the application component provider must specify the fields of the bean. Code Example 7.21 illustrates how the Account entity bean uses the persistence-type element to declare that it will manage its own persistence.

<entity>
	<description>Account of a shopper</description>
	<display-name>TheAccount</display-name>
	...
	<persistence-type>Bean</persistence-type>
</entity>

Some of the more commonly used Web component deployment descriptor elements are discussed in this section.

The one deployment descriptor element that must be specified for a Web component is the servlet element, shown in Code Example 7.22. This element associates a logical identifier (servlet-name) with the name of the servlet class or the JSP file associated with the component.

<servlet>
	<servlet-name>webTierEntryPoint</servlet-name>
	<display-name>HTML Client Front Controller Servlet
		</display-name>
	<description>no description</description>
<servlet-class>
	com.sun.j2ee.blueprints.waf.controller.web.MainServlet
	</servlet-class>
</servlet>

7.4.2.3.2 Servlet Mapping

The servlet-mapping element specifies the URLs that the Web component is aliased to handle. While the element is called servlet-mapping, it is used to map URLs to both servlets and JSP pages. Code Example 7.23 aliases Main servlet to handle all requests to the URL namespace *.do.

<servlet-mapping>
	<servlet-name>webTierEntryPoint</servlet-name>
	<url-pattern>/control/*</url-pattern>
</servlet-mapping>

7.4.2.3.3 Error Pages

The error-page element can be used to invoke an error page automatically when the Web application throws a Java language exception. Code Example 7.24 shows how to enable the J2EE server to send errorpage.jsp to the browser client if the Web application ever throws any exception of the type java.lang.Exception or its subclass.

<error-page>
	<exception-type>java.lang.Exception</exception-type>
	<location>/errorpage.jsp</location>
</error-page>

7.4.2.3.4 Form-Based Authentication Configuration

Form-based authentication is the preferred mechanism for authenticating application users in the J2EE platform. Code Example 7.25 illustrates how to configure a Web application to activate form-based authentication when the Web server receives a request for the URL /control/placeorder. The security-constraint element specifies that the URL /control/placeorder is a protected resource. The login-config element specifies that the URL formbasedloginscreen will be displayed when an unauthenticated user tries to access /control/placeorder. This page contains an HTML form that prompts for a user name and password.

<security-constraint>
	<web-resource-collection>
		<web-resource-name>MySecureBit0</web-resource-name>
		<description>no description</description>
		<url-pattern>/control/placeorder</url-pattern>
		<http-method>POST</http-method>
		<http-method>GET</http-method>
	</web-resource-collection>
	<auth-constraint>
		<description>no description</description>
		<role-name>gold_customer</role-name>
		<role-name>customer</role-name>
	</auth-constraint>
	<user-data-constraint>
		<description>no description</description>
		<transport-guarantee>NONE</transport-guarantee>
	</user-data-constraint>
</security-constraint>
<login-config>
	<auth-method>FORM</auth-method>
	<realm-name>default</realm-name>
	<form-login-config>
		<form-login-page>formbasedloginscreen</form-login-page>
		<form-error-page>formbasedloginerrorscreen
			</form-error-page>
	</form-login-config>
</login-config>

7.4.3 Naming Convention Recommendations

Logical names are the names a component uses to refer to external objects. For example, Code Example 7.10 (on page 229) looks up a home interface using a logical name, java:comp/env/ejb/cart, and Code Example 7.11, using ejb-link, binds that logical name to the ejb-name TheCart. Code Example 7.12 declares the shopping cart object and gives it the physical name TheCart.

Each component has its own scope for the logical names it uses, so components can use the same logical name to refer to different objects, and the references will not collide. For example, although a Customer bean and a Supplier bean might both look up an associated enterprise bean by the logical name ejb/Address, each would access a different bean if each reference were bound (with ejb-link) to a different element. Each time a component performs a lookup using the same name, the same object (or an equivalent one) is returned from the naming context.

There are few requirements or restrictions on the internal structure of logical names. Conventions for logical names help to organize references of different types and make it more clear to an application assembler or deployer just what sort of object she is dealing with.

The name of an environment entry should use the subcontext of the component it configures. Code Example 7.26 from the sample application shows that the environment entry CatalogDAOClass appears in JNDI subcontext  java:comp/env/ejb/catalog, because this environment entry is specific to the Catalog enterprise bean. Environment entries that configure an application globally, or configure more than one component, may be placed in the java:comp/env subcontext.

<env-entry>
	<env-entry-name>ejb/catalog/CatalogDAOClass</env-entry-name>
	<env-entry-type>java.lang.String</env-entry-type>
	<env-entry-value>...</env-entry-value>
</env-entry>

7.4.3.0.2 Naming Enterprise Bean References

JNDI subcontext java:comp/env/ejb should be used for the logical names of all EJB references. An additional subcontext level that groups tightly-coupled beans may also be useful. Code Example 7.27 illustrates how the sample application uses the JNDI subcontext java:comp/env/ejb/controller to group the shopping client controller and the shopping facade beans, since these two beans are intimately related. Grouping related classes into subcontexts can clarify for the application assembler or deployer which enterprise beans work with or depend on each other.

<ejb-local-ref>
	<ejb-ref-name>
		ejb/controller/ShoppingClientController
	 </ejb-ref-name>
	<ejb-ref-type>Session</ejb-ref-type>
	<local-home>...</local-home>
	...
	<ejb-link>TheShoppingClientController</ejb-link>
</ejb-local-ref>

<ejb-local-ref>
	<ejb-ref-name>ejb/controller/ClientFacade</ejb-ref-name>
	<ejb-ref-type>Session</ejb-ref-type>
	<local-home>...</local-home>
	...
	<ejb-link>TheShoppingClientFacade</ejb-link>
</ejb-local-ref>

7.4.3.0.3 Naming Connection Factory References

The J2EE platform specification version 1.3 provides several guidelines for logical names for connection factory resource references. Consistent logical naming groups resources by resource manager type, making it clear to the application assembler or deployer what sort of resource needs to be configured for each reference. Table 7.1 shows recommended JNDI subcontexts for common J2EE resource connection factory types.

Logical names for environment resource references should follow the same conventions as for connection factories. For example, JMS message destinations should be placed in the java:comp/env/jms subcontext.

Recommended JNDI Subcontexts for Connection Factories

Resource Manager Type	Connection Factory Type(s)	JNDI Subcontext
JDBC	javax.sql.DataSource	java:comp/env/jdbc
JMS	javax.jms.TopicConnectionFactoryjavax.jms.QueueConnectionFactory	java:comp/env/jms
JavaMail	javax.mail.Session	java:comp/env/mail
URL	java.net.URL	java:comp/env/url
Connector	javax.resource.cci.ConnectionFactory	java:comp/env/eis