test

Sun GlassFish Enterprise Server v3 Prelude Application Deployment Guide

Deploying Modules and Applications

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

Deployment Errors

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

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

The Deployment Life Cycle

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

  1. Initial Deployment

    Before deploying a module, start the domain.

    Because modules are packaged in archive files, specify the archive file name during deployment.

    Deployment is dynamic: you don’t need to restart the server after deploying a module. If you do restart, all deployed modules are still deployed and available.

  2. Enabling or Disabling

    By default, a deployed module is enabled, which means that it is runnable. To prevent access, disable the application or module. A disabled 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 module, redeploy it. Redeploying automatically undeploys the previously deployed module and replaces it with the new one.

  4. Undeployment

    To uninstall a module, undeploy it.

Deployment for Development

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

Note –

You can overwrite a previously deployed module by using the asadmin redeploy command, the --force option of asadmin deploy, or the Redeploy button in the Administration Console. However, you must remove a preconfigured resource before you can update it.

Dynamic Deployment

You can deploy, redeploy, and undeploy a 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 unless you use the keepSessions=true property of the asadmin redeploy command. For example:


asadmin redeploy --properties keepSessions=true --name hello.war

For details, see the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.

Keep Sessions is also a checkbox option when you redeploy using the Administration Console. For details, click the Help button in the Administration Console.

Disabling a Deployed Application or Module

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

To disable a module using the asadmin disable command, see the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.

ProcedureTo Disable a Module in the Administration Console

  1. Open the Applications component.

  2. Go to the page for the type of 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 module you wish to disable.

  4. Click on the Disable button.

See Also

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

Dynamic Reloading

If dynamic reloading is enabled (it is by default), you do not have to redeploy a module when you change its code or deployment descriptors. Simply copy the changed class files or descriptors into the deployment directory for the module. Then update the timestamp of a file named .reload as described in To Reload Code or Deployment Descriptor Changes. The server checks for changes periodically and redeploys the module, automatically and dynamically, with the changes. Deployment directories are as follows:

domain-dir/applications/module-name
Note –

Deployment directories may change between Enterprise Server releases.

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. JSP file changes don't need to be dynamically reloaded. Modified JSP files are automatically recompiled and reloaded when they are accessed.

ProcedureTo Enable Dynamic Reloading in the Administration Console

  1. Select the Application Server component.

  2. Select the Advanced tab.

  3. Select the Applications Configuration tab.

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

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

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

See Also

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

ProcedureTo Reload Code or Deployment Descriptor Changes

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

    domain-dir/applications/module-name/.reload
    Note –

    Deployment directories may change between Enterprise Server releases.

  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 a module file (JAR, WAR) into a special directory, where it is automatically deployed by the Enterprise Server. To undeploy an automatically deployed module, simply remove its file from the special autodeployment directory. This is useful in a development environment, because it allows new code to be tested quickly. Autodeployment is enabled by default.

Autodeployment of a web services JSR 181 annotated file is supported. For more information, see JSR 181 and Chapter 5, Developing Web Services, in Sun GlassFish Enterprise Server v3 Prelude Developer’s Guide.

Autodeployment is enabled by default.

ProcedureTo Enable and Configure or to Disable Autodeployment

  1. Select the Application Server component.

  2. Select the Advanced tab.

  3. Select the Applications Configuration tab.

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

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

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

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

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

See Also

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

Directory Deployment

A directory containing an unpackaged module is sometimes called an exploded directory. To deploy a directory instead of an EAR or WAR, 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 modules must be named with _jar and _war suffixes. For information about the required directory contents, see the appropriate specifications.

The directory must be accessible to the machine on which the Enterprise Server runs.

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 modules 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 Enterprise Server as the same user to which the mapped drive is assigned, or the Enterprise Server won’t see the directory.

Tools for Deployment

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

The asadmin Deployment Commands

You can use the following asadmin commands to deploy or undeploy web or EJB modules on local servers.

For details, see the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.

The Administration Console Deployment Pages

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

ProcedureTo 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. You can undeploy, enable, or disable an application or module from the table on this page.

  3. Click on the Deploy button.

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

See Also

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

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

Deploying a Web Service

Note –

Web services are not supported unless the optional Metro (JSR 109) add-on component is downloaded from the Update Tool. Without the Metro component, a servlet or EJB module cannot be a web service endpoint, and the sun-web.xml and sun-ejb-jar.xml elements related to web services are ignored.

For information about the Update Tool, see the Sun GlassFish Enterprise Server v3 Prelude Installation Guide.

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

Web service management is fully supported in the Administration Console. If the deployed module has a web service endpoint, it is detected automatically during deployment. Once the 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 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 5, Developing Web Services, in Sun GlassFish Enterprise Server v3 Prelude 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 Administration Console, or by using the --precompilejsp option of the asadmin deploy command.

You can keep the generated source for JSP files by adding the keepgenerated flag to the jsp-config element in sun-web.xml. For example:

<sun-web-app>
   ...
   <jsp-config>
      <property name=keepgenerated value=true />
   </jsp-config>
</sun-web-app>

If you include this property when you deploy the WAR module, the generated source is kept in domain-dir/generated/jsp/module-name.

For more information about JSP precompilation, see jsp-config.

If you deploy a web application and don't specify any assigned virtual servers, the web application is assigned to all currently defined virtual servers. If you then create additional virtual servers and want to assign existing web applications to them, you must redeploy the web applications. For more information about virtual servers, see virtual-server in Sun GlassFish Enterprise Server v3 Prelude Administration Reference.

Whenever a redeployment is done, the sessions at that transit time become invalid unless you use the keepSessions=true property of the asadmin redeploy command. For example:


asadmin redeploy --properties keepSessions=true --name hello.war

For details, see the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.

Keep Sessions is also a checkbox option when you redeploy using the Administration Console. For details, click the Help button in the Administration Console.

Web module context roots must be unique within the server.

Deploying an EJB JAR Module

Note –

For GlassFish v3 Prelude, EJB modules are not supported unless the optional EJB container add-on component is downloaded from the Update Tool. Only stateless session beans with local interfaces and entity beans that use the Java Persistence API are supported. Stateful, message-driven, and EJB 2.0 and 2.1 entity beans are not supported. Remote interfaces and remote business interfaces for any of the bean types are not supported. The sun-ejb-jar.xml elements related to these features are ignored.

For information about the Update Tool, see the Sun GlassFish Enterprise Server v3 Prelude Installation Guide.

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.

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 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 GlassFish Enterprise Server v3 Prelude Developer’s Guide.