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 Java EE module is a collection of one or more Java EE components that execute in the same container type (for example, web or EJB) with annotations or deployment descriptors of that type. One descriptor is Java EE standard, the other is Application Server specific. Annotations can be used instead of Java EE standard descriptors.
Types of Java EE 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, must be included as well.
Application Client Container JAR File — An ACC client is an Application Server specific type of Java EE client. An ACC client supports the standard Java EE Application Client specifications, and in addition, supports direct access to the Application 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 Application 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 Application Server also supports lifecycle modules. See Chapter 13, Developing Lifecycle Listeners, in Sun Java System Application Server Platform Edition 9 Developer’s Guide for more information.
EJB JAR and Web modules can also be deployed separately, outside of any application, as in the following figure. EJB components are assembled in a JAR file with ejb-jar.xml and sun-ejb-jar.xml deployment descriptors. Web components are assembled in a WAR file with web.xml and sun-web.xml deployment descriptors. Both module types are deployed to the Application Server.
A Java EE application is a logical collection of one or more Java EE modules tied together by application 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.
The following diagram illustrates how components are assembled into modules and then assembled into an Application Server application and deployed. EJB components are assembled in a JAR file with ejb-jar.xml and sun-ejb-jar.xml deployment descriptors. Web components are assembled in a WAR file with 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.
Each module has an Application Server deployment descriptor and a Java EE deployment descriptor. The Application Server uses the deployment descriptors to deploy the application components and to register the resources with the Application Server.
An application consists of one or more modules, an optional Application Server deployment descriptor, and 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 Application 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 full, 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 Application 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/.
The following table shows where to find more information about the most commonly used Java EE standard deployment descriptors.Table 1–1 Java EE Standard Descriptors
Where to Find More Information
Java Platform Enterprise Edition Specification, v5, Chapter 8, “Application Assembly and Deployment” - Java EE: Application XML DTD
Java Servlet Specification, v2.5 Chapter 13, “Deployment Descriptor,” and JavaServer Pages Specification, v2.1, Chapter 7, “JSP Pages as XML Documents,” and Chapter 5, “Tag Extensions”
Enterprise JavaBeans Specification, v3.0, Chapter 16, “Deployment Descriptor”
Java Platform Enterprise Edition Specification, v5, Chapter 9, “Application Clients - Java EE: Application-client XML DTD”
Java Enterprise Edition, Connector Architecture Specification, v1.5, Chapter 10, “Packaging and Deployment.”
The Application Server uses additional deployment descriptors for configuring features specific to the Application Server. The sun-application-client.xml and sun-acc.xml files are required; all the others are optional.
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 Application 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 Application 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 Application 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 Application 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.