test

Sun Java System Application Server 9.1 Application Deployment Guide

Deploying Modules and Applications

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

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.

In addition, certain warning conditions allow an application to be deployed but return a warning message to the deployment client.

The Deployment Life Cycle

After installing the Application Server and starting a domain, you can deploy (install) Java EE applications and modules. During deployment and as the application is changed, an application or module can go through the following stages:

  1. Initial Deployment

    Before deploying an application or module, start the domain.

    Deploy (install) an application or module to a specific stand-alone server instance or cluster. Because applications and modules are packaged in archive files, specify the archive file name during deployment. The default is to deploy to the default server instance server.

    If you deploy to server instances or clusters, the application or module exists in the domain’s central repository and is referenced by any clusters or server instances you deployed to as targets.

    You can also deploy to the domain using the asadmin deploy or asadmin deploydir command or the Admin Console. In the cluster profile, the preselected deployment target is server. To deploy only to the domain, specify no target. If you deploy the application or module only to the domain, it exists in the domain’s central repository, but no server instances or clusters reference it until you add references.

    Deployment is dynamic: you don’t need to restart the server instance after deploying application or module for applications to be available. If you do restart, all deployed applications and modules are still deployed and available.

  2. Enabling or Disabling

    By default, a deployed application or module is enabled, which means that it is runnable and can be accessed by clients if it has been deployed to an accessible server instance or cluster. To prevent access, disable the application or module. A disabled application or module is not uninstalled from the domain and can be easily enabled after deployment. For more information, see Disabling a Deployed Application or Module.

  3. Adding or Deleting Targets for a Deployed Application or Module

    Once deployed, the application or module exists in the central repository and can be referenced by a number of server instances and/or clusters. Initially, the server instances or clusters you deployed to as targets reference the application or module.

    To change which server instances and clusters reference an application or module after it is deployed, change an application or module’s targets using the Admin Console, or change the application references using the asadmin tool. Because the application itself is stored in the central repository, adding or deleting targets adds or deletes the same version of an application on different targets. However, an application deployed to more than one target can be enabled on one and disabled on another, so even if an application is referenced by a target, it is not available to users unless it is enabled on that target.

  4. Redeployment

    To replace a deployed application or module, redeploy it. Redeploying automatically undeploys the previously deployed application or module and replaces it with the new one.

    When redeploying through the Admin Console, the redeployed application or module is deployed to the domain, and all stand-alone or clustered server instances that reference it automatically receive the new version if dynamic reconfiguration is enabled. If using the asadmin deploy command to redeploy, specify domain as the target.

    If an application is deployed on one target only and you are redeploying using asadmin, specify the same target during redeployment.

    For production environments, perform a rolling upgrade, which upgrades the application or module without interruption in service. For more information, see To Upgrade Components Without Loss of Service in Sun Java System Application Server 9.1 High Availability Administration Guide.

  5. Undeployment

    To uninstall an application or module, undeploy it.

Deployment for Development

This section covers the following topics related to deployment for development:

Note –

You can overwrite a previously deployed application by using the --force option of asadmin deploy or asadmin deploydir or by selecting the Redeploy button in the Admin Console. 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 instances. 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 9.1 Reference Manual.

ProcedureTo Disable an Application or Module in the Admin 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 box to the left of the name of each application or module you wish to disable.

  4. Click on the Disable button.

See Also

For details, click the Help button in the Admin Console.

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. Simply 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. Deployment directories are as follows:

For an application:

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

For an individually deployed module:

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

Dynamic reloading 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.

You can also use the sun-appserv-update task with the asant utility to update an application or module. See Chapter 3, The asant Utility, in Sun Java System Application Server 9.1 Developer’s Guide.

ProcedureTo Enable Dynamic Reloading in the Admin Console

  1. To access reloading features:

    • In the developer profile:

      1. Select the Application Server component.

      2. Select the Advanced tab.

      3. Select the Applications Configuration tab.

    • In the cluster profile:

      1. Select the Stand-Alone Instances component.

      2. Select the instance named server in the table.

        This is the Admin Server.

      3. Select the Advanced tab.

  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, click the Help button in the Admin Console.

ProcedureTo 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 of a web services JSR 181 annotated file is supported. For more information, see JSR 181 and Chapter 6, Developing Web Services, in Sun Java System Application Server 9.1 Developer’s Guide.

Autodeployment is enabled by default.

