Chapter 10   Packaging for Deployment


This chapter describes the contents of iAS modules and how they are packaged to create an iAS application.ear file used for application deployment. The iAS modules include J2EE standard elements and iAS specific elements. Only iAS 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

• Rich Client XML DTD

• Resource XML DTD

Overview of Packaging and Deployment

---

An iAS application is comprised of one or more iAS application modules, an iAS deployment descriptor (DD) and a J2EE application deployment descriptor (DD). All of these items are packaged, using the Java ARchive (JAR) file format, into one file with an extension of .ear (Enterprise ARchive). The deployment descriptors are used by the iAS Deployment Tool (iASDT) to deploy the application components and to register the resources with the iAS.

Each of these application modules consist of either EJB, Web-application, Rich Client, or resource components, as well as an iAS deployment descriptor, and a J2EE deployment descriptor. For example, an EJB module would have one or more EJB components, an EJB deployment descriptor (DD) and an iAS EJB deployment descriptor (DD). There are two DDs for each module; one is a J2EE standard DD and the other is an iAS specific DD specified by this chapter.

Portions of the deployment descriptors for the application modules have been standardized by the J2EE specification, v1.1. For more information on these standards refer to 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 diagram below illustrates how components are package into modules and then assembled into an iAS application .ear file ready for deployment.

Introducing XML DTDs

---

The Document Type Definition (DTD) defines the XML grammar for the deployment descriptors. There are two levels of deployment descriptors; there are application level descriptors, and component level descriptors. Applications are comprised of one or more components, one J2EE application deployment descriptor and one iAS application deployment descriptor.

The J2EE platform provides packaging and deployment facilities. These facilities use Java ARchive (JAR) files as the standard package for components and applications, and XML-based deployment descriptors for customizing parameters. See chapter 7 "Packaging and Deployment" of the Developing Enterprise Applications with the Java 2 Platform, Enterprise Edition, v 1.0 for more information on the J2EE packaging and deployment process.

Application Deployment Descriptor

The deployment descriptor for an application, lists the application's components as modules. An iAS application will have two application deployment descriptors; one is a standard J2EE application DD and the other is an iAS application DD. The iAS application DD describes iAS specific deployment information for the iAS value-added features.

Component Deployment Descriptors

On the component level, each group of components packaged into a module will also have a J2EE component DD and an iAS component DD. An iAS application supports e web application, EJB, rich client and resource components. For each of these component types, there is a DTD to define the XML elements supported for that type of descriptor.

Creating Deployment Descriptors

All the deployment descriptors (DDs) needed for an iAS application are created using iPlanet Application Server Deployment Tool (iASDT). Refer to the iASDT documentation for further details on these procedures.

Deployment Descriptors

The application server uses deployment descriptors (DD) to properly deploy the application. The DDs are in the form of XML files that contain metadata describing deployment information about the J2EE modules (such as servlets, JSPs and EJBs) that make up your application. The information in each XML file is stored in a registry internal to the application server.

Each application module must have an iAS XML DD file, and a J2EE XML DD file. Additionally, each application component must be associated with a globally unique identifier, or GUID.

The following is a list of all the types of deployment descriptors supported by iAS:

• application DD and iAS application DD

• web application DD and an iAS web application DD

• EJB DD and an iAS EJB DD

• application-client DD and an iAS Rich Client DD

• iAS resource DD

Document Type Definition (DTD)

The Document Type Definition (DTD) describes the structure and properties of a class of XML DD files. Each DD will have exactly one element that completely contains all other elements (or sub elements).

The descriptions of the elements found in the XML files are presented in a table format. These element tables have several fields that describe the purpose of the element and settings for the element's parameters. Some elements are hierarchical, that is they have parameters that are other elements (or sub elements). If a parameter contains an element, the description for that element can be found in another table describing that element.

Table 10-1 Document Type Definition

Element	Name of the element as it appears in XML file, and a description of the element.
Sub Elements	Lists the elements contained by this element.
Repeat Rule	Describes how many times this parameter is defined: "one and only one" means this parameter is not optional, it must be defined one time only. "zero or one" means this parameter is optional, it may be undefined or defined one time only <?> "one or many" means this parameter is not optional, it must be defined at least one time or multiple times <+> "zero or many" means this parameter is optional or may be defined many times <*>
Contains	This field describes the contents of the parameter. The contents may be a string, boolean, an integer or an element. If this field is an element, the definition of the element will be found in another table for that element.
Default	Describes the value of this parameter if it is not defined.
Description	The parameter description for this element.

The iAS Registry

