Deploying Applications

This chapter provides procedures and guidelines for deploying applications and modules in the Payara Server environment by using the `asadmin`command-line utility.

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:

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
To Deploy an Application or Module in a Directory Format
To Deploy an Application on Server start
To Deploy from a URL
To Deploy using a Maven Artifact

Instructions for accomplishing these tasks by using the Administration Console are contained in the Administration Console online help.

To Deploy an Application or Module

Use the deploy subcommand in remote mode to deploy an assembled application or module to Payara 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. The redeploy subcommand also accomplishes this. See this example.

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 Payara Server runtime deployment descriptor. See this example for more information.

For more information about deployment descriptors associated with Payara Server, 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 this example for more information.

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.

Ensure that the server is running. Remote commands require a running server.
List deployed applications by using the list-applications subcommand.
Deploy the application or module by using the deploy subcommand.

Information about the options and properties of the subcommand is included in this help page.
If needed, fix issues and rerun the deploy subcommand.

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

Example - 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 an application archive. Specify an absolute path or a relative path to the alternate deployment descriptor file.

asadmin> deploy --altdd path_to_alternate_descriptor cart.ear
Application deployed successfully with name cart.
Command deploy executed successfully

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

asadmin deploy --deploymentorder 102 --name cart cart.war

asadmin deploy --deploymentorder 110 --name horse horse.war

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

To Change Targets for a Deployed Application or Module

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.

Ensure that the server is running. Remote commands require a running server.
Add and remove targets by using the create-application-ref and delete-application-ref subcommands.

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.

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

Ensure that the server is running. Remote commands require a running server.
List the desired applications by using the list-applications subcommand or the list-sub-components subcommand.

Information about these commands is included in these help pages.
Show the status of a deployed component by using the show-component-status subcommand.

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

asadmin> list-applications --type web
hellojsp <web>
Command list-applications executed successfully

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

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

Ensure that the server is running.

Remote commands require a running server.
Redeploy an application or module by using the redeploy subcommand or the deploy subcommand with the --force option.

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

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

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

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

An application or module is enabled by default.

Ensure that the server is running. Remote commands require a running server.
Obtain the exact name of the application or module that you are disabling.
To list deployed applications or modules, use the list-applications 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 subcommand.
Deactivate the application or module by using the disable subcommand.

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

Example - 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-12 Disabling a Web Application

This example disables the hellojsp application.

asadmin> disable hellojsp
Command disable executed successfully.

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

To Enable an Application or Module

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.

Ensure that the server is running. Remote commands require a running server.
Enable the application or module by using the enable 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 subcommand.

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

Example - Enabling an Application

This example enables the sampleApp application.

asadmin> enable sampleApp
Command enable executed successfully.

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

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

Ensure that the server is running. Remote commands require a running server.
Obtain the exact name of the application or module you are un-deploying.

To list deployed applications or modules, use the list-applications 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 subcommand.
Undeploy the application or module by using the undeploy subcommand.

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

Example 2-14 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 - Un-deploying an Application

This example uninstalls the hellojsp application.

asadmin> undeploy hellojsp
hellojsp <web>
Command undeploy executed successfully.

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

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

Go to the root directory of the deployed application or module.

For an application:
```
domain-dir/applications/app-name
```
For an individually deployed module:
```
domain-dir/applications/module-name
```
Deployment directories might change between Payara Server releases.
Create or update the timestamp of the .reload file to load the changes.

For UNIX: touch .reload

For Windows: echo> .reload

If the .reload file doesn’t exist, the touch or echo command creates it.

To Deploy an Application or Module Automatically

This task is best suited for use in a development environment.

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

Use the set subcommand to adjust the auto-deployment interval.

This sets the interval at which applications and modules are checked for code changes and dynamically reloaded. The default is 2.
Use the set subcommand to enable JSP precompilation.
Copy your archive file to the auto-deploy 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 auto-deploy directory.

Deployment directories might change between Payara Server releases.

Example - Setting the Auto-deployment Interval

This example sets the auto-deployment interval to 3 seconds (default is 2).

asadmin set server.admin-service.das-config.autodeploy-polling-interval-in-seconds=3
Command set executed successfully.

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

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

