test

Oracle GlassFish Server 3.0.1 Application Deployment Guide

Deploying Applications and Modules

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.

ProcedureTo Deploy an Application or Module

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. These failures prevent a partial deployment that could leave the server in an inconsistent state.

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–9. The redeploy subcommand also accomplishes this. You can see the status of a component by using the show-component-status(1) subcommand.

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. The user-specified name has the highest precedence. If no application-name is specified in the application.xml file, the application is deployed using the archive name (minus suffix) as the application registration name.

  1. Ensure that the server is running.

    Remote commands require a running server.

  2. (Optional) List deployed components by using the list-components(1) subcommand.

  3. Deploy the application or module by using the deploy(1) subcommand.

    Information about the options and properties of the subcommand is included in this help page.

  4. (Optional) If needed, fix issues and rerun the deploy subcommand.

Example 2–1 Deploying an Enterprise Application

This example deploys newApp.ear to the default server, server.


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

ProcedureTo List Deployed Applications or Modules

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.

  1. Ensure that the server is running.

    Remote commands require a running server.

  2. List the desired components by using the list-applications(1) subcommand, the list-components(1) subcommand , or the list-sub-components(1)command.

    Information about these commands is included in these help pages.

  3. Show the status of a deployed component by using the show-component-status(1).

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 Components

The list-components subcommand lists the deployed Java EE components. If the --type option is not specified, all components are listed. This example lists the components of the deployed cciblackbox-tx.rar.


asadmin> list-components --type connector
cciblackbox-tx <connector>
Command list-components executed successfully
Example 2–5 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 application MEjbApp within module mejb.jar.


asadmin> list-sub-components --appname MEjbApp mejb.jar
MEJBBean <StatelessSessionBean>
Command list-sub-components executed successfully
Example 2–6 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

ProcedureTo Redeploy an Application or Module

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 sessions in transit at that time become invalid unless you use the keepSessions=true property of the redeploy subcommand.

Before You Begin

You must remove a preconfigured resource before it can be updated.

  1. Ensure that the server is running.

    Remote commands require a running server.

  2. Redeploy an application or module by using the redeploy(1) subcommand or the deploy(1) subcommand with the --force option.

    Information about the options and properties of these commands is included in these help page.

Example 2–7 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 keepSessions property, active sessions of the application are retained and restored when redeployment is complete.


asadmin> redeploy --name hello --properties keepSessions=true hello.war
Application deployed successfully with name hello.
Command redeploy executed successfully.

Keep Sessions is a checkbox option when you redeploy using the Administration Console. For instructions, see the Administration Console online help.

Example 2–8 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. The path is retrieved from the domain.xml file.


asadmin>redeploy --name hellodir
Application deployed successfully with name hellodir.
Command redeploy executed successfully.
Example 2–9 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.

ProcedureTo Disable an Application or Module

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.

By default, a deployed application or module is enabled.

  1. Ensure that the server is running.

    Remote commands require a running server.

  2. Obtain the exact name of the application or module that you are disabling.

    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, jruby, and webservice.

    To see the status of deployed components, use the show-component-status(1) subcommand.

  3. Deactivate the application or module by using the disable(1) subcommand.

    Information about the options and properties of the subcommand is included in this help page.

Example 2–10 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–11 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.

ProcedureTo Enable an Application or Module

By default, a deployed application or module is enabled, which means that it is runnable and can be accessed by clients if it has been deployed to an accessible server instance. Use the enable subcommand in remote mode to enable an application or module that has been disabled.

  1. Ensure that the server is running.

    Remote commands require a running server.

  2. Enable the application or module by using the enable(1) subcommand.

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

ProcedureTo Undeploy an Application or Module

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.

  1. Ensure that the server is running.

    Remote commands require a running server.

  2. Obtain the exact name of the application or module you are undeploying.

    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, jruby, and webservice.

    To see the status of deployed components, use the show-component-status(1) subcommand.

  3. Undeploy the application or module by using the undeploy(1) subcommand.

    Information about the options and properties of the subcommand is included in this help page.

Example 2–13 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–14 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.

ProcedureTo Reload Changes to Applications or Modules Dynamically

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.

  1. Create an empty file named .reload at the root of the deployed application or module.

    domain-dir/applications/module-name/.reload
    Note –

    Deployment directories might change between GlassFish Server releases.

  2. Update the timestamp of the .reload file to load the changes.

    In UNIX: touch .reload

See Also

Another method for updating an application or module is to use the sun-appserv-update task with the GlassFish Server Ant tasks. See Chapter 3, Using Ant with GlassFish Server, in Oracle GlassFish Server 3.0.1 Application Development Guide.

ProcedureTo Deploy an Application or Module Automatically

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.

  1. (Optional) Use the set(1) subcommand to adjust the autodeployment interval.

    This sets the interval at which applications and modules are checked for code changes and dynamically reloaded. The default is 2.

  2. (Optional) Use the set(1) subcommand to enable JSP precompilation.

  3. Copy your archive file to the autodeploy directory.

    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–15 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–16 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 help set at the command line.

ProcedureTo Deploy an Application or Module by Using a Deployment Plan

In the deployment plan for an EAR file, the sun-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).

  1. Ensure that the server is running.

    Remote commands require a running server.

  2. Deploy the application or module by using the deploy(1) subcommand with the --deploymentplan option.

    Note –

    Deployment directories might change between GlassFish Server releases.

Example 2–17 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–18 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 sun-application.xml
370 Thu Mar 13 15:37:48 PST 2003 RosterClient.war.sun-web.xml
418 Thu Mar 13 15:37:48 PST 2003 roster-ac.jar.sun-application-client.xml
1281 Thu Mar 13 15:37:48 PST 2003 roster-ejb.jar.sun-ejb-jar.xml
2317 Thu Mar 13 15:37:48 PST 2003 team-ejb.jar.sun-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–19 Deployment Plan Structure for a Web Module

In the deployment plan for a web 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 sun-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.

ProcedureTo Deploy an Application or Module in a Directory Format

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, 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. The directories that hold modules must be named with suffixes that identify the type of archive that the structure is based on, such as _jar or _war.

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.

Before You Begin

The directory must be accessible to the machine on which GlassFish Server runs.

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.

  1. Ensure that the server is running.

    Remote commands require a running server.

  2. Verify that the expanded directory contents match the archive file.

    For information about the required directory contents, see the appropriate specifications.

  3. Deploy the directory by using the deploy(1) subcommand and specifying the path to the expanded directory.

    Note –

    Deployment directories might change between GlassFish Server releases.

Example 2–20 Deploying an Application From a Directory

This example deploys the expanded directory for the hello application. The path name is stored in the domain configuration file (domain.xml).


asadmin> deploy --name hello
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.