Sun Java System Application Server Platform Edition 9 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.

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. Because applications and modules are packaged in archive files, specify the archive file name during deployment.

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

  4. 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 by checking the appropriate box in the Admin 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 9 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 name of the application or module you wish to disable.

  4. Uncheck the Status Enabled box.

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.

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 Platform Edition 9 Developer’s Guide.

ProcedureTo Enable Dynamic Reloading in the Admin 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, 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.

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 Platform Edition 9 Developer’s Guide.

Autodeployment is enabled by default.

ProcedureTo 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.

    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 Platform Edition 9 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

For example:

deployer:Sun:AppServer::localhost:4848

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 Platform Edition 9 Reference Manual.

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.

  3. Type the path to the WAR, JAR, EAR, or RAR file or the exploded directory structure.

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

  4. Click on the Deploy button.

    You can undeploy, enable, or disable an application or module from this page. You can also change 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.

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). You can use the --registryjndiname option of the asadmin deploy 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 Platform Edition 9 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 Platform Edition 9 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 Platform Edition 9 Developer’s Guide.

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 Platform Edition 9 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 9 Reference Manual.

Deploying a Lifecycle Module

For general information about lifecycle modules, see Chapter 13, Developing Lifecycle Listeners, in Sun Java System Application Server Platform Edition 9 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 only necessary for application clients that communicate with EJB components.

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.

If you are using Java Web Start, you should deploy the application or application client as an EAR or JAR file rather than using directory deployment. Java Web Start uses JAR files, which means that the Application Server must JAR application client files during deployment, resulting in slower performance.

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 Java Web Start is not enabled for the application client, 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 9 Reference Manual.

  6. If Java Web Start is not enabled for the application client, 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

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 Platform Edition 9 Developer’s Guide.

For more detailed information about the appclient script, see the Sun Java System Application Server Platform Edition 9 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 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 Java Web Start and the package-appclient script, see Chapter 11, Developing Java Clients, in Sun Java System Application Server Platform Edition 9 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 Platform Edition 9 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 Platform Edition 9 Developer’s Guide.