Facilities Guide

CHAPTER 3

Deployment Plan DTDs

This chapter provides reference documentation for the Novell exteNd Application Server deployment plan DTDs. Topics include:

Before you begin A basic understanding of XML is recommended for this chapter.

About the deployment plan DTDs

The deployment plan DTD files are used when you deploy J2EE archives to the application server. These DTDs (XML document type definitions) describe the structure you must follow when writing deployment plans for particular kinds of archives.

DTD and sample XML files Here's a summary of the names and locations of these files:

To find	Look here in your server's install
The deployment plan DTD files	\Resources\DTDCatalog directory
Sample deployment plan XML files that use the DTDs	\Samples\SilverCmd directory

DTD documentation You can learn about the DTDs by looking at:

The DTD files themselves—for comments about the elements they define
This chapter—for details, hints, and examples for a subset of the elements

Editing deployment plans To create and edit a deployment plan, you can use:

The exteNd Director Deployment Plan Editor
An XML editor or text editor of your choice

Client JAR deployment plan DTD

This section provides reference information about the application server's client JAR deployment plan DTD:

DTD file The client JAR deployment plan DTD is deploy-car_1_3.dtd.

Selected elements A subset of the elements defined by the client JAR deployment plan DTD are described below (in alphabetical order):

beanLink element
```
  <!ELEMENT beanLink (#PCDATA)>
```
Specifies the JNDI name of an EJB referenced by the application client. The referenced EJB can be located on a server other than the one the application client is deployed on.

Specifying the server host for a beanLink Whether you deploy your client JAR by itself or in an EAR, you must be careful about how you specify the application server host name for any EJB references you map — because the host name you type when invoking SilverJ2EEClient must exactly match the host name that appears in the beanLink elements of your deployment plan:
- Guidelines For instance, if the host name portion of the beanLink specifies myserver:
```
  <beanLink>sssw://myserver/RMI/sbOrderSummary</beanLink>
```
  the SilverJ2EEClient command line must also specify that name:
```
  SilverJ2EEClient myserver snuckerby appclient Sam
```
  Alternatively, both may specify the IP address of that server — or both may specify localhost (although it's generally best to avoid using localhost). If you specify the server's port number (such as myserver:80) in one, you must specify it in both.
- Troubleshooting If there isn't an exact match (such as if one specifies the server's host name while the other specifies its IP address), a runtime error will occur when your client tries to access an EJB:
```
  java.rmi.RemoteException: Unable to get a valid session for a request
```
- For EARs If you decide to deploy your client JAR within an EAR, this matching requirement still applies, whether you specify the host name in your EAR deployment plan or on the SilverCmd DeployEAR command line.
clientDataSource element
```
  <!ELEMENT clientDataSource (jdbcURL?, jdbcDriver?,
     jdbcUsername?,jdbcPassword?)> 
```
Container element that describes access to a javax.sql.DataSource accessed by the application client. Clients access data source resources directly, so the client must have the appropriate JDBC drivers installed for the data sources it needs to access. These values are passed as Strings. See the documentation for your particular data source for the correct syntax for jdbcURL, jdbcDriver, jdbcUsername, and jdbcPassword.

mailRefProperties element

  <!ELEMENT mailRefProperties (el+)>

Specifies the set of name/value pairs to associate with a resource reference of type javax.mail.Session, as determined by the JavaMail specification.

Some examples include:

  mail.host
  mail.from
  mail.user
  mail.store.protocol
  mail.transport.protocol
  mail.debug
  mail.[protocol].host (for example, mail.http.host)
  mail.[protocol].user (for example, mail.http.user)

