Chapter 11   Packaging for Deployment


This chapter describes the contents of iPlanet Application Server modules and how these modules are packaged separately or together in an application.

For design considerations that affect packaging, see "Modularizing Applications."

iPlanet Application Server modules and applications include J2EE standard elements and iPlanet Application Server specific elements. Only iPlanet Application Server specific elements are described in detail in this chapter.

The following topics are presented in this chapter:

• Overview of Packaging and Deployment

• Assembling Modules and Applications

• Deploying Modules and Applications

• Introducing XML DTDs

• Web Application XML DTD

• EJB XML DTD

• RMI/IIOP Client XML DTD

• Resource XML DTD

Overview of Packaging and Deployment

---

Application assembly (also known as packaging) is the process of combining discrete components of an application into a single unit that can be deployed to a J2EE-compliant application server. A package can be classified either as a module or as a full-fledged application.

Modules

A J2EE module is a collection of one or more J2EE components of the same container type with two deployment descriptors (DDs) of that type. One DD is J2EE standard, the other is iPlanet Application Server specific. Types of J2EE modules are as follows:

• Web Application Archive (WAR): A web application is a collection of servlets, HTML pages, classes, and other resources that can be bundled and deployed to several J2EE application servers. A WAR file can consist of the following items: servlets, JSPs, ulitility classes, static docs, client-side applets, beans, and bean classes, and deployment descriptors (web.xml and ias-web.xml).

• EJB JAR File: The EJB JAR file is the standard format for packaging enterprise beans. This file contains the bean classes (home, remote, and implementation), all of the utility classes, and the deployment descriptors (ejb-jar.xml and ias-ejb-jar.xml).

• RMI/IIOP Client JAR File: An RMI/IIOP Client is an iPlanet Application Server specific type of J2EE client. An RMI/IIOP Client supports the standard J2EE Application Client specifications, and in addition, supports direct access to the iPlanet Application Server. Its deployment descriptors are app-client.xml and ias-app-client.xml.

• Resource JAR File: Examples of resources are JDBC datasources, Java Mail, or JMS. Each iPlanet Application Server resource has a resource XML file.

Package definitions must be used in the source code of all modules so the classloader can properly locate the classes after the modules have been deployed.

Because the information in a DD is declarative, it can be changed without requiring modifications to source code. At run time, the J2EE server reads this information and acts accordingly.

EJB JAR and Web modules can also be packaged as separate .war or .jar files and deployed separately, outside of any application, as in the following figure.

Applications

A J2EE application is a logical collection of one or more J2EE modules tied together by application deployment descriptors. Components can be assembled at either the module or the application level. Components can also be deployed at either the module or the application level.

The following diagram illustrates how components are packaged into modules and then assembled into an iPlanet Application Server application .ear file ready for deployment.

Each module has an iPlanet Application Server DD and a J2EE DD. The iPlanet Application Server Deployment Tool uses the DDs to deploy the application components and to register the resources with the iPlanet Application Server.

An application consists of one or more modules and a J2EE application DD. All items are packaged, using the Java ARchive (.jar) file format, into one file with an extension of .ear.

Naming Standards

EJB JAR and WAR module names identified by the first portion of their filenames (without the .war and .jar extensions) must be unique when deployed to the Application Server. Use a Java package-like naming scheme for module filenames, EAR filenames, and EJB names as found in the <ejb-name> portion of the ejb-jar.xml files. The use of this package-like naming scheme ensures that name collisions do not occur. The benefits of this naming practice apply not only to the iPlanet Application Server, but to other J2EE application servers as well.

Assembling Modules and Applications

---

Assembling (or packaging) modules and applications in iPlanet Application Server conforms to all of the customary J2EE-defined specifications. The only difference is that when you assemble in iPlanet Application Server, you must include iPlanet Application Server-specific deployment descriptors (such as ias-web.xml and ias-ejb-jar.xml) that enhance the functionality of the application server. For example, iPlanet Application Server provides features such as load balancing (distributing tasks equally among servers in a cluster) and failover (assigning tasks to another server of one server fails).

This section covers the following topics:

• Sample Files

• Assembling WAR Modules

• Assembling EJB JAR Applications

• Assembling RMI/IIOP Applications

The iPlanet Application Server provides three methods for packaging a module or an application. These three tools are listed here and described in greater detail under each topic.

• CLI Tool: When you use the Command Line Interface as an assembly tool, you use JAR files and the automated assembly features available through Ant, a Java-based build tool available through Jakarta Apache:

  http://jakarta.apache.org/ant/

• Deployment Tool: You can use the Deployment Tool (DeployTool) provided with iPlanet Application Server, to both assemble and deploy J2EE applications and modules.

• Visual Café Plug-in: The iPlanet's Visual Café Plug-in integrates the WebGain® Visual Café tool with iPlanet Application Server:

  http://www.iplanet.com/products/application_server_plug/home_2_1_1aj.html

  You can use the Visual Café development features to automate the creation of iPlanet Application Server-specific DDs, WAR files, and JAR files.

Sample Files

Before assembling the sample J2EE application, you must compile the following Java sources:

• Servlet (GreeterServlet.java)

• EJBs (GreeterHome.java, GreeterEJB.java, Greeter.java)

• JSP (GreeterView.jsp)

• Static file (HWSample)

All of these files are located here:

http://developer.iplanet.com/docs/articles/packaging/packaging_print.jsp

The compilation process can be automated using the Ant tool. See the Compile section for the relevant coding information:

