type=page status=published title=Overview of {productName} 7 Application Deployment next=deploying-applications.html prev=preface.html ~~
{productName} 7 provides an environment for developing and deploying Java applications and web services. {productName} applications include Java Platform, Enterprise Edition (Jakarta EE platform) standard features as well as features specific to {productName}. This guide explains the tools and processes used for deploying applications and modules in the {productName} environment. Only {productName} 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.
Assembly, also known as packaging, is the process of combining discrete components of an application or module into a single unit that can be installed on an application server. The {productName} assembly process conforms to the customary Jakarta EE specifications. The only difference is that when you assemble applications or modules in {productName}, you can include optional {productName} deployment descriptors that enhance functionality.
Deployment is the process of installing an application or module on {productName}, optionally specifying location-specific information, such as a list of local users that can access the application, or the name of the local database. {productName} deployment tools expand the archive file into an open directory structure that is ready for users. {productName} deployment tools are described in About Deployment Tools.
The following topics are addressed here:
Various Jakarta 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.
A deployment plan, which deploys a portable archive along with a deployment plan containing {productName} 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 {productName} High Availability Administration Guide.
A deployment descriptor is an XML file that describes how a Jakarta 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, {productName} reads the information in the deployment descriptor and deploys the application or module as directed.
The following types of deployment descriptors are associated with {productName}:
-
Jakarta EE Standard Descriptors. Jakarta EE standard deployment descriptors are described in the Jakarta EE specification. You can find the specification at
https://jakarta.ee/specifications/
. Information about the XML schemas that define Jakarta EE standard deployment descriptors is available athttps://jakarta.ee/xml/ns/jakartaee/
.The Jakarta EE specification permits the use of alternate top-level standard deployment descriptors that reside outside of the application archive using the
alt-dd
mechanism (alternate module-level deployment descriptors were permitted prior to Jakarta EE 7). Alternate deployment descriptors are described in the Jakarta EE 7 specification. You can find the specification athttp://www.oracle.com/technetwork/java/javaee/tech/
. Alternate deployment descriptors override the top-level deployment descriptors packaged in an application archive. For example, for EAR files, an alternate deployment descriptor overridesapplication.xml
. For standalone modules, an alternate deployment descriptor overrides the top-level module descriptor, such asweb.xml
. -
{productName} Descriptors. {productName} provides optional deployment descriptors for configuring features that are specific to {productName}. For example, when you assemble an EJB module, you annotate or create two {productName} deployment descriptor files with these names:
ejb-jar.xml
andglassfish-ejb-jar.xml
. If the EJB component is an entity bean with container-managed persistence (CMP), you can also create a.dbschema
file and asun-cmp-mapping.xml
file. For complete descriptions of these files and their elements, see {productName} Deployment Descriptor Files and Elements of the {productName} Deployment Descriptors.{productName} also permits the use of alternate top-level {productName} runtime deployment descriptors that reside outside of an application archive. Alternate {productName} deployment descriptors override the top-level deployment descriptors packaged in the archive. For example, for EAR files, an alternate {productName} deployment descriptor overrides
glassfish-application.xml
. For standalone modules, an alternate {productName} deployment descriptor overrides the top-level module descriptor, such asglassfish-web.xml
. The name of the {productName} alternate deployment descriptor file must begin withglassfish-
. Alternate deployment descriptors do not apply tosun-*.xml
deployment descriptors.Unless otherwise stated, settings in the {productName} deployment descriptors override corresponding settings in the Jakarta EE standard descriptors and in the {productName} 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. {productName} supports annotation according to the following specifications:
The following annotation and deployment descriptor combinations are supported:
-
Jakarta EE applications or modules can be packaged with full Jakarta EE 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. -
Jakarta EE applications or modules can be fully annotated with metadata defined by the listed specifications. Annotation eliminates the need for Jakarta EE standard deployment descriptors. In most cases, the {productName} deployment descriptors are also not needed.
-
Jakarta 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.
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 Jakarta 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:
{productName} 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 Jakarta 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 Pages (JSP) 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
andglassfish-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
andglassfish-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 {productName} connector has annotations or a deployment descriptor file (
ra.xml
).After deploying a J2EE connector module, you must configure it as described in Developing Connectors in {productName} 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
andglassfish-application-client.xml
). An application client JAR file applies to a {productName} type of Jakarta EE client. An application client supports the standard Jakarta EE Application Client specifications. -
Lifecycle Module. A lifecycle module provides a means of running short-duration or long-duration Java-based tasks within the {productName} environment. Lifecycle modules are not Jakarta EE standard modules. See Developing Lifecycle Listeners in {productName} 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.
The following figure shows separately-deployed EJB, web, and application client modules.
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 Jakarta 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 {productName}
Reference Manual.
For more information about class loaders, see Class Loaders in {productName} Application Development Guide.
Note
|
According to the Jakarta 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. |
Names of applications and individually-deployed modules must be unique
within a {productName} 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 {productName}, but to other Jakarta EE application servers
as well.
The following topics are addressed here:
Starting in Jakarta EE 6, the Jakarta EE 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>
The Jakarta EE specification also defines the portable module-name
element in the module standard deployment descriptors.
{productName} determines the application registration name according to the following order of precedence:
-
The name specified at deployment time in the Administration Console or in the
--name
option of theasadmin deploy
command is used. -
If no name is specified at deployment time, the portable
application-name
ormodule-name
in the Jakarta EE deployment descriptor is used. -
If no name is specified at deployment time or in the deployment descriptors, the archive name, minus the file type suffix, is used.
Java Naming and Directory Interface (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 Jakarta EE specification. During deployment, the
application or module is expanded from the archive file to an open
directory structure. The directories that hold the individual modules
are named with _jar
, _rar
, and _war
suffixes.
If you deploy a directory instead of an EAR file, 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.
Application and module versioning allows multiple versions of the same
application to exist in a {productName} 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:
The version identifier is a suffix to the module or application name. It
is separated from the name by a colon (:
). It must begin with a letter
or number. It can contain alphanumeric characters plus underscore (_
),
dash (-
), and period (.
) characters. The following examples show
valid version identifiers for the foo
application:
foo:1
foo:BETA-2e
foo:3.8
foo:patch39875
A module or application without a version identifier is called the untagged version. This version can coexist with other versions of the same module or application that have version identifiers.
In some deployment-related asadmin
commands, you can use an asterisk
(*
) as a wildcard character to specify a version expression, which
selects multiple version identifiers. Using the asterisk by itself after
the colon selects all versions of a module or application, including the
untagged version. The following table shows example version expressions
and the versions they select.
Version Expression | Selected Versions |
---|---|
|
All versions of |
|
All |
|
All |
|
All |
The following table summarizes which asadmin
subcommands are
identifier-aware or expression-aware. All expression-aware subcommands
are also identifier-aware.
Identifier-Aware Subcommands | Expression-Aware Subcommands |
---|---|
|
|
|
|
|
|
|
|
The create-application-ref
subcommand is expression-aware only if the
--enabled
option is set to false
. Because the --enabled
option is
set to true
by default, the create-application-ref
subcommand is
identifier-aware by default.
The list-applications
and list-application-refs
subcommands display
information about all deployed versions of a module or application. To
find out which version is enabled, use the --long
option.
At most one version of a module or application can be enabled on a server instance. All other versions are disabled. Enabling one version automatically disables all others. You can disable all versions of a module or application, leaving none enabled.
The --enabled
option of the deploy
and redeploy
subcommands is set
to true
by default. Therefore, simply deploying or redeploying a
module or application with a new version identifier enables the new
version and disables all others. To deploy a new version in a disabled
state, set the --enabled
option to false
.
To enable a version that has been deployed previously, use the enable
subcommand.
Module and application versioning in {productName} is subject to the following restrictions and limitations:
-
Use of the
--name
option is mandatory for modules and applications that use versioning. There is no automatic version identifier generation. -
{productName} does not recognize any relationship between versions such as previous or later versions. All version relationships must be tracked manually.
-
There is no limit to the number of versions you can deploy except what is imposed by disk space limits.
-
A module or application in a directory should not be deployed twice with a different version identifier. To redeploy a module or application from a directory with a new version, you must use the
--force
option of thedeploy
subcommand. -
Database tables created or deleted as part of deployment and undeployment are global resources and cannot be qualified by an application version. Be very careful when using global resources among versions of the same application.
-
Web sessions are preserved during redeployment of a new version. However, preserving sessions among different versions of the same module or application is complex, because the key used for session variables is the same for the old and new versions.
-
Resources are created with reference to a resource-adapter’s module or application name. This means that an older version’s resources do not automatically refer to a newer version of the module or application. Therefore, you must explicitly create resources for a newer version of a module or application. {productName} ignores duplicate exported global resources and lets deployment succeed.
-
OSGi already has its own versioning system. Therefore, when you deploy an OSGi bundle, {productName} ignores any version information provided with the name but permits the deployment to succeed with warnings.
The deployment tools that are provided by {productName} can be used by any user authorized as an administrator to deploy applications and modules into any {productName} 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.
-
Deployment Descriptor or Annotation Creation. The developer creates the deployment descriptors or equivalent annotations using Java standards and tools.
Details of the {productName} deployment descriptors are contained in {productName} Deployment Descriptor Files and Elements of the {productName} Deployment Descriptors. The {productName} sample applications contain deployment descriptors that can be used as templates for developing deployment descriptors.
-
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 {productName} issues to consider.
-
Test Deployment. The developer performs a test deployment of the archive. For instructions, see To Deploy an Application or Module.
-
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.
-
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.
-
Production Deployment. The administrator deploys the archive to production. See To Deploy an Application or Module.
-
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.
{productName} provides tools for assembling and deploying a module or application.
The following topics are addressed here:
The {productName} 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 {productName} 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 {productName} asadmin
subcommands are documented
in the {productName} 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 {productName} Administration Guide and the
asadmin
(1M) help page.
You can use the NetBeans Integrated Development Environment (IDE), or
another IDE, to assemble Jakarta EE applications and modules. The NetBeans
IDE is included in the tools bundle of the Jakarta 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
.
In addition to the bundled NetBeans IDE, a plug-in for the Eclipse IDE extends GlassFish to the Eclipse community.
As specified from Jakarta EE specifications, the relevant specifications are the following:
-
Jakarta EE Platform, Enterprise Edition 10 Specification
https://jakarta.ee/specifications/platform/
-
Jakarta EE Application Deployment JSR 88 Specification
http://jcp.org/en/jsr/detail?id=88
-
Common Annotations for the Java Platform 1.6 Specification
http://jcp.org/en/jsr/detail?id=250
-
Java Servlet 3.0 Specification
http://jcp.org/en/jsr/detail?id=315
-
Enterprise JavaBeans 3.1 Specification
http://jcp.org/en/jsr/detail?id=318
-
Jakarta EE Connector Architecture 1.6 Specification
http://jcp.org/en/jsr/detail?id=322
The following product documentation might be relevant to some aspects of application deployment:
-
{productName} Administration Console online help