Chapter 22   Understanding Deployment Descriptors

This chapter provides an overview of the kinds of information that the bean developer and application assembler must add to the deployment descriptor before an EJB JAR can be deployed. This chapter also includes pointers to the appropriate SilverStream tool to accomplish the related tasks.

This chapter includes the following sections:

• About deployment descriptors

• SilverStream tools for creating deployment descriptors

• Converting EJB 1.0 deployment descriptors to EJB 1.1 format

About deployment descriptors   

The EJB JAR file is the deployment vehicle for Enterprise JavaBeans. The EJB JAR includes one or more EJB Java class files, their home and remote interfaces, and a deployment descriptor.

The deployment descriptor is an XML description of the contents of the EJB JAR. It initially contains information that a bean developer provides about the constituent beans. By the time it is deployed, it will contain all of the information that the EJB deployer and the EJB container need to create the proper runtime environment for the Enterprise JavaBeans contained in the EJB JAR.

The EJB specification defines the structure of the deployment descriptor as an XML file with its own DTD. The deployment descriptor contents consist of two parts:

Component	Description
Structural information	The first part of the deployment descriptor provides information about the individual beans in the EJB JARs, such as the name of the EJB's Java class file, the name of it's home and remote interfaces. This part of the deployment descriptor is required. It is written by the bean provider.
Application assembly information	The second part of the deployment descriptor includes information about the runtime attributes of the beans in the EJB JAR, such as entries that name roles, method permissions, and transaction attributes. The deployer then uses this combination of information to install the EJB JAR on the target server and to map this information to actual entities in the runtime environment. This information is optional until the beans are assembled into an application. An EJB JAR can be deployed and enabled without this part of the deployment descriptor.

Defining the bean's structural information   

The deployment descriptor entries that define the bean's structural information allow the application assembler and/or the deployer to customize some of the behavior of the EJB without changing the source code. They also allow the deployment tool to create the necessary home and remote objects for the constituent EJBs.

Required structural information

The deployment descriptor requires these entries for each EJB regardless of its type:

JAR Designer property name	XML tag	Description
Bean name	<ejb-name>	Used to differentiate this bean from others in the EJB JAR.
Bean class	<ejb-class>	The name of the class that implements the bean.
Home interface name	<home>	The name of the bean's home interface class.
Remote interface name	<remote>	The name of the bean's remote interface class.
Description	<description>	A textual description of the bean. You can provide any information that might be useful for application assemblers or deployers.

Session beans also require the following additional information

JAR Designer property name	XML tag	Description
State management type	<session-type>	Specifies whether the bean is a stateful or stateless session bean.
Transaction type	<transaction-type>	Specifies who manages the bean's transactions; the bean or the container.

Entity beans require this additional information:

JAR Designer property name	XML tag	Description
Primary key class name	<prim-key-class>	The name of the bean's primary key class.
Primary key field	<prim-key-field>	The primkey-field element is used with CMP beans. It specifies the name of the primary key field, that is, the field in the entity bean class that contains the primary key. (This is optional.)
Persistence type	<persistence-type>	Specifies who manages the bean's persistence; the bean or the container.
Reentrant	<reentrant>	Specifies whether or not the bean is reentrant.
Persistent fields	<cmp-field>     <field-name> </cmp-field>	The list of persistent fields that the container must load and store. (Optional for BMP beans.)

Other structural information

Each bean can optionally include entries for the following:

• Environment properties

• Bean references

• Role references

• Resource references

Environment properties

Environment properties allow the application assembler or deployer to map static data or variables to values that are meaningful to the operational environment. The bean developer must add entries and optionally initial values for each environment property that the bean references. The entries are added to the <env-entry> node of the deployment descriptor. They include:

JAR Designer property name	XML tag	Description
Name	<env-entry-name>	The name of the environment property. It is a required entry. It must exactly match the environment variable specified in the code. This is the name that is registered with JNDI and the name that the bean should reference. This allows you to substitute values for a variable instead of hardcoding values.
Value	<env-entry-value>	The entry's value.
Entry type	<env-entry-type>	The entry's data type.
Description	<description>	A textual description that allows you to communicate any special information to the application assembler, bean deployer, or administrator.

At deployment time, SilverStream registers the environment property with JNDI so it can be located by the bean at runtime.

    For more information on creating and setting the value of environment properties using the SilverStream IDE, see the chapter on the JAR Designer in the online Tools Guide. For an example of how environment properties are used, see the EJB section of the online Application Techniques.

Bean references

Bean references allow one or more EJBs to find the home object of other EJBs using a logical reference instead of an actual (and possibly not known) JNDI name. The bean developer must add entries for each of the EJB home objects that a bean references in the <ejb-ref> node of the deployment descriptor