http://developer.iplanet.com/docs/articles/packaging/AntCompile.html

See the Ant XML file for the entire Ant build file:

http://developer.iplanet.com/docs/articles/packaging/Ant.xml

Assembling WAR Modules

This section describes procedures for assembling WAR modules in three different ways:

• Using the Command Line Interface (CLI)

• Using the Deployment Tool

• Using the Visual Café Plug-in

Using the Command Line Interface (CLI)

To create a WAR module using the CLI, follow these steps:

1. Create a working directory: working_dir/cli.

2. Create two deployment descriptors with these names: web.xml and ias-web.xml. Examples are here:

   http://developer.iplanet.com/docs/articles/packaging/web.xml

   http://developer.iplanet.com/docs/articles/packaging/ias-web.xml

   
   

   ---

   Tip	The first time, you can create the deployment descriptors using the deployment tool. The resulting WAR file can be extracted to yield the deployment descriptors.

   ---

   
   

3. Move the contents of the WAR file to the directory that you created in step 1. For more information, see:

   http://developer.iplanet.com/docs/articles/packaging/war.html

4. Go to this directory: working_dir/cli/assemble/war.

5. Execute this command:

   jar -cvf helloworldWar.war *

   This creates the WAR file helloworldWar.war.

   
   

   ---

   Tip	The CLI assembly process can be automated using the Ant tool. To learn more, see the following URL.

   ---

   
   

   http://developer.iplanet.com/docs/articles/packaging/AntCompile.html

Using the Deployment Tool

To assemble a WAR module using the iPlanet Deployment Tool, follow these steps:

1. Use the deployment tool to create a new WAR file called helloworld.war in this directory: working_dir/deploytool.

   
   
   

2. Use the Deployment Tool Wizard to insert these web files: GreeterView.jsp, index.html, GreeterServlet.class

   
   
   

3. Resolve the files by clicking on the Resolve button in the lower right portion of the screen.

4. Click Finish. This creates the war file working_dir/deploytool/helloworldWar.war.

   The descriptors (both web.xml and ias-web.xml) have been created by the Deployment Tool.

5. You can now view you WAR module using either the file view:

   
   
   

   or the component view:

   
   
   

   
   

   ---

   Tip	iPlanet recommends that you use the Deployment Tool to build the first cycle of packaging even when you are using the CLI method of assembly.

   ---

   
   

Using the Visual Café Plug-in

To assemble a WAR module using the iPlanet Visual Café Plug-in, follow these steps:

1. Download and install the Visual Café Plug-in for iPlanet Application Server:

   http://www.iplanet.com/products/application_server_plug/home_2_1_1aj.html

2. Create a new iPlanet Application Server Web Application at working_dir/visualcafe.

   
   
   

   Name this file helloworld.vep.

   
   
   

3. Insert these web files into the application: GreeterServlet.java, GreeterView.jsp, index.html.

   
   
   

4. Add any required helper classes.

5. Compile the source (GreeterServlet.java) and deploy the application. The deployment descriptors are created when the module is deployed.

   
   

   ---

   Note	For more information about the Visual Café Plug-in for iPlanet Application Server, see the documentation included in the plug-in download.

   ---

   
   

Assembling EJB JAR Applications

This section describes procedures for assembling EJB JAR modules in two different ways:

• Using the Command Line Interface (CLI)

• Using the Deployment Tool

Using the Command Line Interface (CLI)

To create a J2EE application using the CLI, follow these steps:

1. Create a working directory with this name: working_dir/cli.

2. Create the deployment descriptor application.xml. An example is here:

   http://developer.iplanet.com/docs/articles/packaging/application.xml

3. Move the deployment descriptor, the WAR file, and the EJB JAR file to the directory that you created in step 1. A list is here:

   http://developer.iplanet.com/docs/articles/packaging/app.html

4. Go to your working directory.

5. Execute this command:

   jar -cvf helloworld.ear *

   This command creates the J2EE application helloworld.ear.

Using the Deployment Tool

To assemble a J2EE application using the iPlanet Deployment Tool, follow these steps:

1. Use the deployment tool to create a new EAR file called helloworld.ear in this directory: working_dir/deploytool.

   
   
   

2. Use the Deployment Tool Wizard to insert the EJB JAR file helloworldEJB.jar and the WAR file helloworldWAR.war.

   
   
   

3. Resolve the files by clicking on the Resolve button in the lower right portion of the screen.

4. Remove the path up to the root of the application and click the Update button.

5. Click Finish. This creates the EAR file working_dir/deploytool/helloworld.ear. The deployment descriptor (application.xml) has already been created.

6. You can now view your application using the EAR file view:

   
   
   

   or the EAR component view:

   
   
   

7. Verify your work using the Verify selection from the File menu.

   
   

   ---

   Tip	iPlanet recommends that you use the Deployment Tool for the first cycle of packaging even when you are using the CLI method of assembly.

   ---

   
   

Assembling RMI/IIOP Applications

This section provides some brief pointers for assembling RMI/IIOP applications, but you should first read Chapter 10 "Developing and Deploying CORBA-Based Clients."

For an example demonstrating the packaging and deployment of a simple RMII/IIOP application, see:

http://developer.iplanet.com/appserver/samples/pkging/docs/sampleD.html

RMI/IIOP applications can be divided into two types:

• Simple Clients: These clients do not have the container services provided by iasacc.jar and they do not have an application xml.

• Application Client Containers: These are J2EE 1.2-compliant clients that include a deployment descriptor and have access to additional services.

