Sun logo      Previous      Contents      Next     

Sun Java™ System Application Server Platform Edition 8 Administration Guide

Chapter 2
Application Deployment

This chapter explains how to deploy (install) J2EE applications on the Application Server. This chapter contains following sections:

About Deployment

The Deployment Life Cycle

After you’ve installed the Application Server and started a domain, you can deploy (install) J2EE applications and modules. During deployment, an application or module can go through the following stages:

  1. Initial Deployment

    2. You deploy (install) an application or module into a specific domain. Before you deploy an application or module, you must first start the domain. Because applications and modules are packaged in JAR files, you specify the JAR file name during deployment.

    Deployment is dynamic: you don’t need to restart the domain when you deploy an application. If you do restart the domain, all deployed applications and modules are still deployed.

  2. Enabling or Disabling

    3. By default, a deployed application or module is enabled, which means that it is runnable and can be accessed by clients. To prevent access, you can disable the application or module. A disabled application or module is not uninstalled from the domain and can be easily enabled.

  3. Redeployment

    4. To replace a deployed application or module, you redeploy it. You don’t have to undeploy and then deploy it again. Redeployment is common in a development environment, but less so in a production environment.

  4. Undeployment

    5. To uninstall an application or module, you undeploy it. Undeployment does not delete the JAR file containing the application or module.

Types of J2EE JAR Files

A software provider packages an application or module into a JAR file. To deploy the application or module, you specify the JAR file name. The content and structure of the JAR file is defined by the specifications of the J2EE platform. Types of J2EE JAR files are as follows:

The software provider might assemble an application into a single EAR file or into separate WAR, EJB JAR, and application client JAR files. With separate files, you can distribute the application by deploying it on different servers. In the administration tools, the deployment pages and commands are similar for all types of files.

Naming Conventions

In a given domain, the names of deployed applications and modules must be unique. If you deploy with the Admin Console, then you specify the name in the Application Name field. If you use the asadmin deploy command, the default name of the application or module is the prefix of the JAR file that you deploy. For example, if you deploy the hello.war file, the Web application name will be hello. You can override the default name by specifying the --name option.

Admin Console Tasks for Deploying Applications

Deploying an Enterprise Application

An enterprise application is packaged in an EAR file, a type of JAR file that contains module files such as WAR and EJB JAR files.

To deploy (install) an enterprise application:

  1. In the tree component, expand the Applications node.
  2. Select the Enterprise Applications node.
  3. On the Enterprise Applications page, click Deploy.
  4. On the Deployment page, specify the EAR file that you want to deploy.

    5. In the explanation of this step, the server machine is the host that is running the application server. The client machine is the host on which you are running the Admin Console browser. If a file or directory is said to reside on a server or client machine, it might really live on another host, but it must be accessible from the file system of the server or client machine.

    1. For the Upload File button, if the file resides on the client machine, then select Yes. If the file resides on the server machine, then select No. If you want to deploy an unpackaged application from an exploded directory, then select No. The exploded directory must reside on the server machine. Deploying from an exploded directory is for advanced developers and is not recommended for production environments.
    2. In the File Or Directory field, if you are deploying a file then click Browse and locate the file (or type the full path name of the file). If you are deploying from an exploded directory, then type the full path name of the directory.
  5. Click Next to display the Deploy Enterprise Application page.
  6. On the Deploy Enterprise Application page, specify the settings for the application.
    1. In the Application Name field, you may retain the default name, which is the prefix of the file name, or you may type another name. The application name must be unique.
    2. In the Virtual Servers, you may replace the default server. (To view the available virtual servers, in the tree component select HTTP Service -> Virtual Servers.)
    3. By default, an application is available as soon as it is deployed. If you want to disable the application so that is unavailable after deployment, deselect the Enabled checkbox.
    4. If the application has already been deployed, it will be replaced with the new application unless you deselect the Redeploy checkbox.
    5. If you want to verify the structure and contents of the file before deployment, select the Verifier checkbox. Verification of large applications can be time-consuming, but should be done if you suspect the file is corrupt or non-portable.
    6. If you want to precompile JSP pages, select the JSPs checkbox. If you do not select this checkbox, the JSP pages will be compiled at runtime when they are first accessed. Because compilation can be time-consuming, in a production environment you should select this checkbox.
  7. Click Finish to deploy the application.

