1 Overview of Oracle GlassFish Server 3.1.2 Application Deployment

General Deployment Functionality

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.

• JSR 88 Deployment. A deployment mechanism implemented based on the JSR 88 standard from jcp.org. It delivers vendor neutral deployment options. See JSR 88 Client and JSR 88 Naming.

A deployment plan, which deploys a portable archive along with a deployment plan containing GlassFish Server 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. 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.

For production environments, any upgrade should be performed as a rolling upgrade, which upgrades applications and modules without interruption in service. For more information, see "Upgrading Applications Without Loss of Availability" in Oracle GlassFish Server High Availability Administration Guide.

Deployment Descriptors and Annotations

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. During deployment, GlassFish 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 GlassFish 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://www.oracle.com/technetwork/indexes/downloads/index.html. Information about the XML schemas that define Java EE standard deployment descriptors is available at http://java.sun.com/xml/ns/javaee/.

• GlassFish Server Descriptors. GlassFish Server provides optional deployment descriptors for configuring features that are specific to GlassFish Server. For example, when you assemble an EJB module, you annotate or create two GlassFish Server deployment descriptor files with these names: ejb-jar.xml and glassfish-ejb-jar.xml. If the EJB component is an entity bean with container-managed persistence (CMP), you can also create a .dbschema file and a sun-cmp-mapping.xml file. For complete descriptions of these files and their elements, see GlassFish Server Deployment Descriptor Files and Elements of the GlassFish Server Deployment Descriptors.

  Unless otherwise stated, settings in the GlassFish Server deployment descriptors override corresponding settings in the Java EE standard descriptors and in the GlassFish Server configuration.

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. GlassFish Server supports annotation according to the following specifications:

• JSR 250 Common Annotation Specification

• JSR 181 Annotation for Web Services Specification

• EJB 3.1 Specification

The following annotation and deployment descriptor combinations are supported:

• 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 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 GlassFish 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.

Modules and Applications

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 and, optionally, deployment descriptors into an Enterprise archive (EAR) file which is deployed.

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:

• Types of Modules

• Module-Based Deployment

• Application-Based Deployment

Module-Based Deployment

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.

The following figure shows separately-deployed EJB, web, and application client modules.

Figure 1-1 Module-Based Assembly and Deployment

Description of "Figure 1-1 Module-Based Assembly and Deployment"

Application-Based Deployment

Application-based deployment is appropriate when components need to work together as one unit.

The following figure shows EJB, web, application client, and connector modules assembled into a Java EE application.

Figure 1-2 Application-Based Assembly and Deployment

Description of "Figure 1-2 Application-Based Assembly and Deployment"

Access to Shared Framework Classes

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.

To specify an application-specific library file during deployment, use the --libraries option of the deploy or redeploy subcommand of the asadmin command. To add a library JAR file to the Common class loader directory, the Java optional package directory, or the application-specific class loader directory, use the add-library subcommand. You can then list the libraries with list-libraries and remove the libraries with remove-library. For more information about all these commands, see the Oracle GlassFish Server Reference Manual.

For more information about class loaders, see "Class Loaders" in Oracle GlassFish Server Application Development Guide.

Naming Standards

Names of applications and individually-deployed modules must be unique within a GlassFish Server domain. Modules within an application must have unique names. In addition, for enterprise beans that use container-managed persistence (CMP), the .dbschema file names must be unique within an application.

You should use a hierarchical naming scheme for module file names, EAR 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 hierarchical naming scheme ensures that name collisions do not occur. The benefits of this naming practice apply not only to GlassFish Server, but to other Java EE application servers as well.

The following topics are addressed here:

• Portable Naming

• JNDI Naming

• Directory Structure

• JSR 88 Naming

<application-name>xyz</application-name>

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

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

Module and Application Versions

Application and module versioning allows multiple versions of the same application to exist in a GlassFish Server domain, which simplifies upgrade and rollback tasks. At most one version of an application or module can be enabled on a server any given time. Versioning provides extensions to tools for deploying, viewing, and managing multiple versions of modules and applications, including the Administration Console and deployment-related asadmin subcommands. Different versions of the same module or application can have the same context root or JNDI name. Use of versioning is optional.

The following topics are addressed here:

• Version Identifiers and Expressions

• Choosing the Enabled Version

• Versioning Restrictions and Limitations

foo:1
foo:BETA-2e
foo:3.8
foo:patch39875

Administration Console

The GlassFish Server Administration Console is a browser-based utility that features a graphical interface that includes extensive online help for the administrative tasks. The format for starting the Administration Console in a web browser is http://hostname:port. For example:

http://localhost:4848

Step-by-step instructions for using the Administration Console for deployment are provided in the Administration Console online help. You can display the help material for a page by clicking the Help button. The initial help page describes the functions and fields of the page itself. To find instructions for performing associated tasks, click a link in the See Also list.

The asadmin Utility

The GlassFish Server asadmin utility is a command-line tool that invokes subcommands for identifying the operation or task that you want to perform. You can run asadmin commands either from a command prompt or from a script. The format for starting the asadmin utility on the command line is as-install/bin/asadmin subcommand --option. For example:

asadmin list-applications --type web

Application deployment commands are listed in The asadmin Deployment Subcommands. All GlassFish Server asadmin subcommands are documented in the Oracle GlassFish Server Reference Manual.

For the most part, you can perform the same administrative tasks by using either the graphical Administration Console or the asadmin command-line utility, however, there are exceptions. Procedures for using the command-line utilities are provided in this guide and in the command-line help pages, which are similar to man pages. You can display the help material for a command by typing help followed by the subcommand. For example:

asadmin help list-applications

For additional information on the asadmin utility, see "Using the asadmin Utility" in Oracle GlassFish Server Administration Guide and the asadmin(1M) help page.

NetBeans IDE

You can use the NetBeans Integrated Development Environment (IDE), or another IDE, to assemble Java EE applications and modules. The NetBeans IDE is included in the tools bundle of the Java EE Software Development Kit (SDK). To download, see http://www.oracle.com/technetwork/java/javaee/downloads/index.html. For additional information, see http://www.netbeans.org.

Eclipse IDE

In addition to the bundled NetBeans IDE, a plug-in for the Eclipse IDE extends GlassFish to the Eclipse community. To download, see http://glassfishplugins.java.net/.

JSR 88 Client

The syntax of the URI entry for the getDeploymentManager method is as follows:

deployer:Sun:AppServer::admin-host:admin-port[:https]

For example:

deployer:Sun:AppServer::localhost:4848:https