In the iPlanet Application Server, you should keep the following points in mind while packaging an RMI/IIOP application:

On the Server Side:

• Configure CXS (Corba eXecutive Service) from the iPlanet Application Server Administration Tool.

• Use the Deployment Tool to generate the RMI/IIOP stubs and skeletons.

On the Client Side:

• Include the required JAR files (iasclient.jar, javax.jar, jms.jar, mail.jar, and servlet.jar) in the client class path.

• Include the client-side stubs for the EJB. These are provided by the Deployment Tool. Include iasacc.jar (ACCs only).

• Include application-client.xml (ACCs only).

  
  

  ---

  Tip	All files referred to here can be found in iasclient.tar (on Unix) or iasclient.zip (on NT).

  ---

  
  

Deploying Modules and Applications

---

This section describes the different ways to deploy J2EE applications and modules to the iPlanet Application Server. It covers the following topics:

• Deployment by Module

• Deployment by Application

• Deploying RMI/IIOP Clients

• Deploying Static Content

• Tools for Deployment

• General Rules About Deployment

Deployment by Module

Individual modules can be deployed independently of applications. Module-based registration and deployment is preferable when shared components need to be accessed by:

• Other modules

• J2EE Applications

• RMI/IIOP clients (Module-based registration allows shared access to a bean from an RMI/IIOP client, a servlet, or an EJB.)

To register a module, you execute this command:

iasdeploy deploymodule module_name

Modules can be combined into an EAR file and then deployed as a single module using the same command. This is similar to deploying the modules of the EAR independently. The runtime registry and file system implications of module-based registration are described in Appendix B "Runtime Considerations."

For alternative ways to deploy a module, see "Tools for Deployment."

Deployment by Application

To register a J2EE application, you execute this command:

iasdeploy deployapp app_name

The runtime registry and file system implications of module-based registration are described in Appendix B "Runtime Considerations."

For alternative ways to deploy an application, see "Tools for Deployment."

Deploying RMI/IIOP Clients

Deploying an RMI/IIOP client is a two-step process:

1. Install the EJB JAR that needs to be accessed by the RMI/IIOP client.

2. Package the necessary client files (as described in "Assembling RMI/IIOP Applications"), create the client code, and then execute the client from the client machine.

Deploying Static Content

Static content (HTML, images, etc) can be hosted both on the web server and on the iPlanet Application Server. However, when a WAR is registered, the static content gets deployed on the application server. All of the packaging samples shipped with iPlanet Application Server host the static content on the application server.

For example, to access a static file index.html on the application server, use:

http://server:port/NASApp/&ltcontext_root/index.html

Tools for Deployment

This section discusses the various tools that can be used to deploy modules and applications. The deployment tools include:

• The iasdeploy Command

• The iPlanet Deployment Tool

• The iPlanet Visual Café Plug-in

The iasdeploy Command

The iasdeploy command is a CLI tool that you can use to register and deploy both modules and applications on local servers. To deploy a module, use this command:

iasdeploy deploymodule module_name

To deploy an application, use this command:

iasdeploy deployapp app_name

The iPlanet Deployment Tool

The iPlanet Deployment Tool can be used to deploy modules and applications to both local and remote iPlanet Application Server sites. To use this tool, follow these steps:

1. Open the WAR, JAR, or EAR file that needs to be deployed. Any one of these can be deployed independently.

2. Select Deploy from the File menu.

3. Click the Register button.

4. Register the deployment targets.

5. Highlight the appropriate server, and click the Deploy button.

The iPlanet Visual Café Plug-in

The iPlanet plug-in to the Visual Café allows you to deploy in an Integrated Development Environment (IDE) context. Using this tool, assembly and deployment occur together. For details, see the documentation that is provided when you download the plug-in.

General Rules About Deployment

There are a few general rules that you should keep in mind when deploying modules and applications. These are described here.

Redeploying an Application or Module

When an application or module is redeployed, some file system content and some Application Server registry settings are not overwritten or removed. This can lead to older settings remaining in effect after a redeployment. To perform a clean redeployment, remove the application or module before redeploying it.

Deploying to an iPlanet Application Server Cluster

When an application is deployed to a cluster of iPlanet Application Server servers, it needs to be registered on each server individually. Although the shared information is stored on LDAP, which is accessed by all the servers in a cluster, the file system entries must reside on every server.

Access to Shared Frameworks

When J2EE applications and modules use shared framework classes (such as components and libraries) the classes can be put in the System Classpath rather than in an application or module. If you package a large, shared library into every module that uses it, the result is a huge file that takes too long to register with the server. In addition, several versions of the same class could exist in different classloaders, which is a waste of resources.

For more information about the system classloader, see Appendix B "Runtime Considerations."

The Cocoon example (part of the XML samples) that ships with iPlanet Application Server is a good example of the use of frameworks.

Introducing XML DTDs

---

The Document Type Definition (DTD) defines the XML grammar of a Deployment Descriptor (DD). There are two DD levels: application level descriptors and component level descriptors.

The iPlanet Application Server requires DDs to run an application. The DDs are XML files containing metadata describing the deployment information about the J2EE modules (such as servlets, JSPs, and EJBs) that make up an application. The information in each XML file is stored in an iPlanet Application Server internal registry.

Each application module must have a J2EE DD file. Additionally, each application component must be associated with a Globally Unique IDentifier, or a GUID.

The following lists the DD types supported by the iPlanet Application Server:

• application DD