To Deploy an Application or Module by Using a Deployment Plan

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

Ensure that the server is running. Remote commands require a running server.
Deploy the application or module by using the deploy subcommand with the --deploymentplan option.

Deployment directories might change between Payara Server releases.

Example - 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 - 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 - Deployment Plan Structure for an EJB Module

In the deployment plan for an EJB module, the deployment descriptor that is specific to Payara 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

To Deploy an Application or Module in a Directory Format

This task is best suited for use in a development environment.

An expanded directory, also known as an exploded directory, contains an un-assembled (un-packaged) 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 Payara Server as the same user to which the mapped drive is assigned. This enables Payara Server to access the directory.

Ensure that the server is running. Remote commands require a running server.
Verify that the expanded directory contents match the archive file.

For information about the required directory contents, see the appropriate specifications.
Deploy the directory by using the deploy subcommand and specifying the path to the expanded directory.

Deployment directories might change between Payara Server releases.

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

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

To Deploy an Application on Server Start

As described in To Deploy an Application or Module Automatically Payara Server has the ability to automatically deploy applications on server start using the autodeploy directory. While acceptable in development environments, the internal scanner used to deploy files in this directory is a security risk for production environments.

To introduce the capability of deploying an application on server startup without the risk of enabling the deployment scanner, Payara Server has the ability to run asadmin commands at startup via command scripts, either before or after the server’s boot sequence has been completed.

To enable this feature, the start-domain Asadmin command accepts two extra options: --prebootcommandfile and --postbootcommandfile which can be used as follows:

Pre-boot command script usage

asadmin start-domain --prebootCommandFile=/path/to/file

Due to the time during boot when the commands in this file are executed, this only supports set commands.

Post-boot command script usage

asadmin start-domain --postbootCommandFile=/path/to/file

To deploy an application at startup time, simply create a command script that deploys the application like so:

deployment-script.asadmin

deploy --name MyApp /path/to/deployment/archive

And use this script file with the --postbootCommandFile option:

Post-boot command script usage

asadmin start-domain --postbootCommandFile=deployment-script.asadmin

Post boot command scripts will guarantee that applications will be deployed AFTER the server has completed its boot sequence, guaranteeing that all required resources will be available for the application to use.

Command Script Considerations

There are some considerations to have on how to structure command scripts:

Script files should be saved in a text format, with each command on its own line.
Lines where the first non-whitespace character is # are treated as comments
Any blank lines will be ignored
Any invalid or failing commands will be logged to the server log and the file will continue to be processed.
Script files must exist, and be accessible by the server instance.
Both pre-boot and post-boot script files can be passed at the same time when starting the domain.

To Deploy from a URL

Payara Server also has the ability to deploy applications whose archives are hosted on a remote location. To deploy an application archive that can be reached via its URL, use the deploy-remote-archive subcommand, which works similarly to the standard deploy command, and can be used in the same way.

The only difference in the command is that it takes a valid URL instead of a file location in the host’s filesystem.

Example - Deploying by Using a URL

The following example showcases how to deploy an application’s archive for the clusterjsp application hosted in the https://nexus.payara.fish/repository/payara-artifacts remote repository using the deploy-remote-archive subcommand:

asadmin deploy-remote-archive https://nexus.payara.fish/repository/payara-artifacts/fish/payara/testing/clusterjsp/1.1/clusterjsp-1.1.war

The command will only accept HTTP and HTTPS URLs.

To Deploy using a Maven artifact

Payara Server also has the ability to deploy applications whose archives are hosted as Maven artifacts on remote repositories. To deploy an application archive in this manner, use the deploy-remote-archive subcommand, which works similarly to the standard deploy command, and point it to a set of Maven GAV (Group ID/Artifact ID/Version) coordinates where the artifact is located.

By default, the command will search for the artifact in Maven Central, but specific Maven repositories can be added as search locations by using the additionalRepositories option, which accepts a comma separated list of repository URLs.

Example - Deploying by Using a Maven Artifact

The following example showcases how to deploy an application’s archive for the clusterjsp-1.1.1.war application artifact which is located in the https://nexus.payara.fish/repository/payara-artifacts Maven repository using the deploy-remote-archive subcommand:

If an application matching the GAV coordinates exists on multiple repositories, the first found will be deployed. The order that the repositories are searched is the order that you specify them in.
For example, given an additionalRepositories of repo1,repo2, the order that the repositories would be searched is: Maven Central → repo1 → repo2.

asadmin deploy-remote-archive --additionalRepositories https://nexus.payara.fish/repository/payara-artifacts fish.payara.testing,clusterjsp,1.1

Modifying the Configuration of a Web Application or Module

You can modify the configuration of a web application or a module by modifying the deployment descriptors and then repackaging and redeploying the application.

The instructions in this section enable you to change the configuration of a deployed application without the need to modify the application’s deployment descriptors and repackage and redeploy the application. If the application or module entry is unset, its value reverts to the value, if any, that is set in the application’s deployment descriptor.

The following topics are addressed here:

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

To Set a Web Context Parameter

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:

A deployed web application
A web module in a deployed Jakarta EE application

Before You Begin

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

Ensure that the server is running.

Remote commands require a running server.
Set a servlet context-initialization parameter by using the set-web-context-param subcommand.

Information about the options for the subcommand is included in this help page.

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

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

asadmin> set-web-context-param --name= jakarta.faces.STATE_SAVING_METHOD --description="The location where the application?s state is preserved" --value=client basic-ezcomp

Command set-web-context-param executed successfully.

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

To Unset a Web Context Parameter

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:

A deployed web application
A web module in a deployed Jakarta EE application

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.

Ensure that the server is running.

Remote commands require a running server.
Unset an environment entry by using the unset-web-context-param subcommand.

Information about the options for the subcommand is included in this help page.

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

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

asadmin unset-web-context-param --name= jakarta.faces.STATE_SAVING_METHOD basic-ezcomp
Command unset-web-context-param executed successfully.

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

To List Web Context Parameters

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:

The name of the parameter
The value to which the parameter is set
The value of the --ignoreDescriptorItem option of the set-web-context-param subcommand that was specified when the parameter was set
The description of the parameter or null if no description was specified when the parameter was set
1. Ensure that the server is running.
  
  Remote commands require a running server.
2. List servlet context-initialization parameters by using the list-web-context-param subcommand.

Example - 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 jakarta.faces.PROJECT_STAGE parameter was set, null is displayed instead of a description for this parameter.

asadmin list-web-context-param basic-ezcomp jakarta.faces.STATE_SAVING_METHOD = client ignoreDescriptorItem=false

jakarta.faces.PROJECT_STAGE = null ignoreDescriptorItem=true
Command list-web-context-param executed successfully.

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

To Set a Web Environment Entry

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:

A deployed web application
A web module in a deployed Jakarta EE application

Before You Begin

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

Ensure that the server is running.

Remote commands require a running server.
Set an environment entry for a deployed web application or module by using the set-web-env-entry subcommand.

Information about the options for the subcommand is included in this help page.

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

asadmin> set-web-env-entry --name="Hello User" --type=java.lang.String --value=techscribe --description="User authentication for Hello appplication" hello

Command set-web-env-entry executed successfully

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

To Unset a Web Environment Entry

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

Ensure that the server is running.

Remote commands require a running server.
Unset a web environment entry by using the unset-web-env-entry subcommand.

Information about the options for the subcommand is included in this help page.

Example - Unsetting an Environment Entry for a Web Application

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

asadmin unset-web-env-entry --name="Hello User" hello
Command unset-web-env-entry executed successfully.

To List Web Environment Entries

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:

The name of the entry
The Java type of the entry
The value to which the entry is set
The description of the entry or null if no description was specified when the entry was set
The value of the --ignoreDescriptorItem option of the set-web-env-entry subcommand that was specified when the entry was set
1. Ensure that the server is running.
  
  Remote commands require a running server.
2. List the environment entries by using the list-web-env-entry subcommand.

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

asadmin list-web-env-entry hello

Hello User (java.lang.String) = techscribe ignoreDescriptorItem=false
Hello Port (java.lang.Integer) = null ignoreDescriptorItem=true
Command list-web-env-entry executed successfully.

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