The iAS 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 iAS gains access to servlets, EJBs, and other application resources is called registration, because it involves placing entries in the iAS registry for each item.

You can change some of the information in the registry at run-time using the iAS Administrator Tool (iASAT). For more information about the registry, and the iASAT, see the Administration Guide.

GUIDs

A GUID is a 128-bit hexadecimal number that is assigned to an EJB and Servlet, and optionally to JSPs and is automatically generated by the iAS Deployment Tool. The GUID has the following format:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

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

GUIDs are normally assigned automatically by the deployment tool, or by iPlanet Application Builder. You can generate a GUID manually 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 Document Type Definition (DTD) describes the application Deployment Descriptor (DD). There is a J2EE application DD, defined by the J2EE specification, and an iAS application DD that is defined in this chapter.

The iAS Deployment Tool (iASDT) is used to create the application DD, and also to deploy the application. Refer to the iASDT documentation for further details on these procedures.

J2EE Application DTD

See the Java Platform 2 Enterprise Edition, specification, v1.2 section 8.4 "J2EE:application XML DTD", for the application DTD description.

iAS Application DTD

This is the IAS 6.0 specific XML DTD for the Application ear file

ias-app

The root element of the iAS application deployment descriptor.

Sub Elements  

Repeat Rule  

Contains  

Default  

Description  

role-mapping  

zero or more  

elements  

none   This field create the mapping between the role name as it is known in the AppComponent, and then map them onto one or more LDAP defined user, group, etc.

The deployment code simply treats each role-impl as an opaque string that's interpreted by the security infrastructure

 

ias-app "> Table 10-2

ias-app	The root element of the iAS application deployment descriptor.
Sub Elements	Repeat Rule	Contains	Default	Description
role-mapping	zero or more	elements	none	This field create the mapping between the role name as it is known in the AppComponent, and then map them onto one or more LDAP defined user, group, etc. The deployment code simply treats each role-impl as an opaque string that's interpreted by the security infrastructure

ias-app

role-mapping

Maps role names to LDAP user, groups.

Sub Elements  

Repeat Rule  

Contains  

Default  

Description  

role-name  

one and only one  

string  

none   The name of the role as referred to in the <security-role> element

 

role-impl  

one and only one  

elements  

none   The string used to represent an LDAP group/user thing that makes up a particular role-name. A role imple could be any number of groups and/or users.

 

"> Table 10-3 role-mapping

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

role-impl

.

Sub Elements  

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

 

"> Table 10-4 role-impl

role-impl	.
Sub Elements	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 provides an overview of web applications, the web application module and the web application deployment descriptor (DD). The DDs are created using iPlanet Application Server Deployment Tool (iASDT). Refer to the iASDT Administration and Deployment Guide for further details on these procedures.

Web Application Overview

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

The web application is a composite of the following items:

• Servlets

• JavaServer Pages (JSPs)

• Utility Classes

• Static documents (html, images, sounds, etc.)

• Client side applets, beans and classes

• Descriptive meta information bundling all the above items together

The web application is created by first assembling all the needed Web components into a Web application module along with module deployment descriptors (DD), and then packaging this web application module with all other modules that will be used by the J2EE application along with the application deployment descriptors (DD) into the final web application that is ready for deployment. A complete description of the J2EE assembly and deployment is available in the J2EE specification, chapter 8. See the URL:http://java.sun.com/j2ee.

Web Application XML DTD

This section provides the XML Document Type Definition (DTD) for the iAS specific Web application deployment descriptor (DD). Refer to section 8.4 of the J2EE specification for the standard J2EE application DD.

The Web application DD supports the definition of elements that provide the following information:

• servlet information

• session information

• EJB reference information

• Resource reference information

• Specifying Servlet Information

Element for specifying an iAS Web Application

Table 10-5 <ias-web-app>

ias-web-app	The root element of the iAS web application deployment descriptor.
Sub Elements	Repeat Rule	Contains	Default	Description
servlet	zero or more	elements	none	Contains servlet configuration information.
session-info	one and only one	elements	none	Specifies session information.
ejb-ref	zero or more	elements	none	Specifies storage place foe ABOLUTE JNDI name of the corresponding J2EE XML ejb-ref entry.
resource-ref	zero or more	elements	none	Specifies storage place for the ABSOLUTE JNDI name that the ejb-link in the corresponding J2EE XML file ejb-ref entry.
nlsinfo	one and only one	elements	none	Descriptor for nls settings.
role-maping	zero or many	elements	none	LDAP role mapping descriptor.

Elements for Specifying Servlet Information