• web application DD and an iPlanet Application Server web application DD

• EJB DD and an iPlanet Application Server EJB DD

• application client DD and an iPlanet Application Server RMI/IIOP client DD

• iPlanet Application Server resource DD

J2EE Standard Descriptors

The J2EE platform provides packaging and deployment facilities. These facilities use JAR files as the standard package for components and applications, and XML-based DDs for customizing parameters. For more information on the J2EE packaging and deployment process, see Developing Enterprise Applications with the J2EE, v 1.0, Chapter 7.

The J2EE standard DDs are described in the J2EE specification, v1.1. For more information on these standard DDs, see the following specifications:

• Java 2 Platform Enterprise Edition Specification, v1.2, Chapter 8, "Application Assembly and Deployment - J2EE:application XML DTD"

• Java 2 Platform Enterprise Edition Specification, v1.2, Chapter 9, "Application Clients - J2EE:application-client XML DTD"

• JavaServer Pages Specification, v1.1, Chapter 7, "JSP Pages as XML Documents"

• JavaServer Pages Specification, v1.1, Chapter 5, "Tag Extensions"

• Java Servlet Specification, v2.2 Chapter 13, "Deployment Descriptor"

• Enterprise JavaBeans Specification, v1.1, Chapter 16, "Deployment Descriptor"

Creating Deployment Descriptors

All DDs for an iPlanet Application Server application are created using the Deployment Tool. For more information on these procedures, see the Deployment Tool Online Help.

Document Type Definition

The DTD describes the DD files structure and class properties. Each DD has exactly one element that completely contains all other elements (or subelements).

The element descriptions found in XML files are presented in a table format. These element tables have several fields to describe the element's purpose and setting parameters. Some elements are hierarchical, meaning the parameters have other elements (or subelements). If a parameter contains an element, the element description is found in another table describing the element. Table 11-1 shows the supported DTD entries.

Table 11-1    Document Type Definition  

Type	Description
Element	Element name as it appears in the XML file and an element description.
Sub Elements	Lists the elements contained by this element.

The iPlanet Application Server Registry

The iPlanet Application Server registry is a collection of application metadata, organized in a tree, that is continually available in active memory or on a readily accessible directory server. The process by which the iPlanet Application Server gains access to servlets, EJBs, and other application resources is called registration, because it involves placing entries in the iPlanet Application Server registry for each item.

You can change some information in the registry at runtime using the iPlanet Application Server Administrator Tool. For more information about the registry and the Administrator Tool, see the iPlanet Application Server Deployment Tool Help and the Administrator's Guide.

A Globally Unique Identifier

A GUID is a 128-bit hexadecimal number assigned to EJBs, servlets, and optionally to JSPs. They are automatically generated by the Deployment Tool.

GUIDs are guaranteed to be globally unique, which makes them ideal for identifying components in a large scale heterogeneous system such as an iPlanet Application Server application.

GUIDs are normally assigned automatically by the Deployment Tool. You can manually generate a GUID by using a utility named kguidgen. kguidgen is installed by default into the directory BasePath/bin. That directory must be listed in your search path (your PATH environment variable in order to generate a GUID).

To generate a new GUID, simply run kguidgen from a command line or window.

Web Application XML DTD

---

This section describes a web application, the web application module and the web application DD. DDs are created using the Deployment Tool. For more information, see the iPlanet Application Server Deployment Tool Help and the Administrator's Guide.

Web Application Overview

Web applications run on web servers and may consist of servlets, JSPs, JSP Tag libraries, HTML pages, classes and other resources. A web application's location is rooted at a specific path within the web server. A web application's instance must only be run on one Virtual Machine (VM) at any given time, unless the application is marked as distributable by its DD. When marked as distributable, the application may run on more than one VM at any given time and must follow a more restrictive rule set outlined by the Java Servlet 2.2 specification.

A web application is a composite of the following items:

• Servlets

• JSPs

• Utility Classes

• Static documents (HTML, images, sounds, and so on)

• Client side applets, beans and classes

• Descriptive meta information bundling the above items together

A web application is created by first assembling all needed web components into a web application module along with its module DD. Next, the web application module is packaged with all other modules that are used by the J2EE application along with the application DD into the final web application that is ready for deployment. For more information on J2EE assembly and deployment, see the J2EE specification, Chapter 8.

Web Application XML DTD

This section provides the XML DTD for the iPlanet Application Server specific web application DD. For more information on the standard J2EE application DD, see the J2EE specification, section 8.4.

The web application DD supports element definitions that provide the following information:

• servlet information

• session information

• EJB reference information

• Resource reference information

• Specifying servlet information

Element for Specifying an iPlanet Application Server Web Application

Table 11-2 shows the <ias-web-app> element and sub elements used with the iPlanet Application Server web application DD root element.

Table 11-2    <ias-web-app> Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
servlet	zero or more	elements	none	Contains the servlet configuration information.
session-info	zero or one	elements	none	Specifies the session information.
ejb-ref	zero or more	elements	none	Specifies the absolute JNDI name storage location of the corresponding J2EE XML ejb-ref entry.
resource-ref	zero or more	elements	none	Specifies the absolute JNDI name storage location of the ejb-link in the corresponding J2EE XML file ejb-ref entry.
nlsinfo	zero or one	elements	none	NLS settings descriptor.
role-mapping	zero or many	elements	none	LDAP role mapping descriptor.

Elements for Specifying Servlet Configuration Information
Table 11-3 shows the servlet sub element contains configuration information about a servlet.

