Chapter 1 Assembling and Deploying Applications

This chapter describes Sun Java^TM System Enterprise Server modules and how these modules are assembled. This chapter also describes tools for assembly and deployment.

The Enterprise Server modules include Java Platform, Enterprise Edition (Java EE platform) standard features and Enterprise Server specific features. Only Enterprise Server specific features are described in detail in this chapter.

The following topics are presented in this chapter:

• Overview of Assembly and Deployment

• Assembling Modules and Applications

• Deploying Modules and Applications

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.

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.

Overview of Assembly and Deployment

Application assembly (also known as packaging) is the process of combining discrete components into a single unit that can be deployed to a Java-EE-compliant application server. This section covers the following topics:

• About Modules

• Java EE Standard Annotation

• Java EE Standard Descriptors

• Enterprise Server Descriptors

• Naming Standards

• Directory Structure

About Modules

A module is a collection of one or more components that execute in the same container type (for example, web or EJB) with annotations or deployment descriptors of that type. In the Java EE modules, one descriptor is Java EE standard, the other is optional and Enterprise Server specific. Annotations can be used instead of Java EE standard descriptors.

Types of modules are as follows:

• Web Application Archive (WAR) — A web application is a collection of servlets, HTML pages, classes, and other resources that can be bundled and deployed to several Java EE application servers. A WAR file can consist of the following items: servlets, JavaServer Pages^TM (JSP^TM) files, JSP tag libraries, utility classes, static pages, client-side applets, beans, bean classes, and annotations or deployment descriptors (web.xml and sun-web.xml).

• EJB JAR File — The EJB JAR file is the standard format for assembling enterprise beans. This file contains the bean classes (home, remote, local, and implementation), all of the utility classes, and annotations or deployment descriptors (ejb-jar.xml and sun-ejb-jar.xml).

Package definitions must be used in the source code of all modules so the class loader can properly locate the classes after the modules have been deployed.

Because the information in a deployment descriptor is declarative, it can be changed without requiring modifications to source code. At run time, the Java EE server reads this information and acts accordingly.

EJB JAR and Web modules can be deployed separately, outside of any application. EJB components are assembled in a JAR file with annotations or ejb-jar.xml and sun-ejb-jar.xml deployment descriptors. Web components are assembled in a WAR file with annotations or web.xml and sun-web.xml deployment descriptors.

Java EE Standard Annotation

The Enterprise Server supports modules annotated according to the following specifications:

• JSR 250 Common Annotation Specification (http://www.jcp.org/en/jsr/detail?id=250)

• JSR 181 Annotation for Web Services Specification (http://www.jcp.org/en/jsr/detail?id=181)

• EJB 3.0 Specification (http://www.jcp.org/en/jsr/detail?id=220)

The following annotation and deployment descriptor combinations are supported:

• Java EE modules can be packaged with full Java EE 5.0 compliant standard and runtime deployment descriptors. If the standard deployment descriptors have specified the attribute metadata-complete, annotations in the module are ignored.

• Java EE modules can be fully annotated with metadata defined by the listed specifications. Annotation eliminates the need for Java EE standard deployment descriptors. In most cases, the Enterprise Server deployment descriptors are also optional.

• Java EE modules can be partially annotated with some deployment information in standard deployment descriptors. In case of conflicts, deployment descriptor values supersede the annotated metadata, but a warning message is logged.

Java EE Standard Descriptors

Java EE standard deployment descriptors are described in the Java EE specification, v5. You can find the specification at http://java.sun.com/products/. Information about the XML schemas that define Java EE standard deployment descriptors is available at http://java.sun.com/xml/ns/javaee/.

Enterprise Server Descriptors

The Enterprise Server uses additional, optional deployment descriptors for configuring features specific to the Enterprise Server.

For complete descriptions of these files, see Appendix A, Deployment Descriptor Files.

Naming Standards

Names of applications and individually deployed EJB JAR and WAR modules must be unique within an Enterprise Server domain. Modules of the same type within an application must have unique names.

If you do not explicitly specify a name, the default name is the first portion of the file name (without the .war or .jar extension). Modules of different types can have the same name within an application, because the directories holding the individual modules are named with _jar and _war suffixes. This is the case when you use the Administration Console or the asadmin command. If you use the asadmin deploy command to deploy a directory, your directory structure must follow this same convention. See Directory Deployment and Tools for Deployment.

You can specify a name in one of these ways:

• If deploying using the Administration Console, you can specify a name in the Application Name field.

• If deploying using the asadmin deploy command, you can override the default name by specifying the --name option.

Make sure your package and file names do not contain spaces or characters that are illegal for your operating system.

Using a Java package-like naming scheme is recommended for module filenames, module names as found in the <module-name> portion of the ejb-jar.xml files, and EJB names as found in the <ejb-name> portion of the ejb-jar.xml files. The use of this package-like naming scheme ensures that name collisions do not occur. The benefits of this naming practice apply not only to the Enterprise Server, but to other Java EE application servers as well.

JNDI lookup names for EJB components must also be unique.

Directory Structure

When you deploy a module, the module is expanded from the WAR or JAR file to an open directory structure. The directories are named with _jar and _war suffixes. If you use the asadmin deploy command to deploy a directory, your directory structure must follow this same convention; see Directory Deployment. Module directory structures follow the structure outlined in the Java EE specification.

Assembling Modules and Applications

Assembling (or packaging) modules and applications in Enterprise Server conforms to all of the customary Java-EE-defined specifications. The only difference is that when you assemble in Enterprise Server, you can include optional Enterprise Server specific deployment descriptors that enhance the functionality of the Enterprise Server.

For example, when you assemble an EJB JAR module, you annotate or create two deployment descriptor files with these names: ejb-jar.xml and sun-ejb-jar.xml. For more information about sun-ejb-jar.xml, see Appendix A, Deployment Descriptor Files.

The Enterprise Server provides these tools for assembling and verifying a module or an application:

• The NetBeans IDE

The NetBeans IDE

You can use the NetBeans^TM Integrated Development Environment (IDE), or another IDE, to assemble Java EE applications and modules. The GlassFish edition of the Enterprise Server is bundled with the NetBeans 6.1 IDE. For more information about using the NetBeans IDE, see http://www.netbeans.org.

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

• The Deployment Life Cycle

• Deployment for Development

• Tools for Deployment

• Deploying a Web Service

• Deploying a WAR Module

• Deploying an EJB JAR Module

• Access to Shared Frameworks

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:

• Dynamic Deployment

• Disabling a Deployed Application or Module

• Dynamic Reloading

• Automatic Deployment

• Directory Deployment

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.

To 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

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.

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

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

To 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:

• Use the Administration Console as described in The Administration Console Deployment Pages and enter a path to an exploded directory instead of a path to an archive file.

• Use the asadmin deploy command and specify a path to an exploded directory instead of a path to an archive file. See the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.

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.

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

• The Administration Console Deployment Pages

The asadmin Deployment Commands

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

• deploy — Deploys a web or EJB module. If the module is already deployed, you can force redeployment by setting the --force option to true. You can also deploy a module in an expanded directory structure. See Directory Deployment.

• redeploy — Redeploys a web or EJB module that is already deployed. 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.

• undeploy — Undeploys a web or EJB module.

• disable — Immediately disables a web or EJB module. Disabling a web module makes it inaccessible to clients.

• enable — Immediately enables a web or EJB module.

• list-components — Lists all deployed web or EJB modules.

• deploydir — Deploys a web or EJB module from an expanded directory structure. Deprecated; use asadmin deploy instead.

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.

To Use the Administration Console for Deployment

1. Open the Applications component.

2. Go to the page for the type of application or module.

   For example, for a web application, go to the Web Applications page. 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

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

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.