Web Module Deployment Guidelines

The following guidelines apply to deploying a web module in Payara Server:

Context Root. When you deploy a web module, if you do not specify a context root, the default is the name of the WAR file without the .war extension. The web module context root must be unique within the server instance.

The domain administration server (DAS) in Payara Server supports the deployment of multiple web applications using the same web context root as long as those applications are deployed to different Payara Server stand-alone instances.

Deploying multiple applications using the same context root within a single instance produces an error.
Data Source. If a web application accesses a DataSource that is not specified in a resource-ref in glassfish-web.xml or payara-web.xml, or there is no glassfish-web.xml or payara-web.xml files, the resource-ref-name defined in web.xml is used.

A warning message is logged, recording the JNDI name that was used to look up the resource.
Virtual Servers. If you deploy a web application and do not specify any assigned virtual servers, the web application is assigned to all currently-defined virtual servers except the virtual server with ID __asadmin, which is reserved for administrative purposes.

If you then create additional virtual servers and want to assign existing web applications to them, you must redeploy the web applications.
HTTP Sessions. If a web application is un-deployed, all its HTTP sessions will be invalidated and removed, unless the application is being un-deployed as part of a redeployment and the --keepstate deployment option was set to true.

This option is not supported and ignored in a clustered environment. See this example.

For information about HTTP session persistence, see the Payara Server High Availability section.
JSP Precompilation. You can precompile JSP files during deployment by checking the appropriate box in the Administration Console, or by using the --precompilejsp option of the deploy subcommand.

You can keep the generated source for JSP files by adding the keepgenerated flag to the jsp-config element in glassfish-web.xml or payara-web.xml.

For example:
```
<glassfish-web-app>
   <jsp-config>
      <property name="keepgenerated" value="true" />
   </jsp-config>
</glassfish-web-app>
```
If you include this property when you deploy the WAR file, the generated source is kept in domain-dir/generated/jsp/app-name/module-name for an application, or domain-dir/generated/jsp/module-name for an individually-deployed web module.

For more information about JSP precompilation, see jsp-config.
Web Context Parameters. You can set web context parameters after deployment. See the following sections:
Web Environment Entries. You can set web environment entries after deployment. See the following sections:

EJB Module Deployment Guidelines

The Payara Server Web Profile supports the Jakarta Enterprise Beans 4.0 Lite specification, which allows enterprise beans within web applications, among other features.
The Payara Server Full Platform Profile supports the entire Jakarta Enterprise Beans 4.0 specification. For details, see Jakarta Enterprise Beans

The following guidelines apply to deploying an EJB module in Payara Server:

JNDI Name. — If no JNDI name for the EJB JAR module is specified in the jndi-name element immediately under the ejb element in glassfish-ejb-jar.xml, or there is no glassfish-ejb-jar.xml file, a default, non-clashing JNDI name is derived.

A warning message is logged, recording the JNDI name used to look up the EJB JAR module.

Because the Jakarta Enterprise Beans 4.0 specification defines portable EJB JNDI names, there is less need for Payara Server specific JNDI names. By default, Payara Server specific default JNDI names are applied automatically for backward compatibility.

To disable Payara Server specific JNDI names for an EJB module, set the value of the <disable-nonportable-jndi-names> element in the glassfish-ejb-jar.xml file to true. The default is false.
Stateful Session Bean and Timer State. — Use the --keepstate option of the redeploy subcommand or the <keepstate> element in the glassfish-ejb-jar.xml file to retain stateful session bean instances and persistently created EJB timers across re-deployments.

The --keepstate option of the redeploy subcommand takes precedence. The default for both is false. This option is not supported and ignored in a clustered environment.

Some changes to an application between re-deployments can prevent this feature from working properly. For example, do not change the set of instance variables in the SFSB bean class. Other examples would be changes to EJB names, or adding or removing EJBs to or from an application.
EJB Singletons. — EJB Singletons are created for each server instance in a cluster, and not once per cluster or deployment group. Check the Clustered Singleton proprietary feature of the Public API on how to achieve this.
Stubs and Ties. — Use the get-client-stubs subcommand in remote mode to retrieve stubs and ties.