Table 11-3    servlet Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
servlet-name	one and only one	string	none	The servlet name. This name must match the servlet-name parameter in the J2EE web app XML exactly.
guid	one and only one	string	none	A string representing the guid for the servlet.
servlet-info	zero or one	elements	none	Optional servlet characteristics.
validationRequired	zero or one	boolean	"false"	Specifies if the input parameter needs to be validated.
error-handler	zero or one	string	none	Describes the servlet error handler.
parameters	zero to more	elements	none	Describes all input parameters to be validated.
param-group	zero to more	elements	none	Each parameter group is represented by an event source name and the associated parameters.

Elements for Specifying Servlet Characteristics
Table 11-4 shows the servlet-info sub element which is used to describe the optional characteristics about a servlet.

Table 11-4    servlet-info Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
sticky	zero or one	boolean	"false"	If sticky is "true", the servlet exhibits session affinity and is only load-balanced if no session exists. Once a session is created in a given engine, subsequent requests for sticky servlets continues to be routed to the same engine.
encrypt	zero or one	boolean	"false"	Optional flag indicating whether communications to the servlet are encrypted ("true") or not ("false").
caching	zero or one	elements	none	Specifies caching criteria for the servlet.
number-of-singles	zero or one	integer	10	The number of objects in the servlet pool when SingleThread mode is used.
disable-reload	zero or one	boolean	false	This is used to disable reloading of servlets when dirty. Legal values are true or false.
server-info	zero or many	elements	none	Optional server information including server and load balancing enabling and/or disabling.
server-ip	one and only one	string	none	Server IP address.
server-port	one and only one	string	none	Executive Server's port number.
sticky-lb	zero or many	boolean	servlet-info sticky setting	Sets sticky load balancing. Legal values are true or false. If set overrides the setting of the servlet-info.
enable	zero or many	boolean	true	Specifies if the server is enabled or not. Legal values are true or false.

Elements for Specifying Servlet Validation
Table 11-5 shows the validation-required sub element which is used to verify the input about a servlet should be validated.

Table 11-5    validation-required Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
validation-required	one and only one	boolean	false	Specifies whether or not the input parameters should be verified.

Elements for Specifying Servlet Caching
Table 11-6 shows the caching sub element, which is used to describe caching criteria for the servlet. caching is disabled by not defining the caching element.

Table 11-6    caching Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
cache-timeout	one and only one	integer	none	Sets the servlet caching timeout (in seconds). If the value is 0, caching is disabled.
cache-size	one and only one	integer	none	Sets the cache size. A value of "0" disables caching.
cache-criteria	one and only one	string where the syntax is any value of arg in the input parameter list; for details, see "Caching Servlet Results."	none	Criteria expression containing a string of comma delimited descriptors, each descriptor defining a match with one of the input parameters to the servlet.
cache-option	one and only one	String of either TIMEOUT_CREATE or TIMEOUT_LASTACCESS	TIMEOUT_ LASTACCESS	Sets the cache timeout option.

Examples for Setting Cache Criteria and Cache Option
The following examples provide some common usages and cache criteria element settings.

Example 1
<cache-criteria>EmployeeCode</cache-criteria>

This means caching is enabled if EmployeeCode is in the input parameter list.

Example 2
<cache-criteria>stock=NSCP</cache-criteria>

This means caching is enabled if the stock input parameter value is NSCP

Example 3
<cache-criteria>*</cache-criteria>

This means caching is enabled whenever the input parameter values are the same as the cached value.

Example 4
<cache-criteria>dept=sales|marketing|support</cache-criteria>

This means caching is enabled if the dept parameter value is sales, marketing, or support.

Example 5
<cache-criteria>salary=40000-60000</cache-criteria>

This means caching is enabled when the input parameter value of salary is between 40000 and 60000.

Example 6
<cache-option>TIMEOUT_CREATE</cache-option>

This means it takes the cache timeout value from the creation time.

Example 7
<cache-option>TIMEOUT_LASTACCESS</cache-option>

This means it takes the cache timeout based on the last accessed time.

Elements for Specifying Servlet Parameters
Table 11-7 shows the parameters element which is used to describe the input parameters to be validated.

Table 11-7     parameters Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
param	zero or more	elements	none	Specifies each parameter by name and the rules applied to it for validation.

Elements for Specifying Servlet Sub Parameters
Table 11-8 shows the param sub elements where each parameter is represented by a name and the rules that are applied to it for validation.

Table 11-8     param Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
param-name	one and only one	string	none	Input parameter name.
input-fields	one and only one	elements	none	This describes the input parameter details.

Elements for Specifying Servlet Input Field
Table 11-9 shows the input-field sub elements which is used to detail the input parameter.

Table 11-9    input-field Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
input-required	zero or one	boolean	none	Specifies whether the input parameter is required to exist, that is, whether the field should be part of the input list.
input-rule	zero or one	string	none	Specifies the input rule being applied for validation on the input parameter.
format	zero to one	string in date/time format	none	Specifies the format for date/time to be applied for validation on the input parameter.
in-session	zero to one	string	none	Specifies if the parameter is in cache (session) for validation.
param-error-handler	zero or one	string	none	Specifies the parameter error handler.

Elements for Specifying Servlet Parameter Groups
Table 11-10 shows the param-group sub elements where each parameter group is represented by an event source name and the associated parameters.

Table 11-10    param-group Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
param-group-name	one and only one	string	none	Parameter group name.
param-input	one or more	string	none	Parameter input name associated with the parameter group.

