Chapter 3 Assembling and Deploying Applications

This chapter describes Sun Java System Application Server modules and how these modules are assembled separately or together in an application. This chapter also describes classloaders and tools for assembly and deployment.

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

The following topics are presented in this chapter:

• Overview of Assembly and Deployment

• Assembling Modules and Applications

• Deploying Modules and Applications

• asant Assembly and Deployment Tool

Overview of Assembly and Deployment

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

• Modules

• Applications

• J2EE Standard Descriptors

• Sun Java System Application Server Descriptors

• Naming Standards

• Directory Structure

• Runtime Environments

• Classloaders

Modules

A J2EE module is a collection of one or more J2EE components of the same container type (for example, web or EJB) with deployment descriptors of that type. One descriptor is J2EE standard, the other is Application Server specific. Types of J2EE modules are as follows:

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

• EJB JAR File: The EJB JAR file is the standard format for assembling enterprise beans. This file contains the bean classes (home, remote, local, and implementation), all of the utility classes, and the deployment descriptors (ejb-jar.xml and sun-ejb-jar.xml). If the EJB component is an entity bean with container managed persistence, a .dbschema file and a CMP mapping descriptor, sun-cmp-mapping.xml, must be included as well.

• Application Client Container JAR File: An ACC client is an Application Server specific type of J2EE client. An ACC client supports the standard J2EE Application Client specifications, and in addition, supports direct access to the Application Server. Its deployment descriptors are application-client.xml and sun-application-client.xml.

• Resource RAR File: RAR files apply to J2EE CA connectors. A connector module is like a device driver. It is a portable way of allowing EJB components to access a foreign enterprise system. Each Application Server connector has a J2EE XML file, ra.xml.

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

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

The Application Server also supports lifecycle modules. See Chapter 10, Developing Lifecycle Listeners for more information.

EJB JAR and Web modules can also be deployed separately, outside of any application, as in the following figure. EJB components are assembled in a JAR file with ejb-jar.xml and sun-ejb-jar.xml deployment descriptors. Web components are assembled in a WAR file with web.xml and sun-web.xml deployment descriptors. Both module types are deployed to the Application Server.

Figure 3–1 Module assembly and deployment

Applications

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

The following diagram illustrates how components are assembled into modules and then assembled into an Application Server application and deployed. EJB components are assembled in a JAR file with ejb-jar.xml and sun-ejb-jar.xml deployment descriptors. Web components are assembled in a WAR file with web.xml and sun-web.xml deployment descriptors. An application client is assembled in a JAR file with application-client.xml and sun-application-client.xml deployment descriptors. A resource adapter is assembled in a RAR file with a ra.xml deployment descriptor. All modules are assembled in an EAR file and deployed to the Application Server.

Figure 3–2 Application assembly and deployment

Each module has an Application Server deployment descriptor and a J2EE deployment descriptor. The Application Server uses the deployment descriptors to deploy the application components and to register the resources with the Application Server.

An application consists of one or more modules, an optional Application Server deployment descriptor, and a required J2EE application deployment descriptor. All items are assembled, using the Java ARchive (.jar) file format, into one file with an extension of .ear.

J2EE Standard Descriptors

The J2EE platform provides assembly and deployment facilities. These facilities use WAR, JAR, and EAR files as standard packages for components and applications, and XML-based deployment descriptors for customizing parameters.

J2EE standard deployment descriptors are described in the J2EE specification, v1.4. You can find the specification at http://java.sun.com/products/.

To check the correctness of these deployment descriptors prior to deployment, see The Deployment Descriptor Verifier.

The following table shows where to find more information about J2EE standard deployment descriptors.

Sun Java System Application Server Descriptors

The Application Server uses additional deployment descriptors for configuring features specific to the Application Server. The sun-application.xml, sun-web.xml, and sun-cmp-mappings.xml files are optional; all the others are required.

To check the correctness of these deployment descriptors prior to deployment, see The Deployment Descriptor Verifier.

The following table lists the Application Server deployment descriptors and their DTD files. For complete descriptions of these files, see Appendix A, Deployment Descriptor Files.

Naming Standards

Names of applications and individually deployed EJB JAR, WAR, and connector RAR modules must be unique within an Application Server domain. Modules of the same type within an application must have unique names. In addition, for entity beans that use CMP,.dbschema file names must be unique within an application.

If you do not explicitly specify a name, the default name is the first portion of the file name (without the .war or .jar extension). Modules of different types can have the same name within an application, because the directories holding the individual modules are named with _jar, _war and _rar suffixes. This is the case when you use the Administration Console, the asadmin command, or the deploytool to deploy an application or module. See Tools for Deployment.

Make sure your package and file names do not contain spaces or characters that are illegal for your operating system.

If you are writing your own JSR 88 client to deploy applications to the Application Server using the following API, the name of the application is taken from the display-name entry in the J2EE standard deployment descriptor, because there is no file name in this case. If the display-name entry is not present, the Application Server creates a temporary file name and uses that name to deploy the application.

javax.enterprise.deploy.spi.DeploymentManager.distribute(Target[], 
InputStream, InputStream)

Neither the Administration Console, the asadmin command, nor the deploytool uses this API.

For more information about JSR 88, see the JSR 88 page at http://jcp.org/en/jsr/detail?id=88.

Directory Structure

When you deploy an application, the application is expanded to an open directory structure, and the directories holding the individual modules are named with _jar, _war and _rar suffixes. If you use the asadmin deploydir command to deploy a directory instead of an EAR file, your directory structure must follow this same convention.