name element
```
  <!ELEMENT name (#PCDATA)>
```
Specifies the name of an environment entry, a resource reference, or an EJB reference. The name must match the name of an entry of the same type in the deployment descriptor (if it does not, you'll get a warning message during deployment).
resourceEnvReference
```
  <!ELEMENT resourceEnvReference (name, resourceJNDIName)>
```
Maps a resource environment reference name to a JNDI name. Each occurrence of resource-env-ref in the deployment descriptor should have one corresponding resourceEnvReference in the deployment plan to specify the JNDI name. The name element must be the same as the corresponding resource-env-ref-name in the deployment descriptor.
resourceJNDIName element
```
  <!ELEMENT resourceJNDIName (#PCDATA)>
```
Specifies the JNDI name for a resource reference. All resource references must contain a JNDI name except javax.sql.DataSource and java.net.URL resource references.

The JNDI name can be located on a server other than the one the application client is on. To find a resourceJNDIName, use this syntax:
```
  <resourceJNDIName>sssw://server:port/RMI/JNDINameOfResource
     </resourceJNDIName>
```
resourceReference element
```
  <!ELEMENT resourceReference(name,(clientDataSource|resourceURL|resourceJNDIName|mailRefProperties))>
```
Container element for resource references. You must specify the resource reference name (from the deployment descriptor) plus one of the following:
- A data source for references of type javax.sql.DataSource
- An URL for references of type java.net.URL
- A JNDI name for references of type javax.jms.QueueConnectionFactory or javax.jms.TopicConnectionFactory
- A String array (to be treated as an array of name/value pairs) for references of type javax.mail.Session
resourceURL element
```
  <!ELEMENT resourceURL (#PCDATA)>
```
Specifies the URL that will be looked up at runtime for a specific JNDI name.

EJB JAR deployment plan DTD

This section provides reference information about the EJB JAR deployment plan DTD:

DTD file The EJB JAR deployment plan is deploy-ejb_2_0.dtd.

Selected elements A subset of the elements defined by the EJB JAR deployment plan DTD are described below (in alphabetical order):

alternateColumn element
```
  <!ELEMENT alternateColumn (#PCDATA)>
```
Specifies an alternate column with a SQL type of BIGINT to manage the handling of data of type BLOB when isolationLevel is TRANSACTION_READ_COMMITTED.
autoInc element
```
  <!ELEMENT autoInc (autoIncSequenceName?, (schemaName?, autoIncTableName, columnName)?)>
```
Specifies the support for an autoincrement column:
- For databases that support autoincrement (most databases), an empty autoInc element is all that is required.
- For Oracle databases, the autoIncSequenceName element specifies the sequence name used.
- For databases that do not support autoincrement, use the schemaName element, autoIncTableName element, and columnName element to generate a unique number.
beanJNDIName element
```
  <!ELEMENT beanJNDIName (#PCDATA)>
```
Specifies the JNDI name of an EJB. The JNDI name is used by the container to register the bean within the JNDI namespace. Any code that calls the bean must find it first using the JNDI name. JNDI names must be unique within a server and across servers in a cluster. You should consider using a hierarchical structure for naming your beans. You might even want to include the company name (or initials) within the hierarchy to ensure that EJBs are unique. Some examples include:
```
  abccorp/samples/SalesDemo/Customers
  com/sssw/samples/BankDemo/SessionBeans/AddCustomer
  com/sssw/samples/BankDemo/EntityBeans/Customer
```
The JNDI lookup for these examples would be (respectively):
```
  contextEnv.lookup("RMI/abccorp/samples/SalesDemo/Customers");
  contextEnv.lookup("RMI/com/sssw/samples/BankDemo/SessionBeans/
     AddCustomer");
  contextEnv.lookup("RMI/com/sssw/samples/BankDemo/EntityBeans/
     Customer");
```
beanLink element
```
  <!ELEMENT beanLink (#PCDATA)>
```
Specifies the JNDI name of a referenced EJB. That EJB can be located on another server.

Here are two examples of specifying the JNDI name of an EJB:
- On the same server:
```
  <beanLink>SBBankATM</beanLink>
```
- On a different server:
```
  <beanLink>sssw://myServer:80/RMI/SBBankATM</beanLink>
```
When you specify a link to an EJB that resides on a different server, you have to copy the remote JAR for the referenced bean to the server from which it is being referenced.
classpathJars element
```
  <!ELEMENT classpathJars (excludeJ2EEXMLJars?, userlibJars?)>
```
This element allows a list of JAR files to be used in an application without deploying them to the server. It also allows the user to disable the inclusion of the default XML JARs that are used to pass the CTS tests.
columnName element
```
  <!ELEMENT columnName (#PCDATA)>
```
Maps a cmp-field (a persistent field) to a database column. The name must match the COLUMN_NAME property returned by JDBC DataMetaData.getColumns().

delayInstantiation element

  <!ELEMENT delayInstantiation (#PCDATA)>

Specifies whether a CMP entity bean is instantiated immediately (FALSE—the default) or only when required (TRUE).

This element determines how the server will retrieve and cache data during finder method execution. Beans whose instantiation is delayed are called lazy beans.

Here are the possible scenarios:

Scenario	Description
You set delay instantiation to TRUE, but the finder method is not part of a transaction context (an unspecified context)	The server ignores the setting. When you call a finder method, the server retrieves the primary key and does not cache any of the data. If your bean requires subsequent use of this data, the server must retrieve the data at that point.
You set delay instantiation to TRUE, and the finder method is part of a transaction context	The server retrieves only the primary key for each of the finder methods. Any subsequent method calls on that bean cause the server to access the database again to retrieve the data and populate the fields for the bean. Although this causes an additional trip to the database, it can be more efficient in cases where the data is large or the application is only interested in a single record. It allows the application to do some processing to determine which record it wants. For applications that will only access a single bean, the initial load time for all beans might not be worth it.
You set delay instantiation to FALSE, and the finder method is part of a transaction context	The server retrieves the primary keys and also retrieves all values for all persistent mapped fields for each bean. The server caches this data. If the client makes subsequent method calls for any of the fields, the server will not need to retrieve any additional data from the database (because it will have cached all records). Depending on your data, this could improve or degrade your performance. It might degrade performance if the bean has a lot of fields or the fields contain large amounts of data. For example, if the beans you are retrieving contain a BLOB field and you do not need access to all of the records, this might not be the right strategy for your application.

Scenario

Description

You set delay instantiation to TRUE, but the finder method is not part of a transaction context (an unspecified context)

The server ignores the setting.

When you call a finder method, the server retrieves the primary key and does not cache any of the data. If your bean requires subsequent use of this data, the server must retrieve the data at that point.

You set delay instantiation to TRUE, and the finder method is part of a transaction context

The server retrieves only the primary key for each of the finder methods.

Any subsequent method calls on that bean cause the server to access the database again to retrieve the data and populate the fields for the bean.

Although this causes an additional trip to the database, it can be more efficient in cases where the data is large or the application is only interested in a single record. It allows the application to do some processing to determine which record it wants.

For applications that will only access a single bean, the initial load time for all beans might not be worth it.

You set delay instantiation to FALSE, and the finder method is part of a transaction context

The server retrieves the primary keys and also retrieves all values for all persistent mapped fields for each bean. The server caches this data.

If the client makes subsequent method calls for any of the fields, the server will not need to retrieve any additional data from the database (because it will have cached all records).

Depending on your data, this could improve or degrade your performance. It might degrade performance if the bean has a lot of fields or the fields contain large amounts of data. For example, if the beans you are retrieving contain a BLOB field and you do not need access to all of the records, this might not be the right strategy for your application.

deployedObject element
```
  <!ELEMENT deployedObject (#PCDATA)>
```
Specifies the name of the EJB deployed object to create on the application server. It is optional and can also be specified on the command line (when deploying with SilverCmd DeployEJB).

When this element is not specified, deployment generates a name by appending the word Deployed to the value of the ejbJarName element.
destinationName element
```
  <!ELEMENT destinationName (#PCDATA)>
```
Specifies the Queue or Topic Name. It must be specified like this:
```
  corbaname:iiop:JMSServer:53506#queue/queueName
```
Specifies the mapping of a CMP field to a database column.

mailRefProperties element

  <!ELEMENT mailRefProperties (el+)>

Specifies the set of name/value pairs to associate with a resource reference of type javax.mail.Session, as determined by the JavaMail specification.

Some examples include:

  mail.host
  mail.from
  mail.user
  mail.store.protocol
  mail.transport.protocol
  mail.debug
  mail.[protocol].host (for example, mail.http.host)
  mail.[protocol].user (for example, mail.http.user)

relationRole element
```
  <!ELEMENT relationRole (beanName, cmrFieldName?, columnNames?)>
```
Defines a role within a relation and contains:
- The bean name (from the deployment descriptor) for the source of a role that participates in the relationship. It needs to match that of the relationship-role-source element in the ejb-relationship-role node.
- The CMR field name for the role (from the deployment descriptor). It needs to match the cmr-field-name (when there is no cmr-field-name this element shouldn't exist either). The deployer uses beanName and cmrFieldName to match the relationship.
- A list of column names (that most frequently contains only one element) the container uses to manage the relationships. These are typically the foreign keys. For many-to-many relationships, these are the foreign key column names in the link table that correspond to the primary key for the bean.
resourceEnvReference element
```
  <!ELEMENT resourceEnvReference (name, resourceJNDIName)>
```
Specifies the mapping of a resource environment reference name to a JNDI name. Each occurrence of resource-env-ref in the deployment descriptor should have one corresponding resourceEnvReference in the deployment plan, to specify the JNDI name. The name element must be the same as the corresponding resource-env-ref-name in the deployment descriptor.

WAR deployment plan DTD

This section provides reference information about the WAR deployment plan DTD:

DTD file The WAR deployment plan DTD is deploy-war_2_3.dtd.

Selected elements A subset of elements defined by the WAR deployment plan DTD are described below (in alphabetical order):

beanLink element
```
  <!ELEMENT beanLink (#PCDATA)>
```
Specifies a link to a referenced EJB. This may be an internal name if the EJB is in the same JAR, or a JNDI name if it's in a different JAR. The EJB can be located on a different server.

Here are two examples of specifying the JNDI name of an EJB:
- On the same server:
```
  <beanLink>SBBankATM</beanLink>
```
- On a different server:
```
  <beanLink>sssw://myServer:80/RMI/SBBankATM</beanLink>
```
classpathJars element
```
  <!ELEMENT classpathJars (excludeJ2EEXMLJars?, userlibJars?)>
```
This element allows a list of JAR files to be used in an application without deploying them to the server. It also allows the user to disable the inclusion of the default XML JARs that are used to pass the CTS tests.
deployedObject element
```
  <!ELEMENT deployedObject (#PCDATA)>
```
Specifies the name of the deployed object to create on the application server. When this element is not specified, deployment generates a name by appending the word Deployed to the value of the warJarName element.
deployToFilesystem element
```
  <!ELEMENT deployToFilesystem (#PCDATA)>
```
Specifies whether or not the application should be deployed to the file system on the application server. The default is FALSE (no file system deployment).
excludedJSPs element
```
  <!ELEMENT excludedJSPs (el+)>
```
List of JSP resources that should not be compiled. (Typically, JSP pages intended to be included in other JSP pages should not be compiled on their own.)

mailRefProperties element

  <!ELEMENT mailRefProperties (el+)>

Specifies the set of name/value pairs to associate with a resource reference of type javax.mail.Session, as determined by the JavaMail specification.

Some examples include:

  mail.host
  mail.from
  mail.user
  mail.store.protocol
  mail.transport.protocol
  mail.debug
  mail.[protocol].host (for example, mail.http.host)
  mail.[protocol].user (for example, mail.http.user)

name element
```
  <!ELEMENT name (#PCDATA)>
```
Specifies the name of an environment entry, a resource reference, an EJB reference, a role mapping, or a context parameter entry. The name must match the name of an entry of the same type in the deployment descriptor (if it does not, you'll get a warning message during deployment).
resourceJNDIName element
```
  <!ELEMENT resourceJNDIName (#PCDATA)>
```
Specifies the JNDI name for a resource reference. All resource references must contain a JNDI name, except for javax.sql.DataSource or java.net.URL resource references.

The JNDI name can be located on a server other than the one containing the WAR. When accessing a different server, use this syntax:
```
  <resourceJNDIName>sssw://server:port/RMI/JNDINameOfResource
     </resourceJNDIName>
```
resourceReference element
```
  <!ELEMENT resourceReference (name, (dataSource | resourceURL |
     resourceJNDIName | mailRefProperties))>
```
Container element for resource references. You must specify the resource reference name (from the deployment descriptor) plus one of the following:
- A data source for references of type javax.sql.DataSource
- An URL for references of type java.net.URL
- A JNDI name for references of type javax.jms.QueueConnectionFactory or javax.jms.TopicConnectionFactory
- A String array (to be treated as an array of name/value pairs) for references of type javax.mail.Session
sessionTimeout element
```
  <!ELEMENT sessionTimeout (#PCDATA)>
```
Specifies session timeout in minutes. Here is the hierarchy of session timeout precedence, from highest to lowest:
- The timeout set programmatically with HttpSession.setMaxInactiveInterval() (in seconds)
- The deployment plan (in minutes)
- The deployment descriptor (in minutes)
- The server's default session timeout

RAR deployment plan DTD

This section provides reference information about the resource adapter archive (RAR) deployment plan DTD:

DTD file The RAR deployment plan DTD is deploy-rar_1_0.dtd.

Selected elements A subset of the elements defined by the RAR deployment plan DTD are described below (in alphabetical order):

idleTimeout
```
  <!ELEMENT idleTimeout (#PCDATA)>
```
Specifies the number of seconds an unused connection remains in the pool before the server destroys it. The default is 60 seconds. The value you specify will depend on the type of applications that will rely on the connection pool. If you specify shorter timeout periods, the server may be forced to create connections more often—and creating connections is an expensive operation. But if you specify a timeout that is too long, other applications may be forced to wait for an available connection.
isEnabled
```
  <!ELEMENT isEnabled (#PCDATA)>
```
Specifies whether the RAR is enabled (the default) or not. You disable a deployed RAR by setting this flag to FALSE and redeploying the RAR.
name
```
  <!ELEMENT name (#PCDATA)>
```
Specifies the name of the ManagedConnectionFactory.
password
```
  <!ELEMENT password (#PCDATA)>
```
Specifies the password for the default connections created in the pool. A default connection is created when users invoke ConnectionFactory.getConnection(). This is the preferred method for obtaining a connection, because it allows the server to efficiently pool connections.
poolName
```
  <!ELEMENT poolName (#PCDATA)>
```
Specifies the name of the connection pool added to the server. Use this name to administer the connection pool.
resourceAdapterName
```
  <!ELEMENT resourceAdapterName (#PCDATA)>
```
Specifies the name under which the resource adapter will be deployed in the application server. This is a logical name.
user
```
  <!ELEMENT user (#PCDATA)>
```
Specifies the user name for the default connections created in the pool. A default connection is created when users invoke ConnectionFactory.getConnection(). This is the preferred method for obtaining a connection, because it allows the server to efficiently pool connections.

EAR deployment plan DTD

This section provides reference information about the EAR deployment plan DTD:

DTD file The EAR deployment plan DTD is deploy-ear_1_3.dtd.

Selected elements A subset of elements are described below (in alphabetical order):

alternateDeplDesc element
```
  <!ELEMENT alternateDeplDesc (#PCDATA)>
```
Identifies a deployment descriptor to use for a specified module. Use this element when you do not want to use the deployment descriptor in the specified module's archive. The alternate deployment descriptor that you specify must be in the EAR.

There are two situations when you might want to use this element:
- If you want to use the same module twice but want to configure the two uses differently
- If there are two instances of the module in the EAR (such as two EJB JARs) and you want to configure the modules differently
classpathJars element
```
  <!ELEMENT classpathJars (excludeJ2EEXMLJars?, userlibJars?)>
```
This element allows a list of JAR files to be used in an application without deploying them to the server. It also allows the user to disable the inclusion of the default XML JARs that are used to pass the CTS tests.
deployAs element
```
  <!ELEMENT deployAs (#PCDATA)>
```
Overrides the name under which the module would normally be deployed. By default, the EAR deployment process creates a deployment name that is a combination of the EAR name and the module name. For EJB modules, this name (if specified) is also used as the base name for the remote JAR. Use with caution.
earJarName element
```
  <!ELEMENT earJarName (#PCDATA)>
```
Specifies the name of the EAR to deploy. You may specify this in the deployment plan or on the command line (when deploying with SilverCmd DeployEAR). Values specified on the command line take precedence. You can specify a full path (if the EAR is on disk) or just the name. When you specify just the name and the EAR is not in the current directory, the EAR is assumed to already exist in the same database and server to which it is being deployed.
module element
```
  <!ELEMENT module (ejbJar | warJar | carJar)>
```
Describes a specific J2EE module in the EAR.

The information contained in this element is the deployment plan for the specific module. You should cut and paste the deployment plan from the application client JAR, EJB JAR, or WAR to complete this section.

For EJBs, the beanName components of the bean element must be unique within the EAR or you will encounter errors when deploying the EAR (because the bean names are used to resolve bean references within an EAR).
name element
```
  <!ELEMENT name (#PCDATA)>
```
Specifies the name of a role reference that must be mapped to a user or group name. It must match the name of a role reference entry in the deployment descriptor (if it does not, a warning is generated at deployment).
order element
```
  <!ELEMENT order (#PCDATA)>
```
Identifies the order of deployment of the modules. The smaller the number the higher its deployment priority. Modules without the order element are deployed after ordered modules.
roleMap element
```
  <!ELEMENT roleMap (roleMapping+)>
```
Container for EAR-level role mappings.

You might consider mapping security roles at the EAR level and not within individual modules (EJB JARs, WARs, and so on). This allows you to combine and simplify the security settings for the constituent J2EE modules.

Here are the basic rules:
- If the individual modules do not contain any role maps, the EAR-level role map is used
- If some or all individual modules and the EAR both contain a role map:
  
  And the roles are unique, the role map used for each module is a union of the EAR-level role map and the module
  
  And one or more of the roles are not unique, the module-level role map takes precedence for the duplicate role and the unique roles are added to the role map
This example illustrates how a role map is determined when roles are not unique. If the EAR-level role map contains the following values:

This role

Is mapped to this userOrGroupName

EJBAdmin

Zack

User

Mary

and an EJB module within the EAR contains this role map:

This role

Is mapped to this userOrGroupName

Admin

Joe

User

Helen

then the role map used for the EJBs will look like this:

This role

Is mapped to this userOrGroupName

Admin

Joe

User

Helen

EJBAdmin

Zack

In this case, the EJB module's User role takes precedence. The Admin role is added to the EJB's role mapping, because it is inherited from the EAR's role map.
userOrGroupName element
```
  <!ELEMENT userOrGroupName (#PCDATA)>
```
Specifies the name of a principal in a security policy domain or a user group in the operational environment. This is mapped to a role reference name from the deployment descriptor. You can map a role reference to any of the security domains supported by the application server.
userlibJars element
```
  <!ELEMENT userlibJars (el+)>
```
Lists any additional JAR files that should be made available to the application. The JARs must reside in the server's userlib directory. The value is a StringArray of JAR names, relative to (and contained within) the userlib directory.

This role	Is mapped to this userOrGroupName
EJBAdmin	Zack
User	Mary

This role	Is mapped to this userOrGroupName
Admin	Joe
User	Helen

This role	Is mapped to this userOrGroupName
Admin	Joe
User	Helen
EJBAdmin	Zack