Elements for Specifying Session Information
Table 11-11 shows the session-info elements which is used to specifies session information.

Table 11-11    session-info Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
impl	one and only one	string of either distributed or lite	none	A session can either be a distributed, fault-tolerant session or a lightweight local session only.
timeout-type	zero or one	string of either last-access or creation	last- access	Session timeouts are normally measured in "time since last access." Alternatively, an absolute timeout can be specified as "time since session creation."
timeout	zero or one	positive integer representing minutes	30 minutes	Number of session timeout minutes before a timeout. If unspecified, a system wide default session timeout is used. This value and the <session-timeout> value in web.xml are stored in the same place internally. Changing either value changes the other value as well.
secure	zero or one	boolean	false	Specifies the session can only be visible to a secure (HTTPS) server.
domain	zero or one	string name of the domain that set the cookie	none	Specifies the application domain used to set the session domain cookie. The domain string argument must contain at least 2 or 3 periods (3 period-domains apply to domains like acme.co.uk). If the domain is set to acme.com, then the session is visible to Who.acme.com, bar.asme.com, and so on.
path	zero or one	String value of the URL for the session cookie starting with "/".	The URL that created the cookie.	Specifies the session cookie path. A non-existent path implies the same path as the one set in the cookie is used. For example, the path /phoenix matches /phoenix/types/bird.html and /phoenix/birds.html.
scope	zero or one	String identifying the other application.	none	Grouping name that selects what other applications can access the session. For example, if the domain is set to acme.com, then the session is visible to Who.acme.com, bar.acme.com, and so on.
dsync-type	zero or one	string of either dsync-local or dsync- distributed	none	Specifies the DSync session type.

Elements for Specifying EJB Reference Information
Table 11-12 shows the ejb-ref sub elements which are the absolute jndi-name storage place for the ejb-link in the corresponding J2EE XML file ejb-ref entry.

Table 11-12    ejb-ref Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
ejb-ref-name	one and only one	string	none	The ejb-link in the corresponding J2EE XML file ejb-ref entry.
jndi-name	one and only one	string	none	The absolute jndi-name.

Elements for Specifying Resource Reference Information
Table 11-13 shows the resource-ref sub elements which are the absolute jndi-name storage place for the resource-ref in the corresponding J2EE XML file resource-ref entry.

Table 11-13    resource-ref Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
resource-ref-name	one and only one	string	none	The resource-ref name in the corresponding J2EE XML file resource-ref entry.
jndi-name	one and only one	string	none	The absolute jndi-name.

Elements for Specifying NLS Settings
Table 11-14 shows the nlsinfo sub elements which contains the configuration information about the application's NLS settings.

Table 11-14    nlsinfo Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
locale-charset-map	zero or many	elements	none	Contains locale and the corresponding character set.
default-locale	one and only one	string	none	Default locale.

Elements for Specifying Locale Character Sets
Table 11-15 shows the locale-charset-map sub elements which contains the descriptor information for locale and corresponding character sets.

Table 11-15    locale-charset-map Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
locale	one and only one	string	none	Locale name.
charset	one and only one	string	none	Default locale.

Elements for Specifying Role Mapping
Table 11-16 shows the role-mapping sub elements which contains the descriptor information for mapping roles to LDAP user, groups, and so on.

Table 11-16    role-mapping Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
role-name	one and only one	string	none	Role name as referred to in the <security-role> element.
role-impl	one and only one	elements	none	The string used to represent a LDAP group/user which makes up a particular role-name. A role-impl could be any number of groups and/or users.

Elements for Specifying Role IMPL
Table 11-17 shows the role-impl sub elements which contains the descriptor information for role implementation.

Table 11-17    role-impl Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
group	zero or many	string	none	LDAP specific string that corresponds to a particular LDAP group.
user	zero or many	string	none	LDAP specific string that corresponds to a particular LDAP user.

EJB XML DTD

---

This section describes the EJB DTD used by the EJB deployment descriptors. The DDs are created using the Deployment Tool. For more information on creating DDs, see the Deployment Tool Online Help.

EJB JAR File Contents

The standard format used to package enterprise beans is the EJB-JAR file. The format is the contract between the bean provider and application assembler, and between the application assembler and the deployer.

The EJB-JAR file must contain the DD as well as all class files for the following:

• The enterprise bean class.

• The enterprise helper classes.

• The enterprise bean home and remote interfaces.

• If the bean is an entity bean, the primary key class.

In addition, the EJB-JAR file must contain the class files for all classes and interfaces that the enterprise bean class, and the remote home interfaces depend on.

Specifying Parameter Passing Rules

When a servlet or EJB calls another bean that is co-located within the same process, the iPlanet Application Server does not perform marshalling of all call parameters by default. This optimization allows the co-located case to execute far more efficiently than if strict by-value semantics are used. In certain cases, you may want to ensure that parameters passed to a bean are always passed by value. The iPlanet Application Server supports the marking of a bean or even a particular method within a bean as requiring pass-by-value semantics. The parameter passing method used by the EJB is defined by the pass-by-value element. For more information, see the pass-by-value element description in the session (Table 11-20) or entity element (Table 11-21). Because this option decreases performance by greatly increasing call overhead, the default value is false.

EJB iPlanet Application Server XML DTD

The following is the iPlanet Application Server specific XML DTD for EJB-JAR files.

Elements for Specifying EJB-JAR

Table 11-18 shows the ias-ejb-jar element which is the iPlanet Application Server web application DD root element.

