Chapter 10   Deployment Packaging


This chapter describes the iPlanet Application Server modules content and how they are packaged to create an iPlanet Application Server application .ear file used for application deployment. The iPlanet Application Server modules include J2EE standard elements and iPlanet Application Server specific elements. Only iPlanet Application Server specific information is detailed in this chapter. Through out this chapter for J2EE specific information, you will find a reference to the appropriate J2EE specification.

The following topics are presented in this chapter:

• Overview of Packaging and Deployment

• Introducing XML DTDs

• Application XML DTD

• Web Application XML DTD

• EJB XML DTD

• RMI/IIOP Client XML DTD

• Resource XML DTD

Overview of Packaging and Deployment

---

An iPlanet Application Server application is comprised of one or more iPlanet Application Server application modules, an iPlanet Application Server Deployment Descriptor (DD) and a J2EE application DD.

All items are packaged, using the Java ARchive (.jar) file format, into one file with an extension of .ear. Package definitions must be used in the source code so the class loader can properly locate the classes.

The DDs are used by the iPlanet Application Server Deployment Tool to deploy the application components and to register the resources with the iPlanet Application Server.

Each application module consists of either an EJB, web application, RMI/IIOP application, or resource components, as well as an iPlanet Application Server DD, and a J2EE DD. For example, an EJB module would have one or more EJB components, an EJB DD and an iPlanet Application Server EJB DD. There are two DDs for each module; one is a J2EE standard DD and the other is an iPlanet Application Server specific DD specified in this chapter.

DDs application module portions are standardized in the J2EE specification, v1.1. For more information on these standards, 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"

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

Introducing XML DTDs

---

The Document Type Definition (DTD) defines the DDs XML grammar. There are two DD levels; application level descriptors and component level descriptors. Applications are comprised of one or more components, one J2EE application DD and one iPlanet Application Server application DD.

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.

Application Deployment Descriptor

An application DD, lists the application components as modules. An iPlanet Application Server applications have two application DDs; one is a standard J2EE application DD and the other is an iPlanet Application Server application DD. The iPlanet Application Server application DD describes iPlanet specific deployment information for the iPlanet Application Server value-added features.

Component Deployment Descriptors

On the component level, each component group is packaged into a module with a J2EE component DD and an iPlanet Application Server component DD. An iPlanet Application Server application supports web application, EJB, RMI/IIOP Client, and resource components. For each component type, there is a DTD to define the XML elements supported for that descriptor type.

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.

Deployment Descriptors

The iPlanet Application Server require 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 an iPlanet Application Server DD file, and 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 and 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

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 10-1 shows the supported DTD entries.

Table 10-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.

Application XML DTD

---

The application DTD describes the application DD. There is a J2EE application DD, defined by the J2EE specification and an iPlanet Application Server application DD that is defined in this chapter.

The Deployment Tool is used to create the application DD and also to deploy the application. For more information on these procedures, see the Deployment Tool Online Help.

J2EE Application DTD

For more information about the application DTD description, see the J2EE specification, v1.2 Chapter 8.4.

iPlanet Application Server Application DTD

This is the iPlanet Application Server specific DTD for an application .ear file.

Table 10-2 shows the ias-app root element of the iPlanet Application Server application DD.

Table 10-2    ias-app Root Element

Sub Element	Repeat Rule	Contains	Default	Description
role-mapping	zero or more	elements	none	This field creates the mapping between the role name as known in the AppComponent, and then mapped onto one or more LDAP defined user, group, and so on. The deployment code simply treats each role-IMPL as an opaque string interpreted by the security infrastructure.

Table 10-3 shows the role-mapping sub element which maps role names to LDAP user, groups, and so on.

Table 10-3    role-mapping Sub Element

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

Table 10-4 shows the role-impl sub element which IMPLs role names to LDAP user, groups, and so on.

Table 10-4    role-impl Sub Element

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

Sample Application XML DD File

<?xml version="1.0"?>

<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN' 'http://java.sun.com/j2ee/dtds/application_1_2.dtd'>