ProcedureTo Enable and Configure or to Disable Autodeployment

  1. To access autodeployment features:

    • In the developer profile:

      1. Select the Application Server component.

      2. Select the Advanced tab.

      3. Select the Applications Configuration tab.

    • In the cluster profile:

      1. Select the Stand-Alone Instances component.

      2. Select the instance named server in the table.

        This is the Admin Server.

      3. Select the Advanced tab.

  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.

    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 verifier Utility.

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

See Also

For details, click the Help button in the Admin Console.

Directory Deployment

A directory containing an unpackaged application or module is sometimes called an exploded directory. To deploy a directory instead of an EAR, WAR, JAR, or RAR file, you can do one of the following:

The contents of the directory must match the contents of a corresponding Java EE archive 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. In addition, the directories holding the individual modules must be named with _jar, _war and _rar suffixes. For information about the required directory contents, see the appropriate specifications.

You can change the deployment descriptor files directly in the exploded directory. If your environment is configured to use dynamic reloading, you can also dynamically reload applications deployed from the directory. For more information, see Dynamic Reloading.

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.

Using a Deployment Plan

This feature is for advanced developers.

A deployment plan is an JAR file that contains only the deployment descriptors that are specific to the Application Server. The deployment plan is part of the implementation of JSR 88. Use a deployment plan to deploy an application or module that does not contain the deployment descriptors that are specific to the Application Server. For more information about JSR 88, see the JSR 88 page at http://jcp.org/en/jsr/detail?id=88.

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


$ asadmin deploy --user admin --deploymentplan mydeployplan.jar myrostapp.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 Application Server is at the root level. If a stand-alone EJB module contains a CMP bean, 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

Tools for Deployment

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

The asant Utility

The asant utility can help you assemble and deploy modules and applications. For details, see Chapter 3, The asant Utility, in Sun Java System Application Server 9.1 Developer’s Guide.

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.

The syntax of the URI entry for the getDeploymentManager method is as follows:

deployer:Sun:AppServer::admin-host:admin-port[:https]

The :https is not needed by default in the developer profile and needed by default in the cluster profile. For example:

deployer:Sun:AppServer::localhost:4848:https

See Naming Standards for application and module naming considerations.

The asadmin Deployment Commands

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 Directory Deployment and the Sun Java System Application Server 9.1 Reference Manual. The asadmin deploydir command is available only on the default server instance.

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

The Admin Console Deployment Pages

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

ProcedureTo Use the Admin 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. In the developer profile, you can undeploy, enable, or disable an application or module from the table on this page. In the cluster profile, click on the link in the Status column to undeploy, enable, or disable an application or module on specific targets.

  3. Click on the Deploy button.

    On this page, you type the path to the WAR, JAR, EAR, or RAR file or the exploded directory structure. You can also specify deployment settings that vary according to the type of application or module.

See Also

For details, click the Help button in the Admin Console.

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

For more information on deploying from an exploded directory structure, see Directory Deployment.

Deployment by Module or Application

You can deploy applications or individual modules that are independent of applications; see About Modules and About Applications. Individual module-based deployment is preferable when components need to be accessed by:

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 Web Service

You deploy a web service endpoint to the Application Server just as you would any servlet or stateless session bean (SLSB).

Web service management is fully supported in the Admin Console. If the deployed application or module has a web service endpoint, it is detected automatically during deployment. Once the application or module is deployed, click on the Web Service component. The table in the right frame lists deployed web service endpoints.

You can use the --registryjndiname option of the asadmin deploy or asadmin deploydir command to publish the web service as part of deployment, but this is optional. See Tools for Deployment.

To deploy a JSR 181 annotated file, use the autodeployment feature. You can compile and deploy in one step, as in the following example:


javac -cp javaee.jar -d domain-dir/autodeploy MyWS.java

For more information about JSR 181, see http://jcp.org/en/jsr/detail?id=181. For more information about autodeployment, see Automatic Deployment.

The Sun-specific deployment descriptor files sun-web.xml and sun-ejb-jar.xml provide optional web service enhancements in their webservice-endpoint and webservice-description elements.

For more information about web services, see JSR 181 and Chapter 6, Developing Web Services, in Sun Java System Application Server 9.1 Developer’s Guide.

Deploying a WAR Module

You deploy a WAR module as described in Tools for Deployment. If you do not specify a context root, the default is the name of the WAR file without the extension.

If a web application accesses a DataSource that is not specified in a resource-ref in sun-web.xml, or there is no sun-web.xml file, the resource-ref-name defined in web.xml is used. A warning message is logged recording the JNDI name used to look up the resource.