Equivalent asadmin command: deploy

Deploying a Web Application

An Web application is packaged in a WAR file, a type of JAR file that contains components such as servlets and JSP pages.

To deploy (install) a Web application:

  1. In the tree component, expand the Applications node.
  2. Select the Web Applications node.
  3. On the Web Applications page, click Deploy.
  4. On the Deployment page, specify the WAR file that you want to deploy.

    5. In the explanation of this step, the server machine is the host that is running the application server. The client machine is the host on which you are running the Admin Console browser. If a file or directory is said to reside on a server or client machine, it might really live on another host, but it must be accessible from the file system of the server or client machine.

    1. For the Upload File button, if the file resides on the client machine, then select Yes. If the file resides on the server machine, then select No. If you want to deploy an unpackaged application from an exploded directory, then select No. The exploded directory must reside on the server machine. Deploying from an exploded directory is for advanced developers and is not recommended for production environments.
    2. In the File Or Directory field, if you are deploying a file then click Browse and locate the file (or type the full path name of the file). If you are deploying from an exploded directory, then type the full path name of the directory.
  5. Click Next to display the Deploy Web Application page.
  6. On the Deploy Web Application page, specify the settings for the application.
    1. In the Application Name field, you may retain the default name, which is the prefix of the file name, or you may type another name. (The default name appears if you select Yes for the Upload File button.) The application name must be unique.
    2. In the Context Root field, enter a string that identifies the Web application. In the URL of the Web application, the context root immediately follows the port number (http://host:port/context-root/...). Make sure that the context root starts with a forward slash, for example: /hello
    3. In the Virtual Servers, you may replace the default server. (To view the available virtual servers, in the tree component select HTTP Service -> Virtual Servers.)
    4. By default, an application is available as soon as it is deployed. If you want to disable the application so that is unavailable after deployment, deselect the Enabled checkbox.
    5. If the application has already been deployed, it will be replaced with the new application unless you deselect the Redeploy checkbox.
    6. If you want to verify the structure and contents of the file before deployment, select the Verifier checkbox. Verification of large applications can be time-consuming, but should be done if you suspect the file is corrupt or non-portable.
    7. If you want to precompile JSP pages, select the JSPs checkbox. If you do not select this checkbox, the JSP pages will be compiled at runtime when they are first accessed. Because compilation can be time-consuming, in a production environment you should select this checkbox.
  7. Click Finish to deploy the application.

Equivalent asadmin command: deploy

Deploying an EJB Module

An EJB Module, also called an EJB JAR file, contains enterprise beans.

To deploy (install) an EJB module:

  1. In the tree component, expand the Applications node.
  2. Select the EJB Modules node.
  3. On the EJB Module page, click Deploy.
  4. On the Deployment page, specify the JAR file that you want to deploy.

    5. In the explanation of this step, the server machine is the host that is running the application server. The client machine is the host on which you are running the Admin Console browser. If a file or directory is said to reside on a server or client machine, it might really live on another host, but it must be accessible from the file system of the server or client machine.

    1. For the Upload File button, if the file resides on the client machine, then select Yes. If the file resides on the server machine, then select No. If you want to deploy an unpackaged application from an exploded directory, then select No. The exploded directory must reside on the server machine. Deploying from an exploded directory is for advanced developers and is not recommended for production environments.
    2. In the File Or Directory field, if you are deploying a file then click Browse and locate the file (or type the full path name of the file). If you are deploying from an exploded directory, then type the full path name of the directory.
  5. Click Next to display the Deploy EJB Module page.
  6. On the Deploy EJB Module page, specify the settings for the application.
    1. In the Application Name field, you may retain the default name, which is the prefix of the file name, or you may type another name. The application name must be unique.
    2. By default, an application is available as soon as it is deployed. If you want to disable the application so that is unavailable after deployment, deselect the Enabled checkbox.
    3. If the application has already been deployed, it will be replaced with the new application unless you deselect the Redeploy checkbox.
    4. If you want to verify the structure and contents of the file before deployment, select the Verifier checkbox. Verification of large applications can be time-consuming, but should be done if you suspect the file is corrupt or non-portable.
  7. Click Finish to deploy the module.

Equivalent asadmin command: deploy

Deploying a Connector Module

A connector, also known as a resource adapter, is packaged in a type of JAR file called a RAR file.

To deploy (install) a connector module:

  1. In the tree component, expand the Applications node.
  2. Select the Connector Modules node.
  3. On the Connector Modles page, click Deploy.
  4. On the Deployment page, specify the RAR file that you want to deploy.

    5. In the explanation of this step, the server machine is the host that is running the application server. The client machine is the host on which you are running the Admin Console browser. If a file or directory is said to reside on a server or client machine, it might really live on another host, but it must be accessible from the file system of the server or client machine.

    1. For the Upload File button, if the file resides on the client machine, then select Yes. If the file resides on the server machine, then select No. If you want to deploy an unpackaged application from an exploded directory, then select No. The exploded directory must reside on the server machine. Deploying from an exploded directory is for advanced developers and is not recommended for production environments.
    2. In the File Or Directory field, if you are deploying a file then click Browse and locate the file (or type the full path name of the file). If you are deploying from an exploded directory, then type the full path name of the directory.
  5. Click Next to display the Deploy Connector Module page.
  6. On the Deploy Connector Module page, specify the settings for the application.
    1. In the Application Name field, you may retain the default name, which is the prefix of the file name, or you may type another name. The application name must be unique.
    2. In the Thread Pool Id field, you may specify the thread pool for the connector that you are deploying.
    3. By default, an application is available as soon as it is deployed. If you want to disable the application so that it is unavailable after deployment, deselect the Enabled checkbox.

      4. When you enable or disable a connector module, you also enable or disable the connector resources and connection pools that point to the module.

    4. If the application has already been deployed, it will be replaced with the new application unless you deselect the Redeploy checkbox.
    5. If you want to verify the structure and contents of the file before deployment, select the Verifier checkbox. Verification of large applications can be time-consuming, but should be done if you suspect the file is corrupt or non-portable.
  7. Click Finish to deploy the module.

Equivalent asadmin command: deploy

Creating a Lifecycle Module

A lifecycle module performs tasks when it is triggered by one or more events in the server lifecycle. These server events are: initialization, start up, ready to service requests, and shut down. Lifecycle modules are not part of the J2EE specification, but are an enhancement to the Sun Java™ System Application Server Platform Edition 8.

To create a lifecycle module:

  1. In the tree component, expand the Applications node.
  2. Select the Lifecycle Modules node.
  3. On the Lifecycle Modules page, click New.
  4. On the Create Lifecycle Module page, specify the settings:
    1. In the Name field, type a name that denotes the function of the module.
    2. In the Class Name field, type the fully qualified name of the lifecycle module’s class file.
    3. If the JAR file containing the lifecycle is in the server’s classpath, then leave the Classpath field blank. Otherwise, type the fully qualified path.
    4. In the Load Order field, type an integer greater than 100 and less than the operating system’s MAXINT value.

      5. The integer determines the order in which lifecycle modules are loaded when the server starts up. Modules with smaller integers are loaded sooner.

    5. When you start the server, it loads lifecycle modules that have already been deployed. By default, if a load fails, the server will continue the start up operation. If you want to prevent the server from starting up when a load files, then select the On Load Failure checkbox.
    6. By default, a module is available as soon as it is deployed. If you want to disable the module so that is unavailable after deployment, deselect the Enabled checkbox.
  5. Click OK.

Equivalent asadmin command: create-lifecycle-module

Deploying an Application Client Module

An application client module, also called a J2EE application client JAR file, contains the server-side routines for the client.

To deploy (install) an application client module:

  1. In the tree component, expand the Applications node.
  2. Select the App Client Modules node.
  3. On the Application Client Modules page, click Deploy.
  4. On the Deployment page, specify the JAR file that you want to deploy.

    5. In the explanation of this step, the server machine is the host that is running the application server. The client machine is the host on which you are running the Admin Console browser. If a file or directory is said to reside on a server or client machine, it might really live on another host, but it must be accessible from the file system of the server or client machine.

    1. For the Upload File button, if the file resides on the client machine, then select Yes. If the file resides on the server machine, then select No. If you want to deploy an unpackaged application from an exploded directory, then select No. The exploded directory must reside on the server machine. Deploying from an exploded directory is for advanced developers and is not recommended for production environments.
    2. In the File Or Directory field, if you are deploying a file then click Browse and locate the file (or type the full path name of the file). If you are deploying from an exploded directory, then type the full path name of the directory.
  5. Click Next to display the Deploy Application Client Module page.
  6. On the Deploy Application Client Module page, specify the settings for the application.
    1. In the Application Name field, you may retain the default name, which is the prefix of the file name, or you may type another name. The application name must be unique.
    2. If the application has already been deployed, it will be replaced with the new application unless you deselect the Redeploy checkbox.
    3. If you want to verify the structure and contents of the file before deployment, select the Verifier checkbox. Verification of large applications can be time-consuming, but should be done if you suspect the file is corrupt or non-portable.
  7. Click Finish to deploy the module.

For the client-side routines:

Equivalent asadmin command: deploy

Admin Console Tasks for Listing, Undeploying, and Enabling Applications

Listing Deployed Applications

  1. In the tree component, expand the Applications node.
  2. Expand the node for the application or module type.

To view the details of a deployed application or module you can either:

Equivalent asadmin command: list-components

Listing Subcomponents

Enterprise and Web applications contain subcomponents. For example, a Web application may contain one or more servlets. You use the same method for listing the subcomponents of Enterprise and Web applications.

To list the subcomponents of a Web application:

  1. In the tree component, expand the Applications node.
  2. Expand the Web Applications node.
  3. Select the node for a particular Web application.
  4. On the Web Application page, note the contents of the Sub Components table.

Equivalent asadmin command: list-components

Undeploying an Application

When you undeploy an applicaton or module, you uninstall it from the application server. This action will not delete the JAR file in which the application or module has been packaged.

To undeploy an application or module:

  1. In the tree component, expand the Applications node.
  2. Select the node for the type of application or module want to undeploy.
  3. In the table listing the deployed applications, select the checkbox for the application you want to undeploy.
  4. Click Undeploy.

Equivalent asadmin command: undeploy

Enabling and Disabling an Application

If a deployed application or module is enabled, it can be accessed by clients. If it is disabled, then it is still deployed but is not accessible by clients. By default, when you deploy an application or module, it is enabled because the Status checkbox on the Deploy page is selected.

To enable a deployed application or module:

  1. In the tree component, expand the Applications node.
  2. Expand the node for the application type.
  3. Select the node for the deployed application or module.
  4. Select the Status checkbox.

To disable a deployed application or module, deselect the Status checkbox.

Equivalent asadmin commands: enable and disable

Enabling and Disabling Dynamic Reloading

If dynamic reloading is enabled, the server periodically checks for changes in the files of the deployed application and automatically reloads the application with the changes. Dynamic reloading is useful in a development environment because it allows code changes to be tested quickly. In a production environment, however, dynamic reloading may degrade performance.

To configure dynamic reloading:

  1. In the tree component, select Applications.
  2. On the Applications Configuration page, you can configure the following:
    • Reload: You can enable or disable dynamic reloading with the Enabled checkbox.
    • Reload Poll Interval: You can specify how often the server checks for changes in the deployed applications.

Deployment Methods for Developers

Using Auto Deploy

The auto deploy feature enables you to deploy a pre-packaged application or module by copying it to the install_dir/domains/domain_dir/autodeploy directory. For example, you could copy a file named hello.war to the install_dir/domains/domain1/autodeploy directory. To undeploy the application, you would remove the hello.war file from the autodeploy directory.

To configure the auto deploy feature:

  1. In the tree component, select Applications.
  2. On the Applications Configuration page, you can configure the following:
    1. You can enable or disable auto deploy by selecting or deselecting the Enabled checkbox.
    2. In the Auto Deploy Poll Interval field, you specify how often the server checks the auto deploy directory for application or module files. Changing the poll interval will not affect the amount of time it takes to deploy an application or module.
    3. In the Auto Deploy Directory, if you specify the directory where you build your application, then you won’t have to copy the file to the default auto deploy directory.
    4. Verifier: To run the verifier before deployment, select the Enabled checkbox. The verifier will examine the structure and content of the file. Verification of large applications can be time-consuming.
    5. If you want to precompile JSP pages, select the JSPs checkbox. If you do not select this checkbox, the JSP pages will be compiled at runtime when they are first accessed. Because compilation can be time-consuming, in a production environment you should select this checkbox.

Deploying an Unpackaged Application From a Directory

This feature is for advanced developers.

A directory containing an unpackaged application or module is sometimes called an exploded directory. The contents of the directory must match the contents of a corresponding J2EE JAR file. For example, if you deploy a Web application from a directory, the contents of the directory must be the same as a corresponding WAR file. For information about the required directory contents, see the appropriate specifications.

You can change the deployment descriptor files directly in the exploded directory. If dynamic reloading is enabled, then the server automatically detects the changes and reloads the application. See Enabling and Disabling Dynamic Reloading.

To deploy an unpackaged application from a directory:

  1. In the Admin Console, begin the deployment process. See Deploying a Web Application.
  2. On the Deployment page, specify the following:
    1. Select No.

Equivalent asadmin command: deploydir

Using the deploytool Utility

Designed for software developers, the deploytool utility packages and deploys J2EE applications and modules. For instructions on how to use deploytool, see The J2EE 1.4 Tutorial.

Using a Deployment Plan

This feature is for advanced developers.

A deployment plan is a JAR file that contains only the deployment descriptiors that are specific to the Sun Java™ System Application Server Platform Edition 8. These deployment descriptors, for example sun-application.xml, are described in the Sun Java™ System Application Server Platform Edition 8 Developer’s Guide. The deployment plan is part of the implementation of JSR 88: J2EE Application Deployment. You use a deployment plan when you want to deploy an application or module that does not contain the deployment descriptors that are specific to the Sun Java™ System Application Server Platform Edition 8.

To deploy using a deployment plan, you specify the --deploymentplan option of the asadmin deploy command. The following command, for example, deploys the enterprise application in the myrosterapp.ear file according to the plan specified by the mydeployplan.jar file.

$ asadmin deploy --user admin ---deploymentplan mydeployplan.jar myrosterapp.ear

In the deployment plan file for an enterprise application (EAR), the sun-application.xml file is located at the root. The deployment descriptor for each module is stored according to this syntax: module-name.sun-dd-name, where the sun-dd-name depends on the module type. If a module contains a CMP mappings file, the file is named module-name.sun-cmp-mappings.xml. A .dbschema file is stored at the root level with each forward slash character (/) replaced by a pound sign (#). The following listing shows the structure of the deployment plan file for an enterprise application (EAR).

$ jar -tvf mydeployplan.jar
420 Thu Mar 13 15:37:48 PST 2003 sun-application.xml
370 Thu Mar 13 15:37:48 PST 2003 RosterClient.war.sun-web.xml
418 Thu Mar 13 15:37:48 PST 2003 roster-ac.jar.sun-application-client.xml
1281 Thu Mar 13 15:37:48 PST 2003 roster-ejb.jar.sun-ejb-jar.xml
2317 Thu Mar 13 15:37:48 PST 2003 team-ejb.jar.sun-ejb-jar.xml
3432 Thu Mar 13 15:37:48 PST 2003 team-ejb.jar.sun-cmp-mappings.xml
84805 Thu Mar 13 15:37:48 PST 2003 team-ejb.jar.RosterSchema.dbschema

In the deployment plan for a web application or a module file, the deployment descriptor that is specific to the Sun Java™ System Application Server Platform Edition 8 is at the root level. If a stand-alone EJB module contains a CMP bean, then the deployment plan includes the sun-cmp-mappings.xml and .dbschema files at the root level. In the following listing, the deployment plan describes a CMP bean.

$ jar r -tvf myotherplan.jar
3603 Thu Mar 13 15:24:20 PST 2003 sun-ejb-jar.xml
3432 Thu Mar 13 15:24:20 PST 2003 sun-cmp-mappings.xml
84805 Thu Mar 13 15:24:20 PST 2003 RosterSchema.dbschema



Previous      Contents      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.