Module and application directory structures follow the structure outlined in the J2EE specification. Here is an example directory structure of a simple application containing a web module, an EJB module, and a client module.

+ converter_1/
|--- converterClient.jar
|--+ META-INF/
|  |--- MANIFEST.MF
|  |--- application.xml
|  |--- sun-application.xml
|--+ war-ic_war/
|  |--- index.jsp
|  |--+ META-INF/
|  |  |--- MANIFEST.MF
|  |--+ WEB-INF/
|     |--- web.xml
|     |--- sun-web.xml
|--+ ejb-jar-ic_jar/
|  |--- Converter.class
|  |--- ConverterBean.class
|  |--- ConverterHome.class
|  |--+ META-INF/
|     |--- MANIFEST.MF
|     |--- ejb-jar.xml
|     |--- sun-ejb-jar.xml
|--+ app-client-ic_jar/
   |--- ConverterClient.class
   |--+ META-INF/
      |--- MANIFEST.MF
      |--- application-client.xml
      |--- sun-application-client.xml

         

Here is an example directory structure of an individually deployed connector module.

+ MyConnector/
|--- readme.html
|--- ra.jar
|--- client.jar
|--- win.dll
|--- solaris.so
|--+ META-INF/
   |--- MANIFEST.MF
   |--- ra.xml

         

Runtime Environments

Whether you deploy an individual module or an application, deployment affects both the file system and the server configuration.

Module Runtime Environment

The following figure illustrates the environment for individually deployed module-based deployment.

Figure 3–3 Module runtime environment

For file system entries, modules are extracted as follows:

domain-dir/applications/j2ee-modules/module-name
domain-dir/generated/ejb/j2ee-modules/module-name
domain-dir/generated/jsp/j2ee-modules/module-name

The applications directory contains the directory structures described in Directory Structure. The generated/ejb directory contains the stubs and ties that an ACC client needs to access the module; the generated/jsp directory contains compiled JSP files.

Lifecycle modules (see Chapter 10, Developing Lifecycle Listeners) are extracted as follows:

domain-dir/applications/lifecycle-modules/module-name

Configuration entries are added in the domain.xml file as follows:

<server>
   <applications>
      <type-module>
         ...module configuration...
      </type-module>
   </applications>
</server>

The type of the module in domain.xml can be lifecycle, ejb, web, or connector. For details about domain.xml, see the Sun Java System Application Server Platform Edition 8.2 Administration Reference.

Application Runtime Environment

The following figure illustrates the environment for application-based deployment.

Figure 3–4 Application runtime environment

For file system entries, applications are extracted as follows:

domain-dir/applications/j2ee-apps/app-name
domain-dir/generated/ejb/j2ee-apps/app-name
domain-dir/generated/jsp/j2ee-apps/app-name

The applications directory contains the directory structures described in Directory Structure. The generated/ejb directory contains the stubs and ties that an ACC client needs to access the module; the generated/jsp directory contains compiled JSP files.

Configuration entries are added in the domain.xml file as follows:

<server>
   <applications>
      <j2ee-application>
         ...application configuration...
      </j2ee-application>
   </applications>
</server>

For details about domain.xml, see the Sun Java System Application Server Platform Edition 8.2 Administration Reference.

Classloaders

Understanding Application Server classloaders can help you determine where and how you can position supporting JAR and resource files for your modules and applications.

In a Java Virtual Machine (JVM), the classloaders dynamically load a specific Java class file needed for resolving a dependency. For example, when an instance of java.util.Enumeration needs to be created, one of the classloaders loads the relevant class into the environment. This section includes the following topics:

• The Classloader Hierarchy

• Classloader Universes

• Circumventing Classloader Isolation

The Classloader Hierarchy

Classloaders in the Application Server runtime follow a hierarchy that is illustrated in the following figure and fully described in Table 3–3.

Figure 3–5 Classloader runtime hierarchy

Note that this is not a Java inheritance hierarchy, but a delegation hierarchy. In the delegation design, a class loader delegates classloading to its parent before attempting to load a class itself. A class loader parent can be either the System Classloader or another custom class loader. If the parent class loader can’t load a class, the findClass() method is called on the class loader subclass. In effect, a class loader is responsible for loading only the classes not available to the parent.

The Servlet specification recommends that the Web Classloader look in the local class loader before delegating to its parent. You can make the Web Classloader follow the delegation model in the Servlet specification by setting delegate="false" in the class-loader element of the sun-web.xml file. It’s safe to do this only for a web module that does not interact with any other modules.

The default value is delegate="true", which causes the Web Classloader to delegate in the same manner as the other classloaders. You must use delegate="true" for a web application that accesses EJB components or that acts as a web service client or endpoint. For details about sun-web.xml, see The sun-web.xml File.

Classloader Universes

Access to components within applications and modules installed on the server occurs within the context of isolated class loader universes, each of which has its own EJB, Web, and JSP Engine classloaders.

• Application Universe: Each J2EE application has its own class loader universe, which loads the classes in all the modules in the application.

• Individually Deployed Module Universe: Each individually deployed EJB JAR, web WAR, or lifecycle module has its own class loader universe, which loads the classes in the module.

A resource such as a file that is accessed by a servlet, JSP, or EJB component must be in a directory pointed to by the class loader’s classpath. For example, the web class loader’s classpath includes these directories:

module-name/WEB-INF/classes
module-name/WEB-INF/lib

If a servlet accesses a resource, it must be in one of these directories or it is not loaded.

In iPlanet Application Server 6.x, individually deployed modules shared the same class loader. In subsequent Application Server versions, each individually deployed module has its own class loader universe.

Circumventing Classloader Isolation

Since each application or individually deployed module class loader universe is isolated, an application or module cannot load classes from another application or module. This prevents two similarly named classes in different applications from interfering with each other.

To circumvent this limitation for libraries, utility classes, or individually deployed modules accessed by more than one application, you can include the relevant path to the required classes in one of these ways:

• Using the System Classloader

• Using the Common Classloader

• Using the Java Optional Package Mechanism

• Packaging the Client JAR for One Application in Another Application

Using the System Classloader

To use the System Classloader, do one of the following, then restart the server:

• Use the Administration Console. Select the JVM Settings component under the relevant configuration, select the Path Settings tab, and edit the Classpath Suffix field. For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

• Edit the classpath-suffix attribute of the java-config element in the domain.xml file. For details about domain.xml, see the Sun Java System Application Server Platform Edition 8.2 Administration Reference.

Using the System Classloader makes an application or module accessible to any other application or module across the domain.

Using the Common Classloader

To use the Common Classloader, copy the JAR and ZIP files into the domain-dir/lib directory or copy the .class files into the domain-dir/lib/classes directory, then restart the server.

Using the Common Classloader makes an application or module accessible to any other application or module across the domain.

Using the Java Optional Package Mechanism

To use the Java optional package mechanism, copy the JAR and ZIP files into the domain-dir/lib/ext directory, then restart the server.

Using the Java optional package mechanism makes an application or module accessible to any other application or module across the domain.

For example, this is the recommended way of adding JDBC drivers to the Application Server. For a list of the JDBC drivers currently supported by the Application Server, see the Sun Java System Application Server Platform Edition 8.2 Release Notes. For configurations of supported and other drivers, see Configurations for Specific JDBC Drivers.

Packaging the Client JAR for One Application in Another Application

By packaging the client JAR for one application in a second application, you allow an EJB or web component in the second application to call an EJB component in the first (dependent) application, without making either of them accessible to any other application or module.

As an alternative for a production environment, you can have the Common Classloader load client JAR of the dependent application as described in Using the Common Classloader restart the server to make the dependent application accessible, and it is accessible across the domain.

To package the client JAR for one application in another application

1. Deploy the dependent application.

2. Add the dependent application’s client JAR file to the calling application.

   • For a calling EJB component, add the client JAR file at the same level as the EJB component. Then add a Class-Path entry to the MANIFEST.MF file of the calling EJB component. The Class-Path entry has this syntax:

     Class-Path: filepath1.jar filepath2.jar ...

     Each filepath is relative to the directory or JAR file containing the MANIFEST.MF file. For details, see the J2EE specification, section 8.1.1.2, “Dependencies.”

   • For a calling web component, add the client JAR file under the WEB-INF/lib directory.

3. If you need to package the client JAR with both the EJB and web components, set delegate="true" in the class-loader element of the sun-web.xml file.

   This changes the Web Classloader so it follows the standard class loader delegation model and delegates to its parent before attempting to load a class itself.

   For most applications, packaging the client JAR file with the calling EJB component is sufficient. You do not need to package the client JAR file with both the EJB and web components unless the web component is directly calling the EJB component in the dependent application.

4. Deploy the calling application.

   The calling EJB or web component must specify in its sun-ejb-jar.xml or sun-web.xml file the JNDI name of the EJB component in the dependent application. Using an ejb-link mapping does not work when the EJB component being called resides in another application.

Assembling Modules and Applications

Assembling (or packaging) modules and applications in Application Server conforms to all of the customary J2EE-defined specifications. The only difference is that when you assemble in Application Server, you include Application Server specific deployment descriptors that enhance the functionality of the Application Server.

For example, when you assemble an EJB JAR module, you must create two deployment descriptor files with these names: ejb-jar.xml and sun-ejb-jar.xml (both required). If the EJB component is an entity bean with container-managed persistence, you can also create a .dbschema file and a sun-cmp-mapping.xml file, but these are not required. For more information about sun-ejb-jar.xml and sun-cmp-mapping.xml, see Appendix A, Deployment Descriptor Files.

According to the J2EE specification, section 8.1.1.2, “Dependencies,” you cannot package utility classes within an individually deployed EJB module. Instead, package the EJB module and utility JAR within an application using the JAR Extension Mechanism Architecture. For other alternatives, see Circumventing Classloader Isolation.

The Application Server provides these tools for assembling and verifying a module or an application:

• deploytool

• Apache Ant

• NetBeans IDE

• The Deployment Descriptor Verifier

deploytool

You can use the deploytool, provided with the Application Server, to assemble J2EE applications and modules, configure deployment parameters, perform simple static checks, and deploy the final result. For more information about using the deploytool, see the J2EE 1.4 Tutorial at http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html.

Apache Ant

Ant can help you assemble and deploy modules and applications. For details, see asant Assembly and Deployment Tool.

NetBeans IDE

You can use the NetBeans IDE to assemble J2EE applications and modules. For more information about using the NetBeans IDE, see http://www.netbeans.org.

The Deployment Descriptor Verifier

