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

---

Note –

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. This feature is available only on the default server instance.

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 Enterprise Edition 8.1 2005Q2 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 Enterprise Edition 8.1 2005Q2 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 feature is available only on the default server instance.

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 Enterprise Edition 8.1 2005Q2 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. This feature is available only on the default server instance.

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 Enterprise Edition 8.1 2005Q2 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 Enterprise Edition 8.1 2005Q2 Reference Manual. The asadmin deploydir command is available only on the default server instance.

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

---

Note –

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 Enterprise Edition 8.1 2005Q2 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.

HTTP sessions in WAR modules can be saved in a persistent store in case a server instance fails. For more information, see Distributed Sessions and Persistence and the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide.

---

Note –

After a web application is undeployed, its HttpSession information is not immediately removed if sessions are persistent. HttpSession information is removed in the subsequent cycle, when timed out sessions are removed. Therefore, you should disable a web application before undeploying it if sessions are persistent.

---

If you are setting up load balancing, web module context roots must be unique within a cluster. See the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide for more information about load balancing.

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 Enterprise Edition 8.1 2005Q2 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 Enterprise Edition 8.1 2005Q2 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 Enterprise Edition 8.1 2005Q2 Administration Guide.

• Use the asadmin create-lifecycle-module command. For details, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Reference Manual.

---

Note –

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 Enterprise Edition 8.1 2005Q2 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. If you are using the default server instance, the only required option is -client. For example:

appclient -client converterClient.jar

The -xml parameter, which specifies the location of the sun-acc.xml file, is also required if you are not using the default instance.

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.