servlet	Contains configuration information about a servlet.
Sub Elements	Repeat Rule	Contains	Default	Description
servlet-name	one and only one	string	none	The name of the servlet. 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 characteristics of the servlet.
validationRequired	zero or one	boolean	"false"	Specifies if the input parameter needs to be validated.
error-handler	zero or one	string	none	Describes the error handler for the servlet.
parameters	zero to more	elements	none	Describes all the 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.

servlet-info	Describes optional characteristics of the servlet.
Sub Elements	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 will continue to be routed to that 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 information about the server including enabling/disabling of the server and loadbalancing.

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

caching	Describes caching criteria for the servlet. Caching can be disabled by not defining the caching element.
Sub Elements	Repeat Rule	Contains	Default	Description
cache-timeout	one and only one	integer	none	Sets the time-out for the caching of the servlet (in seconds). If the value is 0, caching is disabled.
cache-size	one and only one	integer	none	Sets the size of the cache. 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	none	Criteria expression containing a string of comma-delimited descriptors, each descriptor defining a match with one of the input parameters to the servlet.

Examples for Setting Cache Criteria

The following examples provide some common usages and settings for the cache-criteria element.

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 is the value of the "stock" input parameter is "NSCP"

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

This means that caching is enabled whenever the value of the input parameters is the same as the value cached.

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

This means caching is enabled if the value of the "dept" parameter is either of sales or marketing or support.

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

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

server-info	Optional extra information about the server, including enabling/disabling of the server, and load-balancing.
Sub Elements	Repeat Rule	Contains	Default	Description
server-ip	one and only one	string	none	Server's IP address.
server-port	one and only one	string	none	Executive Server's port number.
sticky-lb	zero or many	boolean	"sticky" setting of the servlet-info	Sets sticky load balancing. Legal values are "true" or "false". If set will override 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".

parameters	Describes all the input parameters to be validated.
Sub Elements	Repeat Rule	Contains	Default	Description
param	zero or more	elements	none	Specifies each parameter by name and the rules that are applied to it for validation.

param	Each parameter is represented by a name and the rules that are applied to it for validation.
Sub Elements	Repeat Rule	Contains	Default	Description
param-name	one and only one	string	none	Name of the input parameter.
input-fields	one and only one	elements	none	This describes the details of the input parameter.

input-fields	Describes the details of the input parameter.
Sub Elements	Repeat Rule	Contains	Default	Description
input-required	zero or one	boolean	none	Specifies whether the input parameter is required to exist, i.e. 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 error handler for the parameter.

param-group	Description: Each parameter group is represented by an event source name and the associated parameters.
Sub Elements	Repeat Rule	Contains	Default	Description
param-group-name	one and only one	string	none	Name of the parameter group.
param-input	one or more	string	none	Name of the parameter input associated with the parameter group.

Elements for Specifying Session Information

session-info	Specifies session information.
Sub Elements	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	This is the number of session timeout seconds before a timeout. If unspecified, a system-wide default session timeout is used
secure	zero or one	boolean	"false"	This specifies that 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	This specifies that the domain for the application. This is used to set the cookie for the session for that domain. 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 foo.acme.com, bar.asme.com, etc.
path	zero or one	String value of the URL for the session cookie starting with "/".	The URL that created the cookie.	This specifies the path for the session cookie. A non-existent path implies that the same path as the one that sets the cookie is used. For example, the path "/phoenix" will match "/phoenix/types/bird.html" and "/phoenix/birds.html".
scope	zero or one	String identifying the other application.	none	Grouping name that selects which other applications can access this session. For example, if the domain is set to acme.com, then the session is visible to foo.acme.com, bar.asme.com, etc.
dsync-type	zero or one	string of either "dsync-local" or "dsync-distributed"	none	Specifes the type of DSync session.

Elements for Specifying EJB Reference Information

ejb-ref	This is the storage place for the ABSOLUTE jndi name that the ejb-link in the corresponding J2EE XML file ejb-ref entry.
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

resource-ref	This is the storage place for the ABSOLUTE jndi name that the resource-ref in the corresponding J2EE XML file resource-ref entry.
Parameter	Repeat Rule	Contains	Default	Description
resource-ref-name	one and only one	string	none	This is the name of the resource-ref 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

nlsinfo	The nlsinfo element contains configuration information about application nls settings..
Sub Element	Repeat Rule	Contains	Default	Description
locale-charset-map	zero or many	elements	none	Contains locale and corresponding character set.
default-locale	one and only one	string	none	Default locale.

locale-charset-map	Descriptor for locale and corresponding charater set.
Sub Element	Repeat Rule	Contains	Default	Description
locale	one and only one	string	none	Name of locale.
charset	one and only one	string	none	Default locale.