The verifier tool validates both J2EE and Application Server specific deployment descriptors against their corresponding DTD files and gives errors and warnings if a module or application is not J2EE and Application Server compliant. You can verify deployment descriptors in EAR, WAR, RAR, and JAR files.

The verifier tool is not simply an XML syntax verifier. Rules and interdependencies between various elements in the deployment descriptors are verified. Where needed, user application classes are introspected to apply validation rules.

The verifier is integrated into Application Server deployment, the deploytool, and the sun-appserv-deploy Ant task. You can also run it as a stand-alone utility from the command line. The verifier is located in the install-dir/bin directory.

When you run the verifier during Application Server deployment, the output of the verifier is written to the tempdir/verifier-results/ directory, where tempdir is the temporary directory defined in the operating system. Deployment fails if any failures are reported during the verification process. The verifier also logs information about verification progress to the standard output.

For details on all the assertions tested by the verifier, see the assertions documentation provided at http://java.sun.com/j2ee/avk/index.html.

Using the verifier tool can help you avoid runtime errors that are difficult to debug.

This section covers the following topics:

• Command Line Syntax

• Ant Integration

• Sample Results Files

Command Line Syntax

The verifier tool’s syntax is as follows:

verifier [options] file

The file can be an EAR, WAR, RAR, or JAR file.

The following table shows the options for the verifier tool.

For example, the following command runs the verifier in verbose mode and writes all the results of static verification of the ejb.jar file to the output directory ResultsDir:

verifier -v -r a -d ResultsDir ejb.jar

The results files are ejb.jar_verifier.timestamp.txt and ejb.jar_verifier.timestamp.xml. The format of the timestamp is yyyyMMddhhmmss.

If the verifier runs successfully, a result code of 0 is returned. This does not mean that no verification errors occurred. A nonzero error code is returned if the verifier fails to run.

Ant Integration

You can integrate the verifier into an Ant build file as a target and use the Ant call feature to call the target each time an application or module is assembled. This is because the main method in com.sun.enterprise.tools.verifier.Verifier is callable from user Ant scripts. The main method accepts the arguments described in Table 3–4.

Example code for an Ant verify target is as follows:

<target name="verify">
 <echo message="Verification Process for ${testfile}"/>
 <java classname="com.sun.enterprise.tools.verifier.Verifier"
		 fork="yes">
	 <sysproperty key="com.sun.enterprise.home"
		 value="${appserv.home}"/>
	 <sysproperty key="verifier.xsl"
		 value="${appserv.home}/verifier/config" />
	 <!-- uncomment the following for verbose output -->
	 <!--<arg value="-v"/>-->
	 <arg value="${assemble}/${ejbjar}" />
	 <classpath path="${appserv.cpath}:${java.class.path}"/>
 </java>
</target>

Sample Results Files

Here is a sample results XML file:

<static-verification>
 <ejb>
	 <failed>
		 <test>
			 <test-name>
tests.ejb.session.TransactionTypeNullForContainerTX
			</test-name>
			 <test-assertion>
Session bean with bean managed transaction demarcation test
			</test-assertion>
			 <test-description>
For [ TheGreeter ] Error: Session Beans [ TheGreeter ] with 
[ Bean ] managed transaction demarcation should not have 
container transactions defined.
			 </test-description>
		 </test>
	 </failed>
 </ejb>
...
</static-verification>

Here is a sample results TXT file:

---------------------------
STATIC VERIFICATION RESULTS
---------------------------
----------------------------------
NUMBER OF FAILURES/WARNINGS/ERRORS
----------------------------------

# of Failures : 3
# of Warnings : 6
# of Errors : 0
-----------------------------
RESULTS FOR EJB-RELATED TESTS
-----------------------------
--------------
FAILED TESTS :
--------------

Test Name : tests.ejb.session.TransactionTypeNullForContainerTX
Test Assertion : Session bean with bean managed transaction demarcation test
Test Description : For [ TheGreeter ]
Error: Session Beans [ TheGreeter ] with [ Bean ] managed transaction 
demarcation should not have container transactions defined.

...
---------------
PASSED TESTS :
---------------

Test Name : tests.ejb.session.ejbcreatemethod.EjbCreateMethodStatic
Test Assertion : Each session Bean must have at least one non-static 
ejbCreate method test
Test Description : For [ TheGreeter ] For EJB Class 
[ samples.helloworld.ejb.GreeterEJB ] method [ ejbCreate ] 
[ samples.helloworld.ejb.GreeterEJB ] properly declares non-static 
ejbCreate(...) method.

...
-----------
WARNINGS :
-----------

Test Name : tests.ejb.businessmethod.BusinessMethodException
Test Assertion : Enterprise bean business method throws RemoteException test
Test Description :

Test Name : tests.ejb.ias.beanpool.IASEjbBeanPool
Test Assertion :
Test Description : WARNING [IAS-EJB ejb] : bean-pool should be defined for 
Stateless Session and Message Driven Beans

...
---------------------
NOTAPPLICABLE TESTS :
---------------------

Test Name : tests.ejb.entity.pkmultiplefield.PrimaryKeyClassFieldsCmp
Test Assertion : Ejb primary key class properly declares all class fields 
within subset of the names of the container-managed fields test.
Test Description : For [ TheGreeter ] class com.sun.enterprise.tools.
verifier.tests.ejb.entity.pkmultiplefield.PrimaryKeyClassFieldsCmp 
expected Entity bean, but called with Session.