JAR Designer property name	XML tag	Description
Bean name	<ejb-ref-name>	The name of the referenced bean as it is looked up by referring beans. The name of the bean reference in the java code. Required. This must exactly match the bean reference as specified in the code.
Referenced bean name	<ejb-link>	The referenced bean's class name.
Bean type	<ejb-ref-type>	The referenced bean's type (entity or session).
Home interface	<home>	The referenced bean's fully qualified home interface name.
Remote interface	<remote>	The referenced bean's fully qualified remote interface name.

    For more information on creating and setting the values of bean references using the SilverStream IDE, see the chapter on the JAR Designer in the online Tools Guide. For an example of how bean references are used, see the EJB section of the online Application Techniques.

Resource references

Resource references allow access to database connections in a connection pool. They allow the application assembler or deployer to customize the reference to a specific database that is available to the SilverStream Server in the operational environment. The values are added to the <resource-ref> node of the deployment descriptor and have the values shown below.

JAR Designer property name	XML tag	Description
Name	<res-ref-name>	The database or resource name. This is the name that will be registered with JNDI.
DataSource type	<res-type>	Resource type. SilverStream supports only the javax.sql.DataSource type.
Authorization type	<res-auth>	Specifies who performs the login to the resource. Values can be container or application.
Description	<description>	A textual description of this resource.

    For more information on creating and setting the values of resource references using the SilverStream IDE, see the chapter on the JAR Designer in the online Tools Guide. For an example of how resource references are used, see the EJB section of the online Application Techniques.

Role references

Role references allow the bean developer to use logical role names within the bean's code. The application assembler or deployer can then map the reference to an actual role in the operational environment. The following entries are made in the <security-role-ref> node of the deployment descriptor.

JAR Designer property name	XML tag	Description
Name	<role-name>	The role name as it is used within the EJB.
Role-link	<role-link>	The actual role name specified in the application assembly portion of the deployment descriptor. It must exactly match.
Description	<description>	A textual description of role reference. This is useful for application assemblers, bean deployers, and administrators. Optional.

    For more information on creating and setting the values of role references using the SilverStream IDE, see the chapter on the JAR Designer in the online Tools Guide. For an example of how role references are used, see the EJB section of the online Application Techniques.

Defining the bean's application assembly information   

The deployment descriptor entries that define the bean's application assembly information apply to the entire EJB JAR. The application assembler is responsible for providing the information that reflects the values in the operational environment. These values are added to the <assembly-descriptor> node of the deployment descriptor.

Application assembly entries   

Application assembly entries include the following:

• Roles

• Method permissions

• Transaction attributes

Specifying roles

Roles provide a way to group security permissions for a type of user (such as managers) or a group of users that will use an application in the same way (such as bank tellers). The application assembler must specify roles if the application requires that you set method permissions or are using role references. At deployment time, the deployer can map the role to an actual entity in the operational environment. The following values are added to the <security-role> node of the deployment descriptor

JAR Designer property name	Tag name	Description
Name	<role-name>	The role name created by application assembler. There should be an entry for each role in the deployment environment. At deployment these roles are mapped to individuals or groups in target environment.
Description	<description>	A textual description of this role.

    For more information on creating roles using the SilverStream IDE, see the chapter on the JAR Designer in the online Tools Guide.

Specifying method permissions

Method permissions allow you to specify the methods that users in a specific role can execute.

The following values must be added to the <method-permission> node of the deployment descriptor.

JAR Designer property name	XML tag	Description
Name	<role-name>	The role name created by application assembler. Specify a name for this set of method permissions. This name is used within the deployment descriptor only. It provides a way to differentiate multiple method permission specifications. You might provide a name that you can use to logically group these values like "Access to employee salary information".
Roles	<role-name>	The name of the role that has execute permission to the methods listed in this section.
Method	<method>    <ejb-name>     <method-name>     <method-name>	Choose Edit Methods... SilverStream launches a dialog box that lists all of the beans and their methods that reside in the EJB JAR. You can choose one or more methods from one or more bean. Specify * to include all of the methods in a bean.
Description	<description>	A textual description of the method permission.

Rules for specifying method permissions

These rules are as follows:

• The values are additive.

• You can specify a wild card to allow all the specified users access to all methods.

• If you do not specify method permissions the default is to allow all users in all roles to call methods.

• If you specify method permissions for one method in the JAR, you must specify method permissions for all methods. If you specify method permissions for only a subset, SilverStream assumes that none of the other methods can be called by any user in any rule.

    For more information on using the SilverStream IDE, see the chapter on the JAR Designer in the online Tools Guide.

Transaction attributes

Transaction attributes define a method's ability to participate in a transaction context. They are defined in the <container-transaction> node of the deployment descriptor and include the following entries.

