Sun GlassFish Enterprise Server 2.1 Application Deployment Guide

Overview of Assembly and Deployment

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

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. One descriptor is standard, the other is optional and Enterprise Server specific. Annotations can be used instead of standard descriptors.

Types of modules are as follows:

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.

The Enterprise Server also supports lifecycle modules. See Chapter 13, Developing Lifecycle Listeners, in Sun GlassFish Enterprise Server 2.1 Developer’s Guide for more information.

EJB JAR, Web, and application client modules can also be deployed separately, outside of any application. The following figure shows separately deployed EJB JAR, Web, and application client modules. 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. Application client components are assembled in a JAR file with application-client.xml and sun-application-client.xml deployment descriptors. These module types are deployed to the Enterprise Server.

Figure 1–1 Module Assembly and Deployment

Figure shows EJB, Web, and Application Client module
assembly and deployment.

About Applications

An application is a logical collection of one or more modules tied together by application annotations or deployment descriptors. Components can be assembled at either the module or the application level. Components can also be deployed at either the module or the application level.

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. An application client is assembled in a JAR file with application-client.xml and sun-application-client.xml deployment descriptors. A resource adapter is assembled in a RAR file with a ra.xml deployment descriptor. All modules are assembled in an EAR file and deployed to the Application Server. The following figure shows EJB JAR, Web, application client, and connector modules in a Java EE application.

Figure 1–2 Application Assembly and Deployment

Figure shows Java EE application assembly and
deployment.

Each Java EE module has an optional Enterprise Server deployment descriptor and annotations or a Java EE deployment descriptor. The Enterprise Server uses the annotations or deployment descriptors to deploy the application components and to register the resources with the Enterprise Server.

An application consists of one or more modules, an optional Enterprise Server deployment descriptor, and annotations or a Java EE application deployment descriptor. All items are assembled, using the Java ARchive (.jar) file format, into one file with an extension of .ear.

Java EE Standard Annotation

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

The following annotation and deployment descriptor combinations are supported:

To check the correctness of annotations or deployment descriptors prior to deployment, see The verifier Utility.

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.

To check the correctness of these deployment descriptors prior to deployment, see The verifier Utility.

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

Naming Standards

Names of applications and individually deployed EJB JAR, WAR, and connector RAR modules must be unique within an Enterprise Server domain. Modules of the same type within an application must have unique names. In addition, for entity beans that use CMP,.dbschema file names must be unique within an application.

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, _war and _rar suffixes. This is the case when you use the Admin Console or the asadmin command. See Tools for Deployment.

You can specify a name in one of these ways:

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, EAR 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. Establishing a consistent naming convention might help. For example, appending the application name and the module name to the EJB name is one way to guarantee unique names. In this case, mycompany.pkging.pkgingEJB.MyEJB would be the JNDI name for an EJB in the module pkgingEJB.jar, which is packaged in the application pkging.ear.

If you are writing your own JSR 88 client to deploy applications to the Enterprise Server using the following API, the name of the application is taken from the display-name entry in the Java EE standard deployment descriptor, because there is no file name in this case. If the display-name entry is not present, the Enterprise Server creates a temporary file name and uses that name to deploy the application.

javax.enterprise.deploy.spi.DeploymentManager.distribute(Target[], InputStream, InputStream)

Neither the Admin Console nor the asadmin command uses this API.


Note –

Use of the following JSR 88 API is preferred. In this case, the name is derived from the file name as previously described.

javax.enterprise.deploy.spi.DeploymentManager.distribute(Target[], File, File)

For more information about JSR 88, see the JSR 88 page at http://jcp.org/en/jsr/detail?id=88.

Directory Structure

When you deploy an application, the application is expanded from the EAR file to an open directory structure. The directories holding the individual modules are named with _jar, _war and _rar suffixes. If you use the asadmin deploydir command to deploy a directory instead of an EAR file, your directory structure must follow this same convention. Module and application directory structures follow the structure outlined in the Java EE specification.