Test Name : tests.ejb.entity.ejbcreatemethod.EjbCreateMethodReturn
Test Assertion : Each entity Bean can have zero or more ejbCreate 
methods which return primary key type test
Test Description : For [ TheGreeter ] class com.sun.enterprise.tools.
verifier.tests.ejb.entity.ejbcreatemethod.EjbCreateMethodReturn 
expected Entity bean, but called with Session bean.

...
-----------------------------------
RESULTS FOR OTHER XML-RELATED TESTS
-----------------------------------
---------------
PASSED TESTS :
---------------

Test Name : tests.dd.ParseDD
Test Assertion : Test parses the deployment descriptor using a SAX 
parser to avoid the dependency on the DOL
Test Description : PASSED [EJB] : [ remote ] and [ home ] tags present.
PASSED [EJB]: session-type is Stateless.
PASSED [EJB]: trans-attribute is NotSupported.
PASSED [EJB]: transaction-type is Bean.

...

Deploying Modules and Applications

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

• Deployment Errors

• The Deployment Life Cycle

• Tools for Deployment

• Deployment by Module or Application

• Deploying a WAR Module

• Deploying an EJB JAR Module

• Deploying a Lifecycle Module

• Deploying an Application Client

• Deploying a J2EE CA Resource Adapter

• Access to Shared Frameworks

Deployment Errors

If an error occurs during deployment, the application or module is not deployed. If a module within an application contains an error, the entire application is not deployed. This prevents a partial deployment that could leave the server in an inconsistent state.

The Deployment Life Cycle

After an application is initially deployed, it can be modified and reloaded, redeployed, disabled, re-enabled, and finally undeployed (removed from the server). This section covers the following topics related to the deployment life cycle:

• Dynamic Deployment

• Disabling a Deployed Application or Module

• Dynamic Reloading

• Automatic Deployment

You can overwrite a previously deployed application by using the --force option of asadmin deploy or by checking the appropriate box in the Administration Console during deployment. However, you must remove a preconfigured resource before you can update it.

Dynamic Deployment

You can deploy, redeploy, and undeploy an application or module without restarting the server. This is called dynamic deployment. Although primarily for developers, dynamic deployment can be used in operational environments to bring new applications and modules online without requiring a server restart.

Whenever a redeployment is done, the sessions at that transit time become invalid. The client must restart the session.

Disabling a Deployed Application or Module

You can disable a deployed application or module without removing it from the server. Disabling an application makes it inaccessible to clients.

To disable an application or module using the asadmin disable command, see the Sun Java System Application Server Platform Edition 8.2 Reference Manual.

To disable an application or module in the Administration Console

1. Open the Applications component.

2. Go to the page for the type of application or module.

   For example, for a web application, go to the Web Applications page.

3. Click on the name of the application or module you wish to disable.

4. Uncheck the Status Enabled box.

See Also

For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

Dynamic Reloading

If dynamic reloading is enabled (it is by default), you do not have to redeploy an application or module when you change its code or deployment descriptors. All you have to do is copy the changed JSP or class files into the deployment directory for the application or module. The server checks for changes periodically and redeploys the application, automatically and dynamically, with the changes.

This is useful in a development environment, because it allows code changes to be tested quickly. In a production environment, however, dynamic reloading might degrade performance. In addition, whenever a reload is done, the sessions at that transit time become invalid. The client must restart the session.

To enable dynamic reloading in the Administration Console

1. Select the Application Settings component under the relevant configuration.

2. Check the Reload Enabled box to enable dynamic reloading.

3. Enter a number of seconds in the Reload Poll Interval field.

   This sets the interval at which applications and modules are checked for code changes and dynamically reloaded. The default is 2.

See Also

For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

To reload code or deployment descriptor changes

1. Create an empty file named .reload at the root of the deployed application or module.

   For an application:

   domain-dir/applications/j2ee-apps/app-name/.reload

   For an individually deployed module:

   domain-dir/applications/j2ee-modules/module-name/.reload

2. Explicitly update the .reload file’s timestamp (touch .reload in UNIX) each time you make changes.

Automatic Deployment

Automatic deployment, also called autodeployment, involves copying an application or module file (JAR, WAR, RAR, or EAR) into a special directory, where it is automatically deployed by the Application Server. To undeploy an automatically deployed application or module, simply remove its file from the special autodeployment directory. This is useful in a development environment, because it allows new code to be tested quickly.

Autodeployment is enabled by default.

To enable and configure or to disable autodeployment

1. Select the Application Settings component under the relevant configuration.

2. Check the Auto Deploy Enabled box to enable autodeployment, or uncheck this box to disable autodeployment.

3. Enter a number of seconds in the Auto Deploy Poll Interval field.

   This sets the interval at which applications and modules are checked for code changes and dynamically reloaded. The default is 2.

4. You can change the Auto Deploy Directory if you like.

   You can enter an absolute or relative path. A relative path is relative to domain-dir. The default is domain-dir/autodeploy.

5. You can check the Verifier Enabled box to verify your deployment descriptor files. This is optional.

   For details about the verifier, see The Deployment Descriptor Verifier.

6. Check the Precompile Enabled box to precompile any JSP files.

See Also

For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

Tools for Deployment

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

• Apache Ant

• The deploytool

• JSR 88

• The asadmin Command

• The Administration Console

Apache Ant

Ant can help you assemble and deploy modules and applications. For details, see asant Assembly and Deployment Tool.

The deploytool