Compatibility of JAR Visibility Requirements. — Use the compatibility element of the glassfish-application.xml or glassfish-ejb-jar.xml file to specify the Payara Server release with which to be backward compatible in terms of JAR visibility requirements for applications.

The current allowed value is v2, which refers to older runtimes from where Payara Server is based from.

Starting in Java EE 6, the Java EE specification imposes stricter requirements than Java EE 5 did on which JAR files can be visible to various modules within an EAR file. Setting this element to v2 removes these Java EE 6 and later restrictions.

Deploying a Connector Module

Deploying a stand-alone connector module allows multiple deployed Jakarta EE applications to share the connector module. A resource adapter configuration is automatically created for the connector module.

The following topics are addressed here:

To Deploy and Configure a Stand-Alone Connector Module
Redeploying a Stand-Alone Connector Module
Deploying and Configuring an Embedded Resource Adapter

To Deploy and Configure a Stand-Alone Connector Module

As an alternative to Step 3 through Step 6, you can define application-scoped resources in the glassfish-resources.xml or payara-resources.xml deployment descriptor.

For more information, see Application-Scoped Resources.

Ensure that the server is running.

Remote commands require a running server.
Deploy the connector module by using the deploy subcommand.
Configure connector connection pools for the deployed connector module.

Use the create-connector-connection-pool subcommand. For procedures, see "To Create a Connector Connection Pool" in the General Administration section.
Configure connector resources for the connector connection pools.

Use the create-resource-adapter-config subcommand. For procedures, see "To Create Configuration Information for a Resource Adapter" in the General Administration section.

If needed, you can override the default configuration properties of a resource adapter.

This step associates a connector resource with a JNDI name.
Configure a resource adapter.

Use the create-resource-adapter-config subcommand. For procedures, see "To Create Configuration Information for a Resource Adapter" in the General Administration section.

If needed, you can override the default configuration properties of a resource adapter.
If needed, create an administered object for an inbound resource adapter.

Use the create-admin-object subcommand. For procedures, see "To Create an Administered Object" in the General Administration section.

Redeploying a Stand-Alone Connector Module

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 the Application Development section.

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, Payara Server provides an error message.

Deploying and Configuring an Embedded Resource Adapter

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 un-deployed 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 Payara Server and the logical JNDI name used in the application component is specified in the Payara Server-specific XML descriptor glassfish-ejb-jar.xml.

Assembling and Deploying an Application Client Module

Deployment is necessary for application clients that communicate with EJB components.

The Application Client Container is supported only in the Payara Server Full Platform Profile, not in the Web Profile.

The following topics are addressed here:

To Assemble and Deploy an Application Client
To Prepare Another Machine for Running an Application Client
To Undeploy an Application Client

To Assemble and Deploy an Application Client

Assemble the necessary client components.

The client JAR file is created.
Assemble the EJB components that are to be accessed by the client.

The EJB JAR file is created.
Assemble the client and EJB JAR files together in an EAR.

An EAR file contains all the components of the application.
Deploy the application.

Instructions are contained in To Deploy an Application or Module.
If you are using the appclient script to run the application client, retrieve the client files.

The client artifacts contain the ties and necessary classes for the application client. Client artifacts include multiple files.

You can use either the get-client-stubs subcommand or the --retrieve option of the deploy subcommand, but you do not need to use both.
- Use the deploy subcommand with the --retrieve option to retrieve the client files as part of deploying the application.
- Use the get-client-stubs subcommand to retrieve client files for a previously-deployed application.
Test the client on the Payara Server machine by using the appclient script.

The appclient script is located in the as-install/bin directory.

If you are using the default server instance, the only required option is -client, which points to the client JAR file. For example:
```
appclient -client converterClient.jar
```
The -xml parameter, which specifies the location of the sun-acc.xml file, is also required if you are not using the default instance.

For more detailed information about the appclient script, see appclient.

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

Accessing EJB components and JMS resources from application clients
Connecting to a remote EJB module through a firewall
Using Java Web Start and creating a custom JNLP file
Using libraries with application clients
Specifying a splash screen, login retries, and other customizations

To Prepare Another Machine for Running an Application Client

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.

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.

Create the application client package JAR file.

Use the package-appclient script in the as-install/bin directory. This JAR file is created in the as-install/lib/appclient directory.
Copy the application client package JAR file to the client machine.
Extract the contents of the JAR file.

For example: jar xf filename.jar
Configure the sun-acc.xml file.

If you used the package-appclient script, this file is located in the appclient/appserv/lib/appclient directory by default.
Configure the asenv.conf (asenv.bat on Windows) file.

This file is located in appclient/appserv/bin by default if you used the package-appclient script.
Copy the client JAR file to the client machine.

You are now ready to run the client.

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

To Undeploy an Application Client

After application clients are downloaded, they remain on the client until they are manually removed.

If you undeploy an application client, you can no longer 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.

Lifecycle Module Deployment Guidelines

A lifecycle module, also called a lifecycle listener module, provides a means of running long or short Java-based tasks within the Payara Server environment, such as instantiation of singletons or RMI servers.

Lifecycle modules are automatically initiated at server startup and are notified at various phases of the server life cycle. All lifecycle module interfaces are in the as-install/modules/glassfish-api.jar file.

For general information about lifecycle modules, see "Developing Lifecycle Listeners" in the Application Development section.

You can deploy a lifecycle module using the create-lifecycle-module subcommand. Do not use asadmin deploy or related commands.

You do not need to specify a classpath for the lifecycle module if you place it in the domain-dir/lib or domain-dir/lib/classes directory for the Domain Administration Server (DAS). Do not place it in the lib directory for a particular server instance, or it will be deleted when that instance synchronizes with Payara Server.

After you deploy a lifecycle module, you must restart the server. During server initialization, the server instantiates the module and registers it as a lifecycle event listener.

If the --failurefatal option of create-lifecycle-module is set to true (the default is false), lifecycle module failure prevents server initialization or startup, but not shutdown or termination.

Web Service Deployment Guidelines

If you installed the Web Profile, web services are not supported unless the optional Metro Web Services Stack add-on component is downloaded.
Without the Metro add-on component, a servlet or EJB component cannot be a web service endpoint, and the glassfish-web.xml/payara-web.xml and glassfish-ejb-jar.xml elements related to web services are ignored.

The following guidelines apply when deploying a web service in Payara Server:

Web Service Endpoint. Deploy a web service endpoint to Payara Server as you would any servlet or stateless session bean.

If the deployed application or module has a web service endpoint, the endpoint is detected automatically during deployment.

The Payara Server specific deployment descriptor files, glassfish-web.xml, payara-web.xml and glassfish-ejb-jar.xml, provide optional web service enhancements in their webservice-endpoint and webservice-description elements.
Web Service Management. Web service management is fully supported in the Administration Console. After the application or module is deployed, click the Web Service component. The table in the right frame lists deployed web service endpoints.

For more information about web services, see "Developing Web Services" in the Application Development section.

OSGi Bundle Deployment Guidelines

To deploy an OSGi bundle using the Administration Console, select Other from the Type drop-down list and check the OSGI Type checkbox.

To deploy an OSGi bundle using the asadmin deploy command, set the --type option to the value osgi. For example:

asadmin deploy --type=osgi MyBundle.jar

To automatically deploy an OSGi bundle, copy the bundle archive to the domain-dir/autodeploy/bundles directory.

For components packaged as OSGi bundles (--type=osgi), the deploy subcommand accepts properties arguments to wrap a WAR file as a WAB (Web Application Bundle) at the time of deployment. The subcommand looks for a key named UriScheme and, if present, uses the key as a URL stream handler to decorate the input stream.

Other properties are used in the decoration process. For example, the Payara Server OSGi web container registers a URL stream handler named webbundle, which is used to wrap a plain WAR file as a WAB.

Transparent JDBC Connection Pool Reconfiguration

In this Payara Server release, reconfiguration of a JDBC connection pool due to attribute or property changes can be transparent to the applications or modules that use the pool, even if pool reconfiguration results in pool recreation. You do not need to redeploy the application or module.

To enable transparent pool reconfiguration, set the dynamic-reconfiguration-wait-timeout-in-seconds property. This property specifies the timeout for dynamic reconfiguration of the pool.

