1. Overview of Oracle GlassFish Server 3.1 Application Deployment
Deploying Applications and Modules
To Deploy an Application or Module
To Change Targets for a Deployed Application or Module
To List Deployed Applications or Modules
To Redeploy an Application or Module
To Disable an Application or Module
To Enable an Application or Module
To Undeploy an Application or Module
To Reload Changes to Applications or Modules Dynamically
To Deploy an Application or Module Automatically
To Deploy an Application or Module by Using a Deployment Plan
Modifying the Configuration of a Web Application or Module
To Set a Web Context Parameter
To Unset a Web Context Parameter
To List Web Context Parameters
To Set a Web Environment Entry
To Unset a Web Environment Entry
To List Web Environment Entries
Web Module Deployment Guidelines
EJB Module Deployment Guidelines
To Deploy and Configure a Stand-Alone Connector Module
Redeploying a Stand-Alone Connector Module
Deploying and Configuring an Embedded Resource Adapter
Assembling and Deploying an Application Client Module
To Assemble and Deploy an Application Client
To Prepare Another Machine for Running an Application Client
To Undeploy an Application Client
Lifecycle Module Deployment Guidelines
Web Service Deployment Guidelines
OSGi Bundle Deployment Guidelines
Transparent JDBC Connection Pool Reconfiguration
A. The asadmin Deployment Subcommands
B. GlassFish Server Deployment Descriptor Files
Application deployment is a dynamic process, which means that deployed applications and modules become available without requiring you to restart the server instance. Dynamic deployment can be useful in production environments to bring new applications and modules online easily. If you do restart the server, all deployed components are still deployed and available.
The following topics are addressed here:
Instructions for accomplishing these tasks by using the Administration Console are contained in the Administration Console online help.
Use the deploy subcommand in remote mode to deploy an assembled application or module to GlassFish Server. If an error occurs during deployment, the application or module is not deployed. If a module within an application contains an error, the entire application is not deployed. These failures prevent a partial deployment that could leave the server in an inconsistent state.
By default, the deployment target is the default server instance, server. To deploy only to the default server instance, specify no target. If you deploy the application or module only to the domain target, it exists in the domain central repository, but no server instances or clusters can reference the component unless you add references.
You can also deploy a component to a specific stand-alone server instance or cluster. When you deploy to server instances or clusters, the application or module exists in the domain’s central repository and is referenced by any clusters or server instances that you deployed to. For a cluster, the preselected deployment target is server.
If the component is already deployed or already exists, you can forcefully redeploy if you set the --force option of the deploy subcommand to true. See Example 2-8. The redeploy subcommand also accomplishes this. You can see the enabled or disabled status of an application or module by using the show-component-status(1) subcommand.
For information about how the application or module name is derived, see Naming Standards.
Remote commands require a running server.
Information about the options and properties of the subcommand is included in this help page.
Example 2-1 Deploying an Enterprise Application
This example deploys newApp.ear to the default server, server.
asadmin> deploy Cart.ear Application deployed successfully with name Cart. Command deploy executed successfully
Example 2-2 Deploying a Connector Module
This example deploys a connector module that is packaged in an RAR file.
asadmin> deploy jdbcra.rar Application deployed successfully with name jdbcra. Command deploy executed successfully
See Also
You can also view the full syntax and options of the subcommand by typing asadmin help deploy at the command line.
After deployment, the deployed application or module exists in the central repository and can be referenced by the server instances or clusters that you deployed to as targets. The asadmin create-application-ref and asadmin delete-application-ref subcommands enable you to add or delete targets for a deployed component. Because the application or module itself is stored in the central repository, adding or deleting targets adds or deletes the same version of the component on different targets.
Remote commands require a running server.
See Also
You can also view the full syntax and options of the subcommand by typingasadmin help create-application-ref or asadmin help delete-application-ref at the command line.
There are a number of commands that can be used to list deployed applications or modules and their subcomponents. Use the commands in this section in remote mode.
Remote commands require a running server.
Information about these commands is included in these help pages.
Example 2-3 Listing Applications
The list-applications subcommand lists all deployed Java EE applications or modules. If the --type option is not specified, all components are listed. This example lists deployed applications.
asadmin> list-applications --type web hellojsp <web> Command list-applications executed successfully
Example 2-4 Listing Subcomponents
The list-sub-components subcommand lists EJBs or servlets in a deployed module or in a module of the deployed application. If a module is not identified, all modules are listed. The --appname option functions only when the given module is standalone. To display a specific module in an application, you must specify the module name and the --appname option. This example gets the subcomponents of module mejb.jar within application MEjbApp.
asadmin> list-sub-components --appname MEjbApp mejb.jar MEJBBean <StatelessSessionBean> Command list-sub-components executed successfully
Example 2-5 Showing Status of a Deployed Component
The show-component-status subcommand gets the status (enabled or disabled) of the deployed component. This example gets the status of the MEjbApp component.
asadmin show-component-status MEjbApp Status of MEjbApp is enabled Command show-component-status executed successfully
Use the redeploy subcommand in remote mode to overwrite a previously–deployed application or module. You can also accomplish this task by using the --force option of the deploy subcommand. Whenever a redeployment is done, the HTTP and SFSB sessions in transit at that time, and the EJB timers, become invalid unless you use the --keepstate=true option of the redeploy subcommand.
Before You Begin
You must remove a preconfigured resource before it can be updated.
Remote commands require a running server.
Information about the options and properties of these commands is included in these help page.
Example 2-6 Retaining HTTP Session State During Redeployment
This example redeploys the hello web application. In a production environment, you usually want to retain sessions. If you use the --keepstate option, active sessions of the application are retained and restored when redeployment is complete.
asadmin> redeploy --name hello --keepstate=true hello.war Application deployed successfully with name hello. Command redeploy executed successfully.
Keep State is a checkbox option when you redeploy using the Administration Console. For instructions, see the Administration Console online help.
Example 2-7 Redeploying a Web Application That Was Deployed From a Directory
This example redeploys the hello web application, which was originally deployed from the hellodir directory.
asadmin>redeploy --name hellodir Application deployed successfully with name hellodir. Command redeploy executed successfully.
Example 2-8 Redeploying an Application by Using asadmin deploy --force
The --force option is set to false by default. This example redeploys newApp.ear even if has been deployed or already exists.
asadmin> deploy --force=true newApp.ear Application deployed successfully with name newApp. Command deploy executed successfully.
See Also
You can also view the full syntax and options of the subcommand by typing asadmin help redeploy at the command line.
Use the disable subcommand in remote mode to immediately deactivate a deployed application or module without removing it from the server. Disabling a component makes the component inaccessible to clients. However, the component is not overwritten or uninstalled, and can be enabled by using the asadmin enable subcommand.
An application or module is enabled by default.
Remote commands require a running server.
To list deployed applications or modules, use the list-applications(1) subcommand. If you do not specify a type, all deployed applications and modules are listed. For example, valid types can be web, ejb, connector, application, and webservice.
To see the status of deployed components, use the show-component-status(1) subcommand.
Information about the options and properties of the subcommand is included in this help page.
Example 2-9 Listing Deployed Web Applications
This example lists all deployed web applications.
asadmin> list-applications --type web hellojsp <web> Command list-applications executed successfully.
Example 2-10 Disabling a Web Application
This example disables the hellojsp application.
asadmin> disable hellojsp Command disable executed successfully.
See Also
You can also view the full syntax and options of the subcommand by typing asadmin help disable at the command line.
An enabled application or module is runnable and can be accessed by clients if it has been deployed to an accessible server instance or cluster. An application or module is enabled by default. Use the enable subcommand in remote mode to enable an application or module that has been disabled.
An application or module that is deployed to more than one target can be enabled on one target and disabled on another. If a component is referenced by a target, it is not available to users unless it is enabled on that target.
Remote commands require a running server.
If the component has not been deployed, an error message is displayed. If the component is already enabled, it is re-enabled. To see the status of deployed components, use the show-component-status(1) subcommand.
Information about the options and properties of the subcommand is included in this help page.
Example 2-11 Enabling an Application
This example enables the sampleApp application.
asadmin> enable sampleApp Command enable executed successfully.
See Also
You can also view the full syntax and options of the subcommand by typing asadmin help enable at the command line.
Use the undeploy subcommand in remote mode to uninstall a deployed application or module and remove it from the repository. To reinstate the component, you must deploy the component again using the deploy subcommand.
Remote commands require a running server.
To list deployed applications or modules, use the list-applications(1) subcommand. If you do not specify a type, all deployed applications and modules are listed. For example, valid types can be web, ejb, connector, application, and webservice.
To see the status of deployed components, use the show-component-status(1) subcommand.
Information about the options and properties of the subcommand is included in this help page.
Example 2-12 Listing Deployed Applications or Modules
This example lists all applications of type web.
asadmin> list-applications --type web hellojsp <web> Command list-applications executed successfully.
Example 2-13 Undeploying an Application
This example uninstalls the hellojsp application.
asadmin> undeploy hellojsp hellojsp <web> Command undeploy executed successfully.
See Also
You can also view the full syntax and options of the subcommand by typing asadmin help undeploy at the command line.
Dynamic reloading enables you to change the code or deployment descriptors of an application or module without needing to perform an explicit redeployment. Instead, you can copy the changed class files or descriptors into the deployment directory for the application or module. The server checks for changes periodically and automatically redeploys the changes if the timestamp of the .reload file in the root directory for the application or module has changed.
Dynamic reloading is enabled by default, and is available only on the default server instance.
For an application:
domain-dir/applications/app-name
For an individually deployed module:
domain-dir/applications/module-name
Note - Deployment directories might change between GlassFish Server releases.
If the .reload file doesn't exist, the touch or echo command creates it.
Note - This task is best suited for use in a development environment.
Automatic deployment involves copying an archive file into a special autodeploy directory where the archive is automatically deployed by GlassFish Server at predefined intervals. This method is useful in a development environment because it allows new code to be tested quickly. Automatic deployment is enabled by default, and is available only on the default server instance.
This sets the interval at which applications and modules are checked for code changes and dynamically reloaded. The default is 2.
The default location is domain-dir/autodeploy. The application will be deployed at the next interval.
To undeploy an automatically deployed application or module, remove its archive file from the autodeploy directory.
Note - Deployment directories might change between GlassFish Server releases.
Example 2-14 Setting the Autodeployment Interval
This example sets the autodeployment inverval to 3 seconds (default is 2).
asadmin> set server.admin-service.das-config.autodeploy-polling-interval-in-seconds=3 Command set executed successfully.
Example 2-15 Setting JSP Precompilation
This example enables JSP precompilation (default is false).
asadmin> set server.admin-service.das-config.autodeploy-jsp-precompilation-enabled=true Command set executed successfully.
See Also
You can also view the full syntax and options of the subcommand by typing asadmin set --help at the command line.
In the deployment plan for an EAR file, the glassfish-application.xml file is located at the root. The deployment descriptor for each module is stored according to this syntax: module-name.gf-dd-name, where the gf-dd-name depends on the module type. If a module named MyModule contains a CMP mappings file, the file is named MyModule.sun-cmp-mappings.xml. A .dbschema file is stored at the root level. Each / (forward slash) is replaced by a # (pound sign).
Remote commands require a running server.
Example 2-16 Deploying by Using a Deployment Plan
This example deploys the application in the myrostapp.ear file according to the plan specified by the mydeployplan.jar file.
asadmin>deploy --deploymentplan mydeployplan.jar myrostapp.ear Application deployed successfully with name myrostapp. Command deploy executed successfully.
Example 2-17 Deployment Plan Structure for an Enterprise Application
This listing shows the structure of the deployment plan JAR file for an EAR file.
$ jar -tvf mydeployplan.jar 420 Thu Mar 13 15:37:48 PST 2003 glassfish-application.xml 370 Thu Mar 13 15:37:48 PST 2003 RosterClient.war.glassfish-web.xml 418 Thu Mar 13 15:37:48 PST 2003 roster-ac.jar.glassfish-application-client.xml 1281 Thu Mar 13 15:37:48 PST 2003 roster-ejb.jar.glassfish-ejb-jar.xml 2317 Thu Mar 13 15:37:48 PST 2003 team-ejb.jar.glassfish-ejb-jar.xml 3432 Thu Mar 13 15:37:48 PST 2003 team-ejb.jar.sun-cmp-mappings.xml 84805 Thu Mar 13 15:37:48 PST 2003 team-ejb.jar.RosterSchema.dbschema
Example 2-18 Deployment Plan Structure for an EJB Module
In the deployment plan for an EJB module, the deployment descriptor that is specific to GlassFish Server is at the root level. If a standalone EJB module contains a CMP bean, the deployment plan includes the sun-cmp-mappings.xml and .dbschema files at the root level. In the following listing, the deployment plan describes a CMP bean:
$ jar r -tvf myotherplan.jar 3603 Thu Mar 13 15:24:20 PST 2003 glassfish-ejb-jar.xml 3432 Thu Mar 13 15:24:20 PST 2003 sun-cmp-mappings.xml 84805 Thu Mar 13 15:24:20 PST 2003 RosterSchema.dbschema
See Also
The deployment plan is part of the implementation of JSR 88. For more information about JSR 88, see JSR 88 Naming and the JSR 88 page at http://jcp.org/en/jsr/detail?id=88.
Note - This task is best suited for use in a development environment.
An expanded directory, also known as an exploded directory, contains an unassembled (unpackaged) application or module. To deploy a directory format instead of an archive, file, use the asadmin deploy subcommand in remote mode and specify a path to a directory instead of to an archive file. The contents of the directory must be the same as the contents of a corresponding archive file, with one exception. An application archive file contains archive files for its modules, for example myUI.war and myEJB.jar. The expanded application directory contains expanded directories for the modules, for example myUI_war and myEJB_jar, instead. .
You can change deployment descriptor files directly in the expanded directory.
If your environment is configured to use dynamic reloading, you can also dynamically reload applications or modules that are deployed from the directory. For instructions, see To Reload Changes to Applications or Modules Dynamically.
Unlike archive file deployment, directory deployment does not copy the directory contents to the remote hosts. This means that for deployment to a cluster, the directory path may exist for both the DAS and the remote server instances but may not actually correspond to the same physical location. If any target server instance cannot see the deployed directory, or finds that it contains different files from those detected by the DAS, deployment fails.
Integrated development environments (IDEs) typically use directory deployment, so you do not need to deal directly with the expanded format.
Before You Begin
On each cluster or stand-alone server instance to which the application or module is deployed, the directory must be accessible and must contain the same files as found by the DAS.
On Windows, if you are deploying a directory on a mapped drive, you must be running GlassFish Server as the same user to which the mapped drive is assigned. This enables GlassFish Server to access the directory.
Remote commands require a running server.
For information about the required directory contents, see the appropriate specifications.
Note - Deployment directories might change between GlassFish Server releases.
Example 2-19 Deploying an Application From a Directory
This example deploys the expanded directory /apps/MyApp for the hello application.
asadmin> deploy --name hello /apps/MyApp Application deployed successfully with name hello. Command deploy executed successfully.
See Also
You can also view the full syntax and options of the subcommand by typing asadmin help deploy at the command line.