You can use the deploytool, provided with Application Server, to assemble J2EE applications and modules, configure deployment parameters, perform simple static checks, and deploy the final result. For more information about using the deploytool, see the J2EE 1.4 Tutorial at http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html.

JSR 88

You can write your own JSR 88 client to deploy applications to the Application Server. For more information, see the JSR 88 page at http://jcp.org/en/jsr/detail?id=88.

See Naming Standards for application and module naming considerations.

The asadmin Command

You can use the asadmin deploy or asadmin deploydir command to deploy or undeploy applications and individually deployed modules on local servers. For details, see the Sun Java System Application Server Platform Edition 8.2 Reference Manual.

To deploy a lifecycle module, see Deploying a Lifecycle Module.

On Windows, if you are deploying a directory on a mapped drive, you must be running the Application Server as the same user to which the mapped drive is assigned, or the Application Server won’t see the directory.

The Administration Console

You can use the Administration Console to deploy modules and applications to both local and remote Application Server sites.

To use the Administration Console for deployment

1. Open the Applications component.

2. Go to the page for the type of application or module.

   For example, for a web application, go to the Web Applications page.

3. Click on the Deploy button.

   You can also undeploy, enable, or disable an application or module from this page.

See Also

For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

To deploy a lifecycle module, see Deploying a Lifecycle Module.

Deployment by Module or Application

You can deploy applications or individual modules that are independent of applications. The runtime and file system implications of application-based or individual module-based deployment are described in Runtime Environments.

Individual module-based deployment is preferable when components need to be accessed by:

• Other modules

• J2EE Applications

• ACC clients (Module-based deployment allows shared access to a bean from an ACC client, a servlet, or an EJB component.)

Modules can be combined into an EAR file and then deployed as a single module. This is similar to deploying the modules of the EAR independently.

Deploying a WAR Module

You deploy a WAR module as described in Tools for Deployment.

You can precompile JSP files during deployment by checking the appropriate box in the Administration Console or by using the --precompilejsp option of the asadmin deploy or asadmin deploydir command. The sun-appserv-deploy and sun-appserv-jspc Ant tasks also allow you to precompile JSP files.

You can keep the generated source for JSP files by adding the -keepgenerated flag to the jsp-config element in sun-web.xml. If you include this property when you deploy the WAR module, the generated source is kept in domain-dir/generated/jsp/j2ee-apps/app-name/module-name if it is in an application or domain-dir/generated/jsp/j2ee-modules/module-name if it is in an individually deployed web module.

For more information about JSP precompilation, see Options for Compiling JSP Files jsp-config.

Deploying an EJB JAR Module

You deploy an EJB JAR module as described in Tools for Deployment.

You can keep the generated source for stubs and ties by adding the -keepgenerated flag to the rmic-options attribute of the java-config element in domain.xml. If you include this flag when you deploy the EJB JAR module, the generated source is kept in domain-dir/generated/ejb/j2ee-apps/app-name/module-name if it is in an application or domain-dir/generated/ejb/j2ee-modules/module-name if it is in an individually deployed EJB JAR module. For more information about the -keepgenerated flag, see the Sun Java System Application Server Platform Edition 8.2 Administration Reference.

Generation of stubs and ties is performed asynchronously, so unless you request their generation during deployment (for example, using the --retrieve option of the asadmin deploy command), stubs and ties are not guaranteed to be available immediately after deployment. You can use the asadmin get-client-stubs command to retrieve the stubs and ties whether or not you requested their generation during deployment. For details, see the Sun Java System Application Server Platform Edition 8.2 Reference Manual.

Deploying a Lifecycle Module

For general information about lifecycle modules, see Chapter 10, Developing Lifecycle Listeners.

You can deploy a lifecycle module using the following tools:

• In the Administration Console, open the Applications component and go to the Lifecycle Modules page. For details, see the Sun Java System Application Server Platform Edition 8.2 Administration Guide.

• Use the asadmin create-lifecycle-module command. For details, see the Sun Java System Application Server Platform Edition 8.2 Reference Manual.

If the is-failure-fatal setting is set to true (the default is false), lifecycle module failure prevents server initialization or startup, but not shutdown or termination.

Deploying an Application Client

Deployment is only necessary for application clients that communicate with EJB components.

To deploy an application client

1. Assemble the necessary client files.

2. Assemble the EJB components to be accessed by the client.

3. Package the client and EJB components together in an application.

4. Deploy the application as described in Tools for Deployment.

5. Retrieve the client JAR file.

   The client JAR file contains the ties and necessary classes for the ACC client.

   You can use the --retrieve option to get the client JAR file.

   You can also use the asadmin get-client-stubs command to retrieve the stubs and ties whether or not you requested their generation during deployment. For details, see the Sun Java System Application Server Platform Edition 8.2 Reference Manual.

6. Copy the client JAR file to the client machine, and set the APPCPATH environment variable on the client to point to this JAR.

Next Steps

To execute the client on the Application Server machine to test it, use the appclient script in the install-dir/bin directory.The only required option is -client. For example:

appclient -client converterClient.jar

The -xml parameter specifies the location of the sun-acc.xml file.

See Also

For more detailed information about the appclient script, see Chapter 8, Developing Java Clients.

To prepare another machine for executing an application client

1. You can use the package-appclient script in the install-dir/bin directory to create the ACC package JAR file. This is optional.

   This JAR file is created in the install-dir /lib/appclient directory.

2. Copy the ACC package JAR file to the client machine and unjar it.

