Assembly, also known as packaging, is the process of combining discrete components into a single unit that can be installed on an application server. The Enterprise Server assembly process conforms to the customary Java EE specifications. The only difference is that when you assemble applications or modules in Enterprise Server, you can include optional Enterprise Server–specific deployment descriptors that enhance functionality.
Deployment is the process of using a deployment tool to specify location-specific information, such as a list of local users that can access the application, or the name of the local database. The deployment tool expands the archive file into an open directory structure that is ready for users. Enterprise Server deployment tools are described in About Deployment Tools.
The following topics are addressed here:
Various Java EE module types, such as connector module, web module, EJB module, application client module, can be deployed in the following ways:
Archive Deployment. Deploys the application as an archive file. For instructions, see To Deploy an Application or Module.
Dynamic Reloading. Redeploys the application by creating or modifying a special .reload file in the applications repository. For instructions, see To Reload Changes to Applications or Modules Dynamically.
Automatic Deployment. Deploys the application archive that is placed in the autodeployment directory. For instructions, see To Deploy an Application or Module Automatically.
Directory Deployment. Deploys the application in a directory format. For instructions, see To Deploy an Application or Module in a Directory Format.
A deployment plan, which deploys a portable archive along with a deployment plan containing Enterprise Server– specific deployment descriptors, can apply to any of these deployment techniques. For instructions, see To Deploy an Application or Module by Using a Deployment Plan.
There are two work situations that require different safeguards and processes:
A development environment provides a loose set of tools and work spaces for a relatively small number of developers who are creating and testing applications and modules.
A production environment provides a stable, protected environment where applications are tuned to maximum efficiency for business use rather than for development.
Some deployment methods that are used effectively in a development environment should not be used in production. For example, dynamic reloading is a quick way for developers to reload an application, but might degrade performance in a production environment. In addition, whenever a reload is done, the sessions that are in transit become invalid, which might not be a concern for development, but can be a serious matter in production. The client must restart the session, another negative in a production environment.
A deployment descriptor is an XML file that describes how a Java EE application or module should be deployed. Each deployment descriptor XML file has a corresponding Document Type Definition (DTD) file or schema (XSD) file, which defines the elements, data, and attributes that the deployment descriptor file can contain. The deployment descriptor directs a deployment tool to deploy a module or application with specific container options, and also describes specific configuration requirements that you must resolve.
Because the information in a deployment descriptor is declarative, it can be changed without requiring modifications to source code. At run time, Enterprise Server reads the information in the deployment descriptor and deploys the application or module as directed.
The following types of deployment descriptors are associated with Enterprise Server:
Java EE Standard Descriptors. Java EE standard deployment descriptors are described in the Java EE 6 specification. 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. Enterprise Server provides optional deployment descriptors for configuring features that are specific to Enterprise Server. For example, when you assemble an EJB module, you annotate or create two Enterprise Server–specific deployment descriptor files with these names: ejb-jar.xml and sun-ejb-jar.xml. For complete descriptions of these files and their elements, see Appendix B, Enterprise Server Deployment Descriptor Files and Appendix C, Elements of the Enterprise Server Deployment Descriptors.
Unless otherwise stated, settings in the Enterprise Server deployment descriptors override corresponding settings in the Java EE standard descriptors and in the Enterprise Server configuration. For more information about the domain configuration file, see Sun GlassFish Enterprise Server v3 Domain File Format Reference.
An annotation, also called metadata, enables a declarative style of programming. You can specify information within a class file by using annotations. When the application or module is deployed, the information can either be used or overridden by the deployment descriptor. Enterprise Server supports annotation 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.1 Specification (http://www.jcp.org/en/jsr/detail?id=318)
Java EE applications or modules can be packaged with full Java EE 6 compliant standard and runtime deployment descriptors. If the standard deployment descriptors have specified the metadata-complete attribute, annotations in the 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 not needed.
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, and a warning message is logged.
A module is a collection of one or more Java EE components that run in the same container type, such as a web container or EJB container. The module uses annotations or deployment descriptors of that container type. You can deploy a module alone or as part of an application.
The following topics are addressed here:
Enterprise Server supports the following types of modules:
Web Module. A web module, also known as a web application, is a collection of servlets, EJBs, HTML pages, classes, and other resources that you can bundle and deploy to several Java EE application servers. A web application archive (WAR) file is the standard format for assembling web applications. 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, enterprise bean classes, plus annotations or web deployment descriptors (web.xml and sun-web.xml).
EJB Module. An EJB module is a deployable software unit that consists of one or more enterprise beans, plus an EJB deployment descriptor. A Java archive (JAR) file is the standard format for assembling enterprise beans. An EJB JAR 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 (CMP), you can also include a .dbschema file and a CMP mapping descriptor (sun-cmp-mapping.xml).
Connector Module. A connector module, also known as a resource adapter module, is a deployable software unit that provides a portable way for EJB components to access foreign enterprise information system (EIS) data. A connector module consists of all Java interfaces, classes, and native libraries for implementing a resource module, plus a resource deployment descriptor. A resource adapter archive (RAR) is the standard format for assembling connector modules. Each Enterprise Server connector has annotations or a deployment descriptor file (ra.xml).
After deploying a J2EE connector module, you must configure it as described in Chapter 12, Developing Connectors, in Sun GlassFish Enterprise Server v3 Application Development Guide.
Application Client Module. An application client module is a deployable software unit that consists of one or more classes, and application client deployment descriptors (application-client.xml and sun-application-client.xml). An application client JAR file applies to 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 Enterprise Server.
Lifecycle Module. Enterprise Server A lifecycle module provides a means of running short–duration or long–duration Java-based tasks within the Enterprise Server environment. See Chapter 13, Developing Lifecycle Listeners, in Sun GlassFish Enterprise Server v3 Application Development Guide for more information.
You can deploy web, EJB, and application client modules separately, outside of any application. Module–based deployment is appropriate when components need to be accessed by other modules, applications, or application clients. Module-based deployment allows shared access to a bean from a web, EJB, or application client component. By using package definitions in the source code of all modules, you eanble the class loader to properly locate the classes after the modules have been deployed.
An application is a logical collection of one or more modules joined by application annotations or deployment descriptors. You assemble components into JAR, WAR, or RAR files, then combine these files into an Enterprise archive (EAR) file which is deployed.
The following figure shows EJB, web, application client, and connector modules assembled into a Java EE application.
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 class loaders, which is a waste of resources. 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 class loader or an application-specific class loader rather than in an application or module. For more information, see Chapter 2, Class Loaders, in Sun GlassFish Enterprise Server v3 Application Development Guide.
According to the Java EE specification, section 18.104.22.168, “Dependencies,” you cannot package utility classes within an individually-deployed EJB module. Instead, you must package the EJB module and utility JAR within an application using the JAR Extension Mechanism Architecture.
Ensure that your package and file names do not contain spaces or characters that are illegal for your operating system.
You should use a Java package-like naming scheme for module file names, 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. This package-like naming scheme ensures that name collisions do not occur. The benefits of this naming practice apply not only to Enterprise Server, but to other Java EE application servers as well.
The following topics are addressed here:
This name is used before the archive name to derive the default application registration name. The application will be deployed under xyz if the application.xml file defines application-name as xyz. However, a user-specified name takes precedence over the portable application name. If application-name is not specified in the application.xml file, the application is deployed using the archive name (minus suffix) as the application registration name.
The Java EE 6 specification also defines the portable module-name element in the module standard deployment descriptors. For standalone modules, the defined module-name will be used as the application name when a name is not explicitly specified.
Java Naming and Directory InterfaceTM (JNDI) lookup names for EJB components must also be unique. Establishing a consistent naming convention can help. For example, appending the application name and the module name to the EJB name is a way to guarantee unique names, such as, jms/qConnPool.
Application and module directory structures must follow the structure outlined in the Java EE specification. During deployment, the application or module is expanded from the archive file to an open directory structure. The directories are named with _jar and _war suffixes.
If you deploy a directory, your directory structure must follow this same convention. For instructions on performing directory deployment, see To Deploy an Application or Module in a Directory Format.
If you are using the following JSR 88 API, there is no file name:
javax.enterprise.deploy.spi.DeploymentManager.distribute(Target, InputStream, InputStream)
Because there is no file name, the name of the application is taken from the display-name entry in the Java EE standard deployment descriptor. If the display-name entry is not present, Enterprise Server creates a temporary file name and uses that name to deploy the application. Neither the Administration Console nor the asadmin utility uses this API.
If you are using the following preferred JSR 88 API, the name is derived from the first portion of the file name (without the .war or .jar extension):
javax.enterprise.deploy.spi.DeploymentManager.distribute(Target, File, File)
For more information about JSR 88, see http://jcp.org/en/jsr/detail?id=88.