test

Oracle GlassFish Server 3.0.1 Application Deployment Guide

Chapter 1 Overview of Oracle GlassFishTM Server 3.0.1 Application Deployment

Oracle GlassFish Server 3.0.1 provides an environment for developing and deploying JavaTM applications and web services. GlassFish Server applications include Java Platform, Enterprise Edition (Java EE platform) standard features as well as features specific to GlassFish Server. This guide explains the tools and processes used for deploying applications and modules in the GlassFish Server environment. Only GlassFish Server features are described in detail in this document.

The following topics are addressed here:

Information and instructions on deploying from the command line are provided in this document. Information and instructions for accomplishing the deployment tasks by using the Administration Console are contained in the Administration Console online help.

About Application Deployment

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 GlassFish Server assembly process conforms to the customary Java EE specifications. The only difference is that when you assemble applications or modules in GlassFish Server, you can include optional GlassFish Server 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. GlassFish Server deployment tools are described in About Deployment Tools.

The following topics are addressed here:

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:

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:

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.

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. At run time, 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:

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:

The following annotation and deployment descriptor combinations are supported:

Modules and Applications

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

GlassFish Server supports the following types of modules:

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

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

Figure 1–1 Module–Based Assembly and Deployment

Figure shows EJB, web, and `application client module assembly and deployment.

Application-Based Deployment

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.

Figure 1–2 Application–Based Assembly and Deployment

Figure shows Java EE application 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. For more information, see Chapter 2, Class Loaders, in Oracle GlassFish Server 3.0.1 Application Development Guide.

Note –

According to the Java EE specification, section 8.1.1.2, “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.

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.

Note –

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 GlassFish Server, but to other Java EE application servers as well.

The following topics are addressed here:

Portable Naming

The Java EE 6 specification defines the portable application-name, which allows you to specify an application name in the application.xml file. For example:


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

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.

JNDI Naming

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.

Directory Structure

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.

JSR 88 Naming

There are two JSR 88 APIs that can be used to deploy applications in GlassFish Server.

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

About Assembly and Deployment Events

The deployment tools that are provided by GlassFish Server can be used by anyone to deploy applications and modules into any GlassFish Server environment. However, effective application deployment requires planning and care. Only the developer knows exactly what is required by an application, so the developer is responsible for initial assembly and deployment.

  1. Deployment Descriptor Creation. The developer creates the deployment descriptors using Java standards and tools.

    Details of the GlassFish Server deployment descriptors are contained in Appendix B, GlassFishTM Server Deployment Descriptor Files and Appendix C, Elements of the GlassFishTM Server Deployment Descriptors. The GlassFish Server sample applications contain deployment descriptors that can be used as templates for developing deployment descriptors.

  2. Assembly. The developer assembles the archive file(s) using Java standards and tools, such as the jar command. The application or module is packaged into a JAR, WAR, RAR, or EAR file. For guidelines on naming, see Naming Standards.

    There are no GlassFish Server issues to consider.

  3. Test Deployment. The developer performs a test deployment of the archive. For instructions, see To Deploy an Application or Module.

  4. Archive Submission. The developer submits the verified archive to the administrator for deployment into a production environment. The developer includes instructions for any additional deployment tasks that the administrator must perform. For an example of such additional instructions, see Access to Shared Framework Classes.

  5. Configuration. The administrator applies additional deployment specifics. Sometimes the developer has indicated additional deployment needs, such as specifying the production database. In this case, the administrator edits and reassembles the archive.

  6. Production Deployment. The administrator deploys the archive to production. See To Deploy an Application or Module.

  7. Troubleshooting. If deployment fails, the administrator returns the archive to the developer. The developer fixes the problem and resubmits the archive to the administrator. Sometimes the administrator resolves the problem, depending on what the problem is.

About Deployment Tools

The following tools can be used for assembling and deploying a module or application:

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 Appendix A, The asadmin Deployment Subcommands. All GlassFish Server asadmin commands are documented in Oracle GlassFish Server 3.0.1 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 3.0.1 Administration Guide and the asadmin(1M) help page.

Ant Utility

The GlassFish Server Ant tasks can help you assemble and deploy modules and applications. For instructions, see Chapter 3, Using Ant with GlassFish Server, in Oracle GlassFish Server 3.0.1 Application Development Guide.

Note –

GlassFish Server is compatible with Apache Ant versions 1.6.5 or greater. If you have not installed Ant, you can download it from the Update Tool. The Apache Ant Build Tool add-on component supplies Ant version 1.7.1. For information about Update Tool, see Update Tool in Oracle GlassFish Server 3.0.1 Administration Guide.

NetBeans IDE

You can use the NetBeansTM 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://java.sun.com/javaee/downloads/index.jsp. 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 https://glassfishplugins.dev.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

Additional Information on Application Deployment

As specified from Java EE 6 specifications, the relevant specifications are the following:

The following product documentation might be relevant to some aspects of application deployment: