Deploying Applications

Use the deploy subcommand in remote mode to deploy an assembled application or module to Eclipse GlassFish. 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. The redeploy subcommand also accomplishes this. See Example 2-10. You can see the enabled or disabled status of an application or module by using the show-component-status subcommand.

For information about how the application or module name is derived, see Naming Standards.

Use the --altdd or --runtimealtdd options of the deploy (and redeploy) subcommand to deploy an application or module using a top-level alternate deployment descriptor. The --altdd option specifies a top-level alternate Jakarta EE standard deployment descriptor. The --runtimealtdd option specifies a top-level alternate Eclipse GlassFish runtime deployment descriptor. See Example 2-3. For more information about deployment descriptors associated with Eclipse GlassFish, see Deployment Descriptors and Annotations.

You can also specify the deployment order of an application by using the --deploymentorder option of the deploy (and redeploy) subcommand. This is useful for applications that must be loaded in a certain order at server startup. Applications with lower deployment order numbers are loaded first. See Example 2-4. If a deployment order is not specified at the time an application is deployed, the default deployment order of 100 is assigned. If two applications have the same deployment order, the application that was deployed first is loaded first at server startup.

Example 2-1 Deploying an Enterprise Application

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

Example 2-2 Deploying a Connector Module

This example deploys a connector module that is packaged in an RAR file.

Example 2-3 Using an Alternate Jakarta EE Standard Deployment Descriptor

This example deploys an application using an alternate Jakarta EE standard deployment descriptor file that resides outside of an application archive. Specify an absolute path or a relative path to the alternate deployment descriptor file.

Example 2-4 Specifying the Deployment Order of an Application

This example specifies the deployment order of two applications. The cart application is loaded before the horse application at server startup.

Some lines of output are omitted from this example for readability.

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.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin 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.

Example 2-5 Listing Applications

The list-applications subcommand lists all deployed Jakarta EE applications or modules. If the --type option is not specified, all components are listed. This example lists deployed applications.

Example 2-6 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.

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

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.

Example 2-8 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.

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

Example 2-9 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.

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

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.

Example 2-11 Listing Deployed Web Applications

This example lists all deployed web applications.

Example 2-12 Disabling a Web Application

This example disables the hellojsp application.

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.

Example 2-13 Enabling an Application

This example enables the sampleApp application.

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.

Example 2-14 Listing Deployed Applications or Modules

This example lists all applications of type web.

Example 2-15 Undeploying an Application

This example uninstalls the hellojsp application.

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.

Automatic deployment involves copying an archive file into a special autodeploy directory where the archive is automatically deployed by Eclipse GlassFish 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.

Example 2-16 Setting the Autodeployment Interval

This example sets the autodeployment inverval to 3 seconds (default is 2).

Example 2-17 Setting JSP Precompilation

This example enables JSP precompilation (default is false).

See Also

You can also view the full syntax and options of the subcommand by typing asadmin set --help at the command line.

A Deployment Plan is a ZIP or JAR archive with a collection of descriptor files that are merged into the application or module archive being deployed. This allows deploying the same archive with different descriptors tailored for the specific 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 Eclipse GlassFish as the same user to which the mapped drive is assigned. This enables Eclipse GlassFish to access the directory.

Example 2-23 Deploying an Application From a Directory

This example deploys the expanded directory /apps/MyApp for the hello application.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help deploy at the command line.

Use the set-web-context-param subcommand in remote mode to change the configuration of a deployed application without the need to modify the application’s deployment descriptors and repackage and redeploy the application. By using this subcommand, you are either adding a new parameter that did not appear in the original web module’s descriptor, or overriding the descriptor’s setting of the parameter.

If the --ignoreDescriptorItem option is set to true, then the server ignores any setting for that context parameter in the descriptor, which means you do not need to specify an overriding value on the set-web-context-param subcommand. The server behaves as if the descriptor had never contained a setting for that context parameter.

This subcommand sets a servlet context-initialization parameter of one of the following items:

Before You Begin

The application must already be deployed. Otherwise, an error occurs.

Example 2-24 Setting a Servlet Context-Initialization Parameter for a Web Application

This example sets the servlet context-initialization parameter javax.faces.STATE_SAVING_METHOD of the web application basic-ezcomp to client.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help set-web-context-param at the command line.

Use the unset-web-context-param subcommand in remote mode to unset an environment entry for a deployed web application or module that has been set by using the set-web-env-entry subcommand. There is no need to modify the application’s deployment descriptors and repackage and redeploy the application.

This subcommand unsets an environment entry for one of the following items:

When an entry is unset, its value reverts to the value, if any, that is set in the application’s deployment descriptor. This subcommand cannot be used to change the value of an environment entry that is set in an application’s deployment descriptor. Instead, use the set-web-context-param subcommand for this purpose.

Before You Begin

The application must already be deployed, and the entry must have previously been set by using the set-web-env-entry subcommand. Otherwise, an error occurs.

Example 2-25 Unsetting a Servlet Context-Initialization Parameter for a Web Application

This example unsets the servlet context-initialization parameter javax.faces.STATE_SAVING_METHOD of the web application basic-ezcomp.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help unset-web-context-param at the command line.

Use the list-web-context-param subcommand in remote mode to list the parameters that have previously been set by using the set-web-context-param subcommand. The subcommand does not list parameters that are set only in the application’s deployment descriptor. For each parameter, the following information is displayed:

Example 2-26 Listing Servlet Context-Initialization Parameters for a Web Application

This example lists all servlet context-initialization parameters of the web application basic-ezcomp that have been set by using the set-web-context-param subcommand. Because no description was specified when the javax.faces.PROJECT_STAGE parameter was set, null is displayed instead of a description for this parameter.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-web-context-param at the command line.

An application uses the values of environment entries to customize its behavior or presentation. Use the set-web-env-entry subcommand in remote mode to change the configuration of a deployed application without the need to modify the application’s deployment descriptors and repackage and redeploy the application. By using this subcommand, you are either adding a new parameter that did not appear in the original web module’s descriptor, or overriding the descriptor’s setting of the parameter.

If you the --ignoreDescriptorItem option is set to true, then the server ignores any setting for that environment entry in the descriptor, which means you do not need to specify an overriding value on the set-web-env-entry subcommand. The server behaves as if the descriptor had never contained a setting for that environment entry.

This subcommand sets an environment entry for one of the following items:

Before You Begin

The application must already be deployed. Otherwise, an error occurs.

Example 2-27 Setting an Environment Entry for a Web Application

This example sets the environment entry Hello User of the application hello to techscribe. The Java type of this entry is java.lang.String.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help set-web-env-entry at the command line.

Use the unset-web-env-entry subcommand in remote mode to unset an environment entry for a deployed web application or module.

Example 2-28 Unsetting an Environment Entry for a Web Application

This example unsets the environment entry Hello User of the web application hello.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help unset-web-env-entry at the command line.

Use the list-web-env-entry subcommand to list environment entries for a deployed web application or module. For each entry, the following information is displayed:

Example 2-29 Listing Environment Entries for a Web Application

This example lists all environment entries that have been set for the web application hello by using the set-web-env-entry subcommand.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-web-env-entry at the command line.

As an alternative to Step 3 through Step 6, you can define application-scoped resources in the glassfish-resources.xml deployment descriptor. For more information, see Application-Scoped Resources.

Redeployment of a connector module maintains all connector connection pools, connector resources, and administered objects defined for the previously deployed connector module. You do not need to reconfigure any of these resources.

However, you should redeploy any dependent modules. A dependent module uses or refers to a connector resource of the redeployed connector module. Redeployment of a connector module results in the shared class loader reloading the new classes. Other modules that refer to the old resource adapter classes must be redeployed to gain access to the new classes. For more information about class loaders, see "Class Loaders" in Eclipse GlassFish Application Development Guide.

During connector module redeployment, the server log provides a warning indicating that all dependent applications should be redeployed. Client applications or application components using the connector module’s resources may throw class cast exceptions if dependent applications are not redeployed after connector module redeployment.

To disable automatic redeployment, set the --force option to false. In this case, if the connector module has already been deployed, Eclipse GlassFish provides an error message.

A connector module can be deployed as a Jakarta EE component in a Jakarta EE application. Such connectors are only visible to components residing in the same Jakarta EE application. Deploy this application as you would any other Jakarta EE application.

You can create new connector connection pools and connector resources for a connector module embedded within a Jakarta EE application by prefixing the connector name with app-name`#. For example, if an application `appX.ear has jdbcra.rar embedded within it, the connector connection pools and connector resources refer to the connector module as appX#jdbcra.

An embedded connector module cannot be undeployed using the name app-name`#`connector-name. To undeploy the connector module, you must undeploy the application in which it is embedded.

The association between the physical JNDI name for the connector module in Eclipse GlassFish and the logical JNDI name used in the application component is specified in the Eclipse GlassFish-specific XML descriptor glassfish-ejb-jar.xml.

See Also

For more detailed information about the appclient script, see appclient(1M).

For more detailed information about creating application clients, see "Developing Java Clients" in Eclipse GlassFish Application Development Guide. This chapter includes information on the following topics:

If Java Web Start is enabled, the default URL format for an application is http://`host:port/``context-root. For example:

The default URL format for a standalone application client module is http://host:port/module-id. For example:

To set a different URL for an application client, set the context-root subelement of the java-web-start-access element in the glassfish-application-client.xml file.

If the context-root or module-id is not specified during deployment, the name of the EAR or JAR file without the .ear or .jar extension is used. For an application, the relative path to the application client JAR file is also included. If the application or module is not in EAR or JAR file format, a context-root or module-id is generated. Regardless of how the context-root or module-id is determined, it is written to the server log. For details about naming, see Naming Standards.

Before You Begin

This task applies if you want to use the appclient script to run the application client on a system other than where the server runs.

See Also

For more detailed information about Java Web Start and the package-appclient script, see appclient(1M).

After application clients are downloaded, they remain on the client until they are manually removed. Use the Java Web Start control panel to discard downloaded application clients that used Java Web Start.

If you undeploy an application client, you can no longer use Java Web Start, or any other mechanism, to download that application client because it might be in an inconsistent state. If you try to launch an application client that was previously downloaded (even though the server side of the application client is no longer present), the results are unpredictable unless the application client has been written to tolerate such situations.

You can write your application client so that it detects failures in contacting server-side components, but continues running. In this case, Java Web Start can run an undeployed application client while the client is cached locally. For example, your application client can be written to detect and then recover from javax.naming.NamingException when locating a resource, or from java.rmi.RemoteException when referring to a previously-located resource that becomes inaccessible.