Elements for Specifying Role Mapping

role-mapping	Descriptor for mapping roles to LDAP user, groups.
Sub Element	Repeat Rule	Contains	Default	Description
role-name	one and only one	string	none	Name of the role 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.

role-impl	Descriptor for role implementation.
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 provides the EJB Document Type Definition (DTD) that is used by the EJB deployment descriptors. The DDs are created using iPlanet Application Server Deployment Tool (iASDT). Refer to the iASDT documentation for further details on how to create the DDs.

EJB Jar File Contents

The standard format used to package enterprise Beans is the ejb-jar file. This 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 deployment descriptor (DD) as well as all the class files for the following:

• The enterprise bean class.

• The enterprise bean home and remote interface.

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

In addition, the ejb-jar file must contain the class files for all the 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, iAS 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 were used. In certain cases, however, you may want to ensure that parameters passed to a bean are always passed by value. The iAS supports the ability to mark a bean or even a particular method within a bean as optionally requiring pass by value semantics. The parameter passing method used by the EJB is defined by the "pass-by-value" element. See the "pass-by-value" element description in the "session" or "entity" element table in this section. Because this option can decrease performance by greatly increasing call overhead, the default value is "false" if this entry is unspecified.

EJB iAS XML DTD

The following is the iAS specific XML DTD for EJB JAR files.

ias-ejb-jar	The root element of the iAS web application deployment descriptor.
Sub Element	Repeat Rule	Contains	Default	Description
enterprise-beans	one and only one	element	none	The enterprise-beans element contains the declarations of one or more enterprise beans.

enterprise-beans	The enterprise-beans element contains the declarations of one or more enterprise beans.
Sub Elements	Repeat Rule	Contains	Default	Description
session	one or the other	element	none	An element that declares all the ias specific session bean related deployment information
entity	one or the other	element	none	An element that declares all the ias specific entity bean related deployment information

session	Declares all the ias specific session bean related deployment information. The ejb-name MUST be matched 1 to 1 with the ejb-name declared in the J2EE XML file.
Sub Elements	Repeat Rule	Contains	Default	Description
ejb-name	one and only one	string	none	The name of the ejb.
guid	one and only one	string	none	The guid of the ejb 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 iASAT.
pass-by-value	one and only one	boolean	none	If "true", marshalling of all call parameters to the EJB will be 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
ejb-ref	zero or more	elements	none	This is a storage place for the ABSOLUTE jndi name that the ejb-link in the corresponding J2EE XML file ejb-ref entry.
resource-ref	zero or more	elements	none	This is a storage place for the ABSOLUTE jndi name that the resource-ref in the corresponding J2EE XML file resource-ref entry.
failoverrequired	zero or one	boolean	none	Indicates whether failover is required.

entity	Declares all the ias specific entity bean related deployment information. The ejb-name MUST be matched 1 to 1 with the ejb-name declared in the J2EE XML file.
Sub Elements	Repeat Rule	Contains	Default	Description
ejb-name	one and only one	string	none	The name of the ejb.
guid	one and only one	string	none	The guid of the ejb 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 iASAT.
pass-by-value	one and only one	boolean	none	If "true", marshalling of all call parameters to the EJB will be 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	This is a storage place for the ABSOLUTE jndi name that the ejb-link in the corresponding J2EE XML file ejb-ref entry.
resource-ref	zero or more	elements	none	This is a storage place for the ABSOLUTE jndi name that the resource-ref in the corresponding J2EE XML file resource-ref entry.
failover-required	zero or one	boolean	"false"	This indicates whether failover is required.
iiop	zero or one	boolean	"false"	Indicates if the bean is rich client enabled.
role-mapping	zero or many	elements	none	This descriptor creates the role mapping.

persistence-manager	Defines all the persistence manager specific information.
Sub Elements	Repeat Rule	Contains	Default	Description
factory-class-name	one and only one	string	none	Name of the persistence manager factory class.
properties-file-location	one and only one	string	none	Location in jar file of properties file.

pool-manager	Defines all the pool manager specific information.
Sub Elements	Repeat Rule	Contains	Default	Description
comit-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 will not cache a "ready" instance. (see EJB v1.1 spec. section 9.1.10 for more details.)
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 iASAT.
ready-pool-maxsize	one and only one	positive integer or "0" for infinite	infinite	Maximum size of the ready cache in number of entries. This value can be changed during runtime by iASAT.
free-pool-maxsize	one and only one	positive integer or "0" for infinite	infinite	Maximum size of the instance free pool in number of entries. This value can be changed during runtime by iASAT.