<application>
<description>Application description</description>
   <display-name>estore</display-name>
   <module>
      <ejb>estoreEjb.jar</ejb>
   </module>
   <module>
      <web>
         <web-uri>estore.war</web-uri>
         <context-root>estore</context-root>
      </web>
   </module>
   <security-role>
      <description>the customer role</description>
      <role-name>customer</role-name>
   </security-role>
</application>

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 10-5 shows the <ias-web-app> element and sub elements used with the iPlanet Application Server web application DD root element.

Table 10-5    <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 10-6 shows the servlet sub element contains configuration information about a servlet.

Table 10-6    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 10-7 shows the servlet-info sub element which is used to describe the optional characteristics about a servlet.

Table 10-7    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 10-8 shows the validation-required sub element which is used to verify the input about a servlet should be validated.

Table 10-8    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 10-9 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 10-9    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 10-10 shows the parameters element which is used to describe the input parameters to be validated.

Table 10-10     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 10-11 shows the param sub elements where each parameter is represented by a name and the rules that are applied to it for validation.

Table 10-11     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 10-12 shows the input-field sub elements which is used to detail the input parameter.

Table 10-12    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 10-13 shows the param-group sub elements where each parameter group is represented by an event source name and the associated parameters.

Table 10-13    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 10-14 shows the session-info elements which is used to specifies session information.

Table 10-14    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 distributed, fault-tolerant 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	30 minutes	Number of session timeout minutes before a timeout. If unspecified, a system wide default session timeout is used
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 10-15 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 10-15    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 10-16 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 10-16    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 10-17 shows the nlsinfo sub elements which contains the configuration information about the application's NLS settings.

Table 10-17    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 10-18 shows the locale-charset-map sub elements which contains the descriptor information for locale and corresponding character sets.

Table 10-18    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 10-19 shows the role-mapping sub elements which contains the descriptor information for mapping roles to LDAP user, groups, and so on.

Table 10-19    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 10-20 shows the role-impl sub elements which contains the descriptor information for role implementation.

Table 10-20    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 10-23) or entity element (Table 10-24). 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 10-21 shows the ias-ejb-jar element which is the iPlanet Application Server web application DD root element.

Table 10-21    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 10-22 shows the enterprise-beans sub element which contains declarations for one or more enterprise beans.

Table 10-22    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 10-23 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 10-23    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 10-24 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 10-24    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 10-25 shows the persistence-manager sub element which defines all persistence manager specific information.

Table 10-25    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 10-26 shows the pool-manager sub element which defines all pool manager specific information.

Table 10-26    pool-manager Sub Elements  

Sub Element	Repeat Rule	Contains	Default	Description
commit-option	one and only one	string value of COMMIT_OPTION_C or COMMIT_OPTION_B	COMMIT_ OPTION_C	Option B: Between transactions, the Container caches a "ready" instance. 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 10-27 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 10-27    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 10-28 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 10-28    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 10-29 shows the role-mapping sub elements which are the mapping roles descriptors for the LDAP user, groups, and so on.

Table 10-29    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 Roll Implementation

Table 10-30 shows the role-impl sub elements which are the role implementation descriptors.

Table 10-30    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 9 "Developing and Deploying RMI/IIOP-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 10-31 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 10-31    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 10-32 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 10-32    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, such as a JDBC datasource, Java Mail and JMS have a resource XML file. 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 10-33 shows the ias-Datasource-jar sub element which is the resource DD root element.

Table 10-33    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 10-34 shows the ias-resource sub element which is the descriptor used for all resources.

Table 10-34    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 10-35 shows the resource sub elements which are the descriptors used for all resources.

Table 10-35    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 10-36 shows the jdbc sub elements which are the descriptors used for the JDBC datasource.

Table 10-36    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 a RMI/IIOP Client datasource.

Elements for Specifying Java Client Resources

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

Table 10-37    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 10-38 shows the jdbc sub elements which are the JDBC settings descriptors.

Table 10-38    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.