You can precompile JSP files during deployment by checking the appropriate box in the Admin Console, or by using the --precompilejsp option of the asadmin deploy or asadmin deploydir command. The asant tasks sun-appserv-deploy and sun-appserv-jspc also allow you to precompile JSP files. For more information, see Chapter 3, The asant Utility, in Sun Java System Application Server 9.1 Developer’s Guide.

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 jsp-config and Options for Compiling JSP Files in Sun Java System Application Server 9.1 Developer’s Guide.

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 in Sun Java System Application Server 9.1 Developer’s Guide and the Sun Java System Application Server 9.1 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.

Web module context roots must be unique within a server instance.

See the Sun Java System Application Server 9.1 High Availability Administration Guide for information about load balancing.

Deploying an EJB JAR Module

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

If no JNDI name for the EJB JAR module is specified in the jndi-name element immediately under the ejb element in sun-ejb-jar.xml, or there is no sun-ejb-jar.xml file, a default, non-clashing JNDI name is derived. A warning message is logged recording the JNDI name used to look up the EJB JAR module.

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 9.1 Administration Reference.

Generation of stubs and ties is performed asynchronously, so unless you request their generation during deployment, stubs and ties are not guaranteed to be available immediately after deployment. To generate stubs and ties during deployment, use the --retrieve option of the asadmin deploy or asadmin deploydir command, or check the Generate RMIStubs Enabled box in the Admin Console.

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 9.1 Reference Manual.

Deploying a Lifecycle Module

For general information about lifecycle modules, see Chapter 13, Developing Lifecycle Listeners, in Sun Java System Application Server 9.1 Developer’s Guide.

You can deploy a lifecycle module using the following tools:

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 necessary for application clients that communicate with EJB components or that use Java Web Start launch support.

Java Web Start is supported for application clients and for applications that contain application clients. It is enabled by default both in application clients and in the Application Server.

This section contains the following topics:

ProcedureTo 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. If you are using the appclient script to run the application client, retrieve the client JAR file.

    The client JAR file contains the ties and necessary classes for the application 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 9.1 Reference Manual.

  6. If you are using the appclient script to run the application client, copy the client JAR file to the client machine.

Next Steps

You can execute the client on the Application Server machine to test it in one of the following ways:

See Also

For more detailed information about Java Web Start, see Chapter 11, Developing Java Clients, in Sun Java System Application Server 9.1 Developer’s Guide.

For more detailed information about the appclient script, see the Sun Java System Application Server 9.1 Reference Manual.

ProcedureTo Prepare Another Machine for Executing an Application Client

If Java Web Start is enabled, the default URL for an application is as follows:


http://host:port/context-root

The default URL for a stand-alone application client module is as follows:


http://host:port/module-id

If the context-root or module-id is not specified during deployment, the name of the EAR or JAR file without the extension is used. For an application, the relative path to the application client JAR file is also included. If the application or module is not in EAR or JAR file format, a context-root or module-id is generated.

Regardless of how the context-root or module-id is determined, it is written to the server log. For details about naming, see Naming Standards.

To set a different URL for an application client, use the context-root subelement of the java-web-start-access element in the sun-application-client.xml file.

If Java Web Start is not enabled for the application client, follow these steps.

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

    This JAR file is created in the as-install/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 Java Web Start and the package-appclient script, see Chapter 11, Developing Java Clients, in Sun Java System Application Server 9.1 Developer’s Guide.

Undeployment of Application Clients

Once application clients are downloaded, they remain on the client until removed manually. The Java Web Start control panel provides a simple interface you can use to discard downloaded application clients that used Java Web Start. When you undeploy an application client, you can no longer use Java Web Start, or any other mechanism, to download the application client. If you try to launch an application client that was previously downloaded even though the server side of the application client is no longer present, the results depend on whether the application client has been written to tolerate such situations.

You can write your application client to detect failures in contacting server-side components and to continue running anyway. In this case, Java Web Start can run an undeployed application client as it is cached locally. For example, your application client can be written to catch and recover from a javax.naming.NamingException in locating a resource or a java.rmi.RemoteException in referring to a previously-located resource that becomes inaccessible.

Deploying a J2EE CA Connector Module

You deploy a J2EE Connector Architecture (CA) connector module as described in Tools for Deployment. After deploying the module, you must configure it as described in Chapter 12, Developing Connectors, in Sun Java System Application Server 9.1 Developer’s Guide.

Access to Shared Frameworks

When Java EE 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, the Common Classloader, or an application-specific class loader 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 Chapter 2, Class Loaders, in Sun Java System Application Server 9.1 Developer’s Guide.