Table 11-18    ias-ejb-jar Element  

Sub Element	Repeat Rule	Contains	Default	Description
enterprise-beans	one and only one	element	none	The enterprise-beans element contains declarations for one or more enterprise beans.

Elements for Specifying Enterprise Beans

Table 11-19 shows the enterprise-beans sub element which contains declarations for one or more enterprise beans.

Table 11-19    enterprise-beans Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
session	one or the other	element	none	An element that declares all iPlanet Application Server specific session bean related deployment information
entity	one or the other	element	none	An element that declares all iPlanet Application Server specific entity bean related deployment information

Elements for Specifying Session
Table 11-20 shows the session sub element which declares all iPlanet Application Server specific session bean related deployment information. The ejb-name must match 1 to 1 with the ejb-name declared in the J2EE XML file.

Table 11-20    session Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
ejb-name	one and only one	string	none	The EJB name.
guid	one and only one	string	none	The EJB guid in question.
pass-timeout	one and only one	positive integer	none	Passivation timeout in seconds used by the container. This value can be changed during runtime by the Administration Tool.
pass-by-value	one and only one	boolean	none	If "true", marshalling of all call parameters to the EJB are performed. If "false" and the beans are co-located, strict by-value semantics are not guaranteed.
session-timeout	one and only one	positive integer	none	The session timeout in minutes.
ejb-ref	zero or more	elements	none	The absolute jndi-name storage place for the ejb-link in the corresponding J2EE XML file ejb-ref entry.
resource-ref	zero or more	elements	none	The absolute jndi-name storage place for the resource-ref in the corresponding J2EE XML file resource-ref entry.
failoverrequired	zero or one	boolean	none	Indicates if failover is required.

Elements for Specifying Entity
Table 11-21 shows the entity sub element which declares all iPlanet Application Server specific entity bean related deployment information. The ejb-name must match 1 to 1 with the ejb-name declared in the J2EE XML file.

Table 11-21    entity Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
ejb-name	one and only one	string	none	The EJB name.
guid	one and only one	string	none	The EJB guid in question.
pass-timeout	one and only one	positive integer	none	Passivation timeout in seconds used by the container. This value can be changed during runtime by the Administration Tool.
pass-by-value	one and only one	boolean	none	If "true", marshalling of all call parameters to the EJB are performed. If "false" and the beans are co-located, strict by-value semantics are not guaranteed.
persistence-manager	zero or one	elements	none	Specifies persistence information.
pool-manager	zero or one	elements	none	Descriptor for cache pool attributes.
ejb-ref	zero or more	elements	none	The absolute jndi-name storage place for the ejb-link in the corresponding J2EE XML file ejb-ref entry.
resource-ref	zero or more	elements	none	The absolute jndi-name storage place for the resource-ref in the corresponding J2EE XML file resource-ref entry.
failover-required	zero or one	boolean	false	Indicates if failover is required.
iiop	zero or one	boolean	false	Indicates if a bean is RMI/IIOP Client enabled.
role-mapping	zero or many	elements	none	Descriptor that creates role mapping.

Elements for Specifying Persistence Manager

Table 11-22 shows the persistence-manager sub element which defines all persistence manager specific information.

Table 11-22    persistence-manager Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
factory-class-name	one and only one	string	none	Persistence manager name factory class.
properties-file-location	one and only one	string	none	Properties file location in a JAR file.

Elements for Specifying Pool Manager

Table 11-23 shows the pool-manager sub element which defines all pool manager specific information.

Table 11-23    pool-manager Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
commit-option	one and only one	string value of COMMIT_OPTION_C	COMMIT_ OPTION_C	Option C: Between transactions the Container does not cache a "ready" instance. For more information, see the EJB v1.1 specification, section 9.1.10.
ready-pool-timeout	one and only one	positive integer	infinite	Ready pool timeout used by the container. This value can be changed during runtime by the Administration Tool.
ready-pool-maxsize	one and only one	positive integer or "0" for infinite	infinite	Maximum size of the ready cache in entry numbers. This value can be changed during runtime by the Administration Tool.
free-pool-maxsize	one and only one	positive integer or "0" for infinite	infinite	Maximum size of the instance free pool in entry numbers. This value can be changed during runtime by the Administration Tool.

Elements for Specifying EJB Reference

Table 11-24 shows the ejb-ref sub element which are the absolute jndi-name storage places for the ejb-link in the corresponding J2EE XML file ejb-ref entry.

Table 11-24    ejb-ref Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
ejb-ref-name	one and only one	string	none	The ejb-link in the corresponding J2EE XML file ejb-ref entry.
jndi-name	one and only one	string	none	The absolute jndi-name.

Elements for Specifying Resource Reference

Table 11-25 shows the resource-ref sub element which are the absolute jndi-name storage places for the resource-ref in the corresponding J2EE XML file resource-ref entry.

Table 11-25    resource-ref Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
resource-ref-name	one and only one	string	none	The resource-ref name in the corresponding J2EE XML file resource-ref entry.
jndi-name	one and only one	string	none	The absolute jndi-name.

Elements for Specifying Role Mapping

Table 11-26 shows the role-mapping sub elements which are the mapping roles descriptors for the LDAP user, groups, and so on.

Table 11-26    role-mapping Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
role-name	one and only one	string	none	Role name as referred to in the <security-role> element.
role-impl	one and only one	elements	none	The string used to represent a LDAP group/user thing that makes up a particular role-name. A role-impl could be any number of groups and/or users.

Elements for Specifying Role Implementation

