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:
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:
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 PagesTM (JSPTM) 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). If the EJB component is a version 2.1 or earlier entity bean with container managed persistence, a .dbschema file and a CMP mapping descriptor, sun-cmp-mapping.xml, can be included as well.
Application Client JAR File — An application client is an Enterprise Server specific type of Java EE client. An application client supports the standard Java EE Application Client specifications, and in addition, supports direct access to the Enterprise Server. Its deployment descriptors are application-client.xml and sun-application-client.xml.
Resource RAR File — RAR files apply to J2EE CA connectors. A connector extends the EJB container to allow access to external systems much like a device driver provides access to a peripheral device from a process hosted by an operating system. It is a portable way of allowing EJB components to access a foreign enterprise system. Each Enterprise Server connector has annotations or a Java EE XML file, ra.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.
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.
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.
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.
The Enterprise Server supports applications and 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 applications or 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 application or module are ignored.
Java EE applications or 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 applications or 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.
To check the correctness of annotations or deployment descriptors prior to deployment, see The verifier Utility.
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/.
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.
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:
If deploying using the Admin Console, specify the name in the Application Name field.
If deploying using the asadmin deploy command, the default name of the application or module is the prefix of the JAR file that you are deploying. For example, for the hello.war file, the Web application name is hello. To override the default name, specify 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, 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.
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.
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.