ejb-ref	This is the storage place for the ABSOLUTE jndi name that the ejb-link in the corresponding J2EE XML file ejb-ref entry.
Sub Elements	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.

resource-ref	This is the storage place for the ABSOLUTE jndi name that the resource-ref in the corresponding J2EE XML file resource-ref entry.
Sub Elements	Repeat Rule	Contains	Default	Description
resource-ref-name	one and only one	string	none	This is the name of the resource-ref in the corresponding J2EE XML file resource-ref entry.
jndi-name	one and only one	string	none	The ABSOLUTE jndi name.

role-mapping	Descriptor for mapping roles to LDAP user, groups.
Sub Element	Repeat Rule	Contains	Default	Description
role-name	one and only one	string	none	Name of the role 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.

role-impl	Descriptor for role implementation.
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.

Rich Client XML DTD

---

The Rich Client is an iAS specific type of J2EE client. A Rich Client supports the standard J2EE Application Client specifications and in addition supports direct access to iAS. For more information on Rich Client, refer to Chapter 10 Rich Client".

A Rich Client jar file will contain two deployment descriptors (DDs) that are generated by the iASDT. One of these DDs is specified by the J2EE application-client XML Document Type Definition (DTD), that can be found in the J2EE Specification, v1.0 Chapter 9 Application Clients. The other DD contains iAS specific Rich Client elements; these elements are described in section <$paratext>" of this chapter.

For a sample Rich Client DD file, refer to section <$paratext>" in Appendix C, " Sample Deployment Files".

iAS Rich Client XML DTD

The ias-java-client-jar element is the root element of the Rich Client deployment descriptor.

Elements for Specifying EJB Reference Information

ejb-ref	This is the storage place for the ABSOLUTE jndi name that the ejb-link in the corresponding J2EE XML file ejb-ref entry.
Sub Elements	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

resource-ref	This is the storage place for the ABSOLUTE jndi name that the resource-ref in the corresponding J2EE XML file resource-ref entry.
Sub Elements	Repeat Rule	Contains	Default	Description
resource-ref-name	one and only one	string	none	This is the name of the resource-ref 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 iAS resource, such as a JDBC datasource, Java Mail and JMS, has a resource XML file. This XML file contains entries that are used to register the resource with iAS. These entries define the way iAS connects to that resource. These files are generated by the iAS Deployment Tool (iASDT). This section describes the resource XML file entries. For information on how to generate these files, refer to the iASDT documentation.

Datasource XML DTD

This section describes the XML DTD for the iAS datasource.

ias-Datasource-jar	This is the root element of the resource deployment descriptor
Sub Elements	Repeat Rule	Contains	Default	Description
ias-resource	one and only one	element	none	Common element for all the resource deployment descriptors.

ias-resource	Descriptor used for all the resources.
Sub Elements	Repeat Rule	Contains	Default	Description
resource	one and only one	elements	none	Common element for all the resource deployment descriptors.

resource	Descriptor used for all the resources.
Sub Elements	Repeat Rule	Contains	Default	Description
jndi-name	one and only one	string	none	The absolute jndi name of the resource factory (i.e. jdb/foo).
jdbc	one or the other	elements	none	Descriptor for the JDBC data source.
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.

jdbc	Descriptor for the jdbc datasource.
Sub Elements	Repeat Rule	Contains	Default	Description
database	one and only one	string	none	Name of the database to connect to.
datasource	one and only one	string	none	Name to assign to the datasource.
username	one and only one	string	none	Valid user name for this database.
password	one and only one	string	none	Valid password for the user name listed.
driver-type	one and only one	string field containing of one of the following: ORACLE_OCI (Oracle) DB2_CLI (DB2) INFORMIX_CLI (Informix) SYBASE_CTLIB (Sybase) ODBC (ODBC)	none	Backend-specific JDBC driver.
resource-mgr	zero or one	string	none	If this attribute is set, the datasource is available for distributed transactions by way of 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 that you created for a resource manager under the RESOURCEMGR key.

Rich Client Datasource XML DTD

ias-javaclient-resource	Root element for the Rich Client datasource XML DD..
Sub Elements	Repeat Rule	Contains	Default	Description
jdbc	one or the other	elements	none	Descriptor for Rich 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.

jdbc	Descriptor for JDBC settings.
Sub Elements	Repeat Rule	Contains	Default	Description
driverClass	one and only one	elements	none
connectUr1	one and only one	string	none	.
userName	one and only one	string	none
password	one and only one	string	none

---