3. Configure the sun-acc.xml file.

   This file is located in the appclient/appserv/lib/appclient directory by default if you used the package-appclient script.

4. Configure the asenv.conf (asenv.bat on Windows) file.

   This file is located in appclient/appserv/bin by default if you used the package-appclient script.

5. Copy the client JAR file to the client machine.

   You are now ready to execute the client.

See Also

For more detailed information about the package-appclient script, see Chapter 8, Developing Java Clients.

Deploying a J2EE CA Resource Adapter

You deploy a connector module as described in Tools for Deployment. After deploying the module, you must configure it as described in Chapter 9, Developing Connectors.

Access to Shared Frameworks

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

asant Assembly and Deployment Tool

Apache Ant 1.6.5 is provided with Application Server and can be launched from the bin directory using the command asant. The Application Server also provides server-specific tasks for deployment, which are described in this section.

Make sure you have done these things before using asant:

• Include install-dir/bin in the PATH environment variable (/usr/sfw/bin for Sun Java Enterprise System on Solaris). The Ant script provided with the Application Server, asant, is located in this directory. For details on how to use asant, see the Sun Java System Application Server Platform Edition 8.2 Reference Manual and the sample applications documentation in the install-dir/samples/docs/ant.html file.

• If you are executing platform-specific applications, such as the exec or cvs task, the ANT_HOME environment variable must be set to the Ant installation directory.

  • The ANT_HOME environment variable for Sun Java Enterprise System must include the following:

    • /usr/sfw/bin - the Ant binaries (shell scripts)

    • /usr/sfw/doc/ant - HTML documentation

    • /usr/sfw/lib/ant - Java classes that implement Ant

  • The ANT_HOME environment variable for all other platforms is install-dir/lib.

• Set up your password file. The argument for the passworfile option of each Ant task is a file. This file contains the password attribute name and its value, in the following format:

  AS_ADMIN_PASSWORD=password
  

  For more information about password files, see the Sun Java System Application Server Platform Edition 8.2 Reference Manual.

This section covers the following asant-related topics:

• asant Tasks for Sun Java System Application Server

• Reusable Subelements

For more information about Ant, see the Apache Software Foundation web site at http://ant.apache.org/.

For information about standard Ant tasks, see the Ant documentation at http://ant.apache.org/manual/.

asant Tasks for Sun Java System Application Server

Use the asant tasks provided by the Application Server for assembling, deploying, and undeploying modules and applications, and for configuring the server. The tasks are as follows:

• sun-appserv-deploy

• sun-appserv-undeploy

• sun-appserv-component

• sun-appserv-admin

• sun-appserv-jspc

• sun-appserv-update

sun-appserv-deploy

Deploys any of the following.

• Enterprise application (EAR file)

• Web application (WAR file)

• Enterprise Java Bean (EJB-JAR file)

• Enterprise connector (RAR file)

• Application client

Subelements

The following table describes subelements for the sun-appserv-deploy task. These are objects upon which this task acts.

Attributes

The following table describes attributes for the sun-appserv-deploy task.

Examples

Here is a simple application deployment script with many implied attributes:

<sun-appserv-deploy
file="${assemble}/simpleapp.ear"
passwordfile="${passwordfile}" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-deploy
 file="${assemble}/simpleapp.ear"
 name="simpleapp"
 force="true"
 precompilejsp="false"
 verify="false"
 upload="true"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 asinstalldir="${asinstalldir}" />

This example deploys multiple components to the same Application Server running on a remote server:

<sun-appserv-deploy passwordfile="${passwordfile}" host="greg.sun.com"
		 asinstalldir="/opt/sun" >
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"
	 contextroot="test"/>
 <component file="${assemble}/simplebean.jar"/>
</sun-appserv-deploy>

This example deploys the same components as the previous example because the three components match the fileset criteria, but note that it’s not possible to set some component-specific attributes. All component-specific attributes (name and contextroot) use their default values.

<sun-appserv-deploy passwordfile="${passwordfile}" host="greg.sun.com"
		 asinstalldir="/opt/sun" >
 <fileset dir="${assemble}" includes="**/*.?ar" />
</sun-appserv-deploy>

sun-appserv-undeploy

Undeploys any of the following.

• Enterprise application (EAR file)

• Web application (WAR file)

• Enterprise Java Bean (EJB-JAR file)

• Enterprise connector (RAR file)

• Application client

Subelements

The following table describes subelements for the sun-appserv-undeploy task. These are objects upon which this task acts.

Attributes

The following table describes attributes for the sun-appserv-undeploy task.

Examples

Here is a simple application undeployment script with many implied attributes:

<sun-appserv-undeploy name="simpleapp" passwordfile="${passwordfile}" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-undeploy
 name="simpleapp"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 asinstalldir="${asinstalldir}" />

This example demonstrates using the archive files (EAR and WAR, in this case) for the undeployment, using the component name (for undeploying the EJB component in this example), and undeploying multiple components.

<sun-appserv-undeploy passwordfile="${passwordfile}">
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"/>
 <component name="simplebean" />
</sun-appserv-undeploy>

sun-appserv-component

Enables or disables the following J2EE component types that have been deployed to the Application Server.

• Enterprise application (EAR file)

• Web application (WAR file)

• Enterprise Java Bean (EJB-JAR file)

• Enterprise connector (RAR file)

• Application client

You don’t need to specify the archive to enable or disable a component: only the component name is required. You can use the component archive, however, because it implies the component name.