JAR Designer property name	XML tag	Description
Name	<description>	A name that provides a way to group methods under a transaction attribute. The Name is only used by the deployment descriptor to differentiate multiple transaction attribute specifications. You might want to provide a name that you can use to logically group these values like "Methods with no transactions".
Attribute	<trans-attribute>	The transaction attribute to apply to the methods in this group. If you do not specify a transaction attribute, the SilverStream container defaults to Supports.
Method	<method>    <ejb-name>     <method-name>      (additional methods)         <trans-attribute>	This node lists the set of methods that have a particular transaction attribute. You can choose one or more methods from one or more bean. Specify * to include all of the methods in a bean.
Description	<description>	A textual description of the transaction.

The EJB specification defines the following values for the <trans-attribute> entries.

Transaction attribute	Description
Mandatory	The method must be called within an existing transaction context.
Never	The method must be invoked without a transaction context. If a client tries to call the method within a transaction context, the Container throws the java.rmi.RemoteException.
NotSupported	The container will not start a transaction and will suspend one if it exists.
Required	Runs in an existing transaction, or starts a new transaction which is committed when the method returns.
RequiresNew	The Container always starts a new transaction and commits it when the method returns. Any existing transaction is suspended until the method returns.
Supports	The container will not start a transaction, but will run the method within an existing transaction context if one exists. If you do not specify a transaction attribute, the SilverStream container defaults to Supports.

    For more information on setting transaction attributes using the SilverStream IDE, see the chapter on the JAR Designer in the online Tools Guide.

SilverStream tools for creating deployment descriptors   

You can create the EJB JAR and deployment descriptor using the SilverStream JAR Designer, or you can create one externally. You can use the JAR Designer to modify the externally created deployment descriptor using the JAR Designer tools.

    For more information on importing or creating an EJB JAR using the SilverStream IDE, see the chapter on the JAR Designer. For information on importing an EJB JAR without using the IDE, see the chapter on SilverCmd (specifically the ImportMedia command). Both chapters are included in the online Tools Guide.

Creating a single EJB JAR from multiple EJB JARs   

During application assembly, you might want to combine EJBs from one or more EJB JARs into an application. Because SilverStream requires that any bean references resolve to beans in the same EJB JAR, you might need to create a new composite EJB JAR that includes the contents of two or more different EJB JARs.

You should create the composite EJB JAR as part of your application assembly and not part of the deployment process.

Importing EJB JARs that include references to other JARs

If you have an EJB JAR file that you created outside of the SilverStream environment and it relies on classes in another EJB JAR or standard JAR, you will encounter an error when trying to import the JAR files.

When you import an EJB JAR file, SilverStream validates all of the classes in the EJB JAR. SilverStream will not be able to find the referenced classes during the import and will fail because there is no way to associate the secondary JAR with the EJB JAR during the import.

To make the import possible, you have the following options:

1. Permanently set your AGCLASSPATH to include a reference to the utility JAR. This ensures that SilverStream can find the classes on import and deployment of the EJB JAR.
   • Import the referenced JAR and make sure that it is referenced in all of the appropriate places (forms, pages, EJB deployments, and so on).

   • This option allows you to use either the IDE or SilverCmd to deploy the EJB JAR and results in a small footprint on the server since the utility classes are shared.

2. Temporarily set your classpath (using the +cp:a option on SilverCmd) to include a reference to the utility JAR.
   • As with the first option, you must import the referenced JAR and make sure that it is referenced in all of the appropriate places.

   • If you use the temporary setting, you must use SilverCmd to import the utility JAR and to deploy your EJB JAR. You cannot use the IDE to import or deploy the EJB JAR. Each time that you deploy the EJB JAR (or any EJB JARs derived from it, you must use SilverCmd and the +cp:a option).

   • Here is an example that shows how to use +cp:a:

       SilverCmd +cp:a c:\myUtility.JAR ImportMedia... 
       SilverCmd +cp:a c:\myUtility.JAR DeployEJB... 
     

3. Create a new EJB JAR outside of the SilverStream environment.
   • This new EJB JAR should contain the classes from both the EJB JAR and the referenced JAR. You can then import this new EJB JAR without any of the problems. However, this alternative can result in multiple copies of utility classes on the server.

Converting EJB 1.0 deployment descriptors to EJB 1.1 format   

SilverStream provides the SilverCmd ConvertEJB tool to convert EJB 1.0 serialized deployment descriptors to EJB 1.1 XML deployment descriptors.

What the conversion does not do

The conversion does not change any of the code in your bean classes or interfaces. Because EJB 1.0 relies on JDK1.1 and EJB 1.1 beans rely on JDK1.2. It is possible that your beans use deprecated or unsupported language elements.

If your beans do use unsupported features, they will not run properly in an EJB 1.1 compliant environment. For example, the javax.jts.UserTransaction has been deprecated (in EJB 1.1 it is javax.trans.UserTransaction). Since the javax.jts package has been deprecated, SilverStream does not include it in the classpath for SilverStream 3.0. This means that attempts to use some EJB 1.0 beans might result in NoClassDefFoundErrors.