In-progress connection requests must complete before this timeout expires, or they must be retried. New connection requests wait for this timeout to expire before acquiring connections to the reconfigured pool. If this property exists and has a positive value, it is enabled.

You can set this property in the glassfish-resources.xml or payara-resources.xml file. For more information, see the property descriptions under jdbc-connection-pool.

For JDBC connection pools that are not application-scoped, use the set subcommand to set this property. For example, to configure mypool on myserver, type the following all on one line:

asadmin set myserver.resources.jdbc-connection-pool.mypool.property.dynamic-reconfiguration-wait-timeout-in-seconds=30

Application-Scoped Resources

You can define an application-scoped JDBC resource or other resource for an enterprise application, web module, EJB module, connector module, or application client module. This allows single-step deployment for resource-dependent modules and applications.

An application-scoped resource has the following characteristics:

It is available only to the module or application that defines it.
It cannot be referenced or looked up by other modules or applications.
It is created during deployment, destroyed during un-deployment, and recreated during redeployment.
It is free from unexpected resource starvation or delay in acquiring connections because no other application or module competes for accesses to it.

The following resource types can be application-scoped:

JDBC connection pools
JDBC resources
Connector connection pools
Connector resources
Resource adapters
External JNDI resources
Custom resources
Admin object resources
Jakarta resources

Deployment Descriptor: An application-scoped resource is defined in the glassfish-resources.xml or payara-resources.xml deployment descriptor file. This file is placed in the META-INF directory of the module or application archive.

For web applications or modules, this file is placed in the WEB-INF directory. If any submodule archives of an enterprise application archive have their own glassfish-resources.xml or payara-resources.xml files, the resource definitions are scoped to those modules only.

For more information about the glassfish-resources.xml and payara-resources.xml file, see Payara Server Deployment Descriptor Files and Elements of the Payara Server Deployment Descriptors.

Naming: Application-scoped resource JNDI names begin with java:app or java:module. If one of these prefixes is not specified in the JNDI name, it is added. For example, application-scoped databases have JNDI names in the following format: java:app/jdbc/DataSourceName or java:module/jdbc/DataSourceName.

Errors: Application-scoped resource definitions with same resource name, resource type, attributes, and properties are duplicates. These generate WARNING level log messages and deployment continues.

Definitions with the same resource name and type but different attributes or properties are conflicts and cause deployment failure. When an application or module tries to look up a scoped resource that does not belong to it, a naming exception is thrown.

Redeployment: When an application or module is un-deployed, its scoped resources are deleted. During redeployment, resources are destroyed and recreated based on changes in the glassfish-resources.xml or payara-resources.xml file.

To preserve old resource definitions during redeployment, use the preserveAppScopedResources property of the redeploy (or deploy --force=true) subcommand. For example:

asadmin> redeploy --property preserveAppScopedResources=true MyApp.ear

asadmin> deploy --force=true --property preserveAppScopedResources=true MyApp.ear

For more information, see redeploy and deploy.

Listing: Use the --resources option of the list-applications subcommand to list application-scoped resources. Use the --subcomponents option in addition to list scoped resources for enterprise application modules or for module subcomponents.

To list scoped resources for subcomponents only, use the --resources option of the list-subcomponents subcommand

For more information, see list-applications and list-sub-components.

Restrictions. Use of application-scoped resources is subject to the following restrictions:

resource-adapter-config and connector-work-security-map — These can only be specified in the glassfish-resources.xml or payara-resources.xml file of the corresponding connector module.

In an enterprise application, the resource-adapter-config or connector-work-security-map for an embedded connector module must be specified in the glassfish-resources.xml or payara-resources.xml file of the connector module.

You cannot specify a resource-adapter-config or connector-work-security-map in an application for a connector module that is not part of the application.
Resource to connection pool cross references — A module-level jdbc-resource cannot reference an application-level jdbc-connection-pool. Likewise, a module-level connector-resource cannot reference an application-level connector-connection-pool.
Global resources — Defining java:global JNDI names is not supported.
Cross definitions — Defining java:app JNDI names at the module level is not supported.

Deploying Applications