Previous Contents Index DocHome Next |
iPlanet Application Server Developer's Guide (Java) |
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
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"
The following diagram illustrates how components are packaged into modules and then assembled into an iPlanet Application Server application .ear file ready for deployment.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"
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
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 name as it appears in the XML file and an element description.
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-3 shows the role-mapping sub element which maps role names to LDAP user, groups, and so on.
Table 10-4 shows the role-impl sub element which IMPLs role names to LDAP user, groups, and so on.
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
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.Static documents (HTML, images, sounds, and so on)
Client side applets, beans and classes
Descriptive meta information bundling the above items together
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:
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.
Elements for Specifying Servlet Configuration Information
Table 10-6 shows the servlet sub element contains configuration information about a servlet.
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.
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
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
Sets the servlet caching timeout (in seconds). If the value is 0, caching is disabled.
string where the syntax is any value of arg in the input parameter list; for details, see "Caching Servlet Results."
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 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
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
Elements for Specifying Servlet Input Field
Table 10-12 shows the input-field sub elements which is used to detail the input parameter.
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
Elements for Specifying Session Information
Table 10-14 shows the session-info elements which is used to specifies session information.
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
The ejb-link in the corresponding J2EE XML file ejb-ref entry.
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
The resource-ref name in the corresponding J2EE XML file resource-ref entry.
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
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
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.
Elements for Specifying Role IMPL
Table 10-20 shows the role-impl sub elements which contains the descriptor information for role implementation.
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.
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.The enterprise helper classes.
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
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.
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.
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.
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
Elements for Specifying Pool Manager
Table 10-26 shows the pool-manager sub element which defines all pool manager specific information.
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
The ejb-link in the corresponding J2EE XML file ejb-ref entry.
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
The resource-ref name in the corresponding J2EE XML file resource-ref entry.
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.
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
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
The ejb-link in the corresponding J2EE XML file ejb-ref entry.
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
The resource-ref name in the corresponding J2EE XML file resource-ref entry.
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
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
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
The absolute jndi-name of the resource factory (for example, jdb/Who).
Elements for Specifying JDBC Datasources
Table 10-36 shows the jdbc sub elements which are the descriptors used for the JDBC datasource.
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
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
Previous Contents Index DocHome Next
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.
Last Updated June 14, 2001