Subelements

The following table describes subelements for the sun-appserv-component task. These are objects upon which this task acts.

Attributes

The following table describes attributes for the sun-appserv-component task.

Examples

Here is a simple example of disabling a component:

<sun-appserv-component
 action="disable"
 name="simpleapp"
 passwordfile="${passwordfile}" />

Here is a simple example of enabling a component:

<sun-appserv-component
 action="enable"
 name="simpleapp"
 passwordfile="${passwordfile}" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-component
 action="enable"
 name="simpleapp"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 asinstalldir="${asinstalldir}" />

This example demonstrates disabling multiple components using the archive files (EAR and WAR, in this case) and using the component name (for an EJB component in this example).

<sun-appserv-component action="disable" passwordfile="${passwordfile}">
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"/>
 <component name="simplebean" />
</sun-appserv-component>

sun-appserv-admin

Enables arbitrary administrative commands and scripts to be executed on the Application Server. This is useful for cases where a specific Ant task hasn’t been developed or a set of related commands are in a single script.

Subelements

none

Attributes

The following table describes attributes for the sun-appserv-admin task.

Examples

Here is an example of executing the create-jms-dest command:

<sun-appserv-admin command="create-jms-dest --desttype topic">

Here is an example of using commandfile to execute the create-jms-dest command:

<sun-appserv-admin commandfile="create_jms_dest.txt" instance="development">

The create_jms_dest.txt file contains the following:

create-jms-dest --user admin --passwordfile "${passwordfile}" --host 
localhost --port 4848 --desttype topic --target server1 simpleJmsDest

Here is an example of using explicitcommand to execute the create-jms-dest command:

<sun-appserv-admin command="create-jms-dest --user admin --passwordfile 
"${passwordfile}" --host localhost --port 4848 --desttype topic 
--target server1 simpleJmsDest">

sun-appserv-jspc

Precompiles JSP source code into Application Server compatible Java code for initial invocation by Application Server. Use this task to speed up access to JSP files or to check the syntax of JSP source code. You can feed the resulting Java code to the javac task to generate class files for the JSP files.

Subelements

none

Attributes

The following table describes attributes for the sun-appserv-jspc task.

Example

The following example uses the webapp attribute to generate Java source files from JSP files. The sun-appserv-jspc task is immediately followed by a javac task, which compiles the generated Java files into class files. The classpath value in the javac task must be all on one line with no spaces.

<sun-appserv-jspc
 destdir="${assemble.war}/generated"
 webapp="${assemble.war}"
 classpath="${assemble.war}/WEB-INF/classes"
 asinstalldir="${asinstalldir}" />
<javac
 srcdir="${assemble.war}/WEB-INF/generated"
 destdir="${assemble.war}/WEB-INF/generated"
 debug="on"
 classpath="${assemble.war}/WEB-INF/classes:${asinstalldir}/lib/
   appserv-rt.jar:${asinstalldir}/lib/appserv-ext.jar">
 <include name="**/*.java"/>
</javac>

sun-appserv-update

Enables deployed applications (EAR files) and modules (EJB JAR, RAR, and WAR files) to be updated and reloaded for fast iterative development. This task copies modified class files, XML files, and other contents of the archive files to the appropriate subdirectory of the domain-dir/applications directory, then touches the .reload file to cause dynamic reloading to occur.

This is a local task and must be executed on the same machine as the application server.

Subelements

none

Attributes

The following table describes attributes for the sun-appserv-update task.

Example

The following example updates the J2EE application foo.ear, which is deployed to the default domain, domain1.

<sun-appserv-update file="foo.ear"/>

Reusable Subelements

Reusable subelements of the Ant tasks for the Application Server are as follows. These are objects upon which the Ant tasks act.

• component

• fileset

component

Specifies a J2EE component. Allows a single task to act on multiple components. The component attributes override corresponding attributes in the parent task; therefore, the parent task attributes function as default values.

Subelements

none

Attributes

The following table describes attributes for the component element.

Examples

You can deploy multiple components using a single task. This example deploys each component to the same Application Server running on a remote server.

<sun-appserv-deploy passwordfile="${passwordfile}" host="greg.sun.com"
	 asinstalldir="/opt/s1as8" >
<component file="${assemble}/simpleapp.ear"/>
<component file="${assemble}/simpleservlet.war"
	 contextroot="test"/>
<component file="${assemble}/simplebean.jar"/>
</sun-appserv-deploy>

You can also undeploy multiple components using a single task. This example demonstrates using the archive files (EAR and WAR, in this case) and the component name (for the EJB component).

<sun-appserv-undeploy passwordfile="${passwordfile}">
<component file="${assemble}/simpleapp.ear"/
<component file="${assemble}/simpleservlet.war"/>
<component name="simplebean" />
</sun-appserv-undeploy>

You can enable or disable multiple components. This example demonstrates disabling multiple components using the archive files (EAR and WAR, in this case) and the component name (for the EJB component).

<sun-appserv-component action="disable" passwordfile="${passwordfile}">
<component file="${assemble}/simpleapp.ear"/>
<component file="${assemble}/simpleservlet.war"/>
<component name="simplebean" />
</sun-appserv-component>

fileset

Selects component files that match specified parameters. When fileset is included as a subelement, the name and contextroot attributes of the containing element must use their default values for each file in the fileset. For more information, see http://ant.apache.org/manual/CoreTypes/fileset.html.