Table 11-27 shows the role-impl sub elements which are the role implementation descriptors.

Table 11-27    role-impl Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
group	zero or many	string	none	LDAP specific string for a particular LDAP group.
user	zero or many	string	none	LDAP specific string for a particular LDAP user.

RMI/IIOP Client XML DTD

---

The RMI/IIOP Client is an iPlanet Application Server specific type of J2EE client. A RMI/IIOP Client supports the standard J2EE Application Client specifications, and in addition, supports direct access to the iPlanet Application Server. For more information on RMI/IIOP Clients, refer to Chapter 10 "Developing and Deploying CORBA-Based Clients."

A RMI/IIOP Client JAR file contains two DDs that are generated by the Deployment Tool. One DD is specified by the J2EE application client XML DTD, that can be found in the J2EE Specification, v1.0 Chapter 9 Application Clients. The other DD contains the iPlanet Application Server specific RMI/IIOP Client elements; for more information, see "iPlanet Application Server RMI/IIOP Client XML DTD."

For a sample RMI/IIOP Client DD file, see "RMI/IIOP Client DD XML Files."

iPlanet Application Server RMI/IIOP Client XML DTD

The ias-java-client-jar element is the RMI/IIOP Client's DD root element.

Elements for Specifying EJB Reference Information

Table 11-28 shows the ejb-ref sub elements which are the absolute jndi-name storage places for the ejb-link in the corresponding J2EE XML file ejb-ref entry.

Table 11-28    ejb-ref Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
ejb-ref-name	one and only one	string	none	The ejb-link in the corresponding J2EE XML file ejb-ref entry.
jndi-name	one and only one	string	none	The absolute jndi-name.

Elements for Specifying Resource Reference Information

Table 11-29 shows the resource-ref sub elements which are the absolute jndi-name storage places for the resource-ref in the corresponding J2EE XML file resource-ref entry.

Table 11-29    resource-ref Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
resource-ref-name	one and only one	string	none	The resource-ref name in the corresponding J2EE XML file resource-ref entry.
jndi-name	one and only one	string	none	The absolute jndi-name.

Resource XML DTD

---

Each iPlanet Application Server resource has a resource XML file. Examples of resources are JDBC datasources, Java Mail, or JMS. The XML file contains entries that are used to register the resource with the iPlanet Application Server. These entries define the way the iPlanet Application Server connects to the resource. These files are generated by the Deployment Tool. This section describes the resource XML file entries. For information on how to generate these files, see the Deployment Tool Online Help.

Datasource XML DTD

This section describes the XML DTD for the iPlanet Application Server datasource.

Element for Specifying Datasources

Table 11-30 shows the ias-Datasource-jar sub element which is the resource DD root element.

Table 11-30    ias-Datasource-jar Sub Element  

Sub Element	Repeat Rule	Contains	Default	Description
ias-resource	one and only one	element	none	Common element for all resource DDs.

Element for Specifying iPlanet Application Server Resources

Table 11-31 shows the ias-resource sub element which is the descriptor used for all resources.

Table 11-31    ias-resource Sub Element  

Sub Element	Repeat Rule	Contains	Default	Description
resource	one and only one	elements	none	Common element for all resource DDs.

Elements for Specifying Resources

Table 11-32 shows the resource sub elements which are the descriptors used for all resources.

Table 11-32    resource Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
jndi-name	one and only one	string	none	The absolute jndi-name of the resource factory (for example, jdb/Who).
jdbc	one or the other	elements	none	Descriptor for the JDBC datasource.
jms	one or the other	string	none	Descriptor for the JMS datasource.
mail	one or the other	string	none	Descriptor for the mail datasource.
url	one or the other	string	none	Descriptor for the URL datasource.

Elements for Specifying JDBC Datasources

Table 11-33 shows the jdbc sub elements which are the descriptors used for the JDBC datasource.

Table 11-33    jdbc Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
database	one and only one	string	none	Database name to connect to.
datasource	one and only one	string	none	Assigned datasource name.
username	one and only one	string	none	Valid database user name.
password	one and only one	string	none	Valid user name password.
driver-type	one and only one	string field which contains one of the following: ORACLE_OCI (Oracle) DB2_CLI (DB2) INFORMIX_CLI (Informix) SYBASE_CTLIB (Sybase) ODBC (ODBC)	none	EIS specific JDBC driver.
resource-mgr	zero or one	string	none	If this attribute is set, the datasource is available for distributed transactions through the resource manager listed. If this attribute is not specified, the datasource is only valid for a local database. The value must be a name you create for a resource manager under the RESOURCEMGR key.

RMI/IIOP Client Datasource XML DTD

This section describes the XML DTD for an RMI/IIOP Client datasource.

Elements for Specifying Java Client Resources

Table 11-34 shows the ias-javaclient-resource sub elements which are the RMI/IIOP Client's datasource XML DD root elements.

Table 11-34    ias-javaclient-resource Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
jdbc	one or the other	elements	none	Descriptor for RMI/IIOP Client JDBC settings.
jms	one or the other	string	none	Not yet defined.
jndi-name	one and only one	string	none	The absolute jndi-name.

Elements for Specifying JDBC Settings

Table 11-35 shows the jdbc sub elements which are the JDBC settings descriptors.

Table 11-35    jdbc Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
driverClass	one and only one	elements	none	Valid driver class.
connectUr1	one and only one	string	none	Valid URL to connect to.
userName	one and only one	string	none	Valid user name.
password	one and only one	string	none	Valid user name password.