This chapter provides procedures and guidelines for deploying applications and modules in the Oracle GlassFishTM Server environment by using the asadmin command-line utility.
The following topics are addressed here:
Instructions for accomplishing these tasks by using the Administration Console are contained in the Administration Console online help.
Application deployment is a dynamic process, which means that deployed applications and modules become available without requiring you to restart the server instance. Dynamic deployment can be useful in production environments to bring new applications and modules online easily. If you do restart the server, all deployed components are still deployed and available.
The following topics are addressed here:
Instructions for accomplishing these tasks by using the Administration Console are contained in the Administration Console online help.
Use the deploy subcommand in remote mode to deploy an assembled application or module to GlassFish Server. If an error occurs during deployment, the application or module is not deployed. 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.
Ensure that the server is running.
Remote commands require a running server.
(Optional) List deployed components by using the list-components(1) subcommand.
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.
(Optional) If needed, fix issues and rerun the deploy subcommand.
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 |
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 |
You can also view the full syntax and options of the subcommand by typing asadmin help deploy 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.
Ensure that the server is running.
Remote commands require a running server.
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.
Show the status of a deployed component by using the show-component-status(1).
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 |
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 |
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 |
The show-component-status subcommand gets the status (enabled or disabled) of the deployed component. This example gets the status of the MEjbApp component.
asadmin show-component-status MEjbApp Status of MEjbApp is enabled Command show-component-status executed successfully |
Use the redeploy subcommand in remote mode to overwrite a previously–deployed application or module. You can also accomplish this task by using the --force option of the deploy subcommand. Whenever a redeployment is done, the sessions in transit at that time become invalid unless you use the keepSessions=true property of the redeploy subcommand.
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(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.
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.
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. |
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.
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.
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(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.
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.
This example lists all deployed web applications.
asadmin> list-applications --type web hellojsp <web> Command list-applications executed successfully. |
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.
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.
Ensure that the server is running.
Remote commands require a running server.
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.
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.
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 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.
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.
This example lists all applications of type web.
asadmin> list-applications --type web hellojsp <web> Command list-applications executed successfully. |
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.
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.
Create an empty file named .reload at the root of the deployed application or module.
domain-dir/applications/module-name/.reload
Deployment directories might change between GlassFish Server releases.
Update the timestamp of the .reload file to load the changes.
In UNIX: touch .reload
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.
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.
(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.
(Optional) Use the set(1) subcommand to enable JSP precompilation.
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.
Deployment directories might change between GlassFish Server releases.
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. |
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 help set at the command line.
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).
Ensure that the server is running.
Remote commands require a running server.
Deploy the application or module by using the deploy(1) subcommand with the --deploymentplan option.
Deployment directories might change between GlassFish Server releases.
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. |
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 |
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 |
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.
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.
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.
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(1) subcommand and specifying the path to the expanded directory.
Deployment directories might change between GlassFish Server releases.
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help deploy at the command line.
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:
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 Java Platform, Enterprise Edition (Java EE) application
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(1) subcommand.
Information about the options for the subcommand is included in this help page.
This example sets the servlet context-initialization parameter javax.faces.STATE_SAVING_METHOD of the web application basic-ezcomp to client.
asadmin> set-web-context-param --name=javax.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.
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 Java Platform, Enterprise Edition (Java 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(1) subcommand for this purpose.
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(1) subcommand.
Information about the options for the subcommand is included in this help page.
This example unsets the servlet context-initialization parameter javax.faces.STATE_SAVING_METHOD of the web application basic-ezcomp.
asadmin> unset-web-context-param --name=javax.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.
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(1) 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
Ensure that the server is running.
Remote commands require a running server.
List servlet context-initialization parameters by using the list-web-context-param(1) subcommand.
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.
asadmin> list-web-context-param basic-ezcomp javax.faces.STATE_SAVING_METHOD = client ignoreDescriptorItem=false //The location where the application?s state is preserved javax.faces.PROJECT_STAGE = null ignoreDescriptorItem=true //null 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.
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 Java Platform, Enterprise Edition (Java EE) application
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(1) subcommand.
Information about the options for the subcommand is included in this help page.
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.
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(1) subcommand.
Information about the options for the subcommand is included in this help page.
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. |
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:
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
Ensure that the server is running.
Remote commands require a running server.
List the environment entries by using thelist-web-env-entry(1) subcommand.
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 //User authentication for Hello appplication Hello Port (java.lang.Integer) = null ignoreDescriptorItem=true //null 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.
The following guidelines apply to deploying a web module in GlassFish 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.
Data Source. If a web application accesses a DataSource that is not specified in a resource-ref in sun-web.xml, or there is no sun-web.xml file, 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 with the exception of 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 undeployed, all its HTTP sessions will be invalidated and removed, unless the application is being undeployed as part of a redeployment and the keepSessions deployment property was set to true. See Example 2–7. During a server shutdown, all HTTP sessions of a web application will be persisted to the file specified by the session-manager property with name sessionFilename in the web application's sun-web.xml deployment descriptor. To prevent HTTP sessions from being persisted during a server shutdown, specify the sessionFilename property with an empty value, as follows:
<sun-web-app> <session-config> <session-manager> <manager-properties> <property name="sessionFilename" value="" /> </manager-properties> </session-manager> </session-config> </sun-web-app>
The default location where HTTP sessions will be persisted during a server shutdown is given as domain-dir/generated/jsp/module-name/module-name_SESSIONS.ser
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. The GlassFish Server Ant tasks sun-appserv-deploy and sun-appserv-jspc also allow you to precompile JSP files. For more information, see Chapter 3, Using Ant with GlassFish Server, in Oracle GlassFish Server 3.0.1 Application Development Guide.
You can keep the generated source for JSP files by adding the keepgenerated flag to the jsp-config element in sun-web.xml. For example:
<sun-web-app> ... <jsp-config> <property name=keepgenerated value=true /> </jsp-config> </sun-web-app>
If you include this property when you deploy the WAR file, the generated source is kept in domain-dir/generated/jsp/module-name.
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:
The GlassFish Server Web Profile supports the EJB 3.1 Lite specification, which allows enterprise beans within web applications, among other features. The GlassFish Server Full Platform Profile supports the entire EJB 3.1 specification. For details, see JSR 318 (http://jcp.org/en/jsr/detail?id=318
The following guidelines apply to deploying an EJB module in GlassFish 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 sun-ejb-jar.xml, or there is no sun-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.
Stubs and Ties. Use the get-client-stubs(1) subcommand in remote mode to retrieve stubs and ties.
Deploying a standalone connector module allows multiple deployed Java EE applications to share the connector module. A resource adapter configuration is automatically created for the connector module.
The following topics are addressed here:
Ensure that the server is running.
Deploy the connector module by using the deploy(1) 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 Oracle GlassFish Server 3.0.1 Administration Guide.
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 Oracle GlassFish Server 3.0.1 Administration Guide. 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 Oracle GlassFish Server 3.0.1 Administration Guide. If needed, you can override the default configuration properties of a resource adapter.
(Optional) 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 Oracle GlassFish Server 3.0.1 Administration Guide.
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 Chapter 2, Class Loaders, in Oracle GlassFish Server 3.0.1 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, GlassFish Server provides an error message.
A connector module can be deployed as a Java EE component in a Java EE application. Such connectors are only visible to components residing in the same Java EE application. Deploy this application as you would any other Java EE application.
You can create new connector connection pools and connector resources for a connector module embedded within a Java 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 GlassFish Server and the logical JNDI name used in the application component is specified in the GlassFish Server–specific XML descriptor sun-ejb-jar.xml.
Deployment is necessary for application clients that communicate with EJB components or that use Java Web Start launch support. Java Web Start is supported for application clients and for applications that contain application clients. By default, Java Web Start is enabled in application clients and in GlassFish Server.
The Application Client Container is supported only in the GlassFish Server Full Platform Profile, not in the Web Profile.
This section addresses the following topics:
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 JAR file contains the ties and necessary classes for the application client. In this release of GlassFish Server, the client JAR file is made up of multiple files. Use either deploy --retrieve or get-client-stubs, but not both.
Use the deploy(1) subcommand with the --retrieve option to retrieve the client files as part of deploying the application.
Use the get-client-stubs(1) subcommand to retrieve client files for a previously-deployed application.
(Optional) Test the client on the GlassFish Server machine in one of the following ways:
If Java Web Start is enabled for the application client, use the Launch link on the Application Client Modules.
Run an application client 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 Java Web Start, see Chapter 11, Developing Java Clients, in Oracle GlassFish Server 3.0.1 Application Development Guide.
For more detailed information about the appclient script, see appclient(1M).
If Java Web Start is enabled, the default URL format for an application is http://host:port/context-root. For example:
http://localhost:80/myapp |
The default URL format for a standalone application client module is http://host:port/module-id. For example:
http://localhost:80/myclient |
To set a different URL for an application client, set the context-root subelement of the java-web-start-access element in the sun-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.
This task applies if you want 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, in UNIX: 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.
Copy the client JAR file to the client machine.
You are now ready to run the client.
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.
A lifecycle module, also called a lifecycle listener module, provides a means of running long or short Java-based tasks within the GlassFish 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 Chapter 13, Developing Lifecycle Listeners, in Oracle GlassFish Server 3.0.1 Application Development Guide.
You can deploy a lifecycle module using the create-lifecycle-module subcommand. Do not use asadmin deploy or related commands.
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.
If you installed the Web Profile, web services are not supported unless the optional Metro Web Services Stack add-on component is downloaded from the Update Tool. Without the Metro add-on component, a servlet or EJB component cannot be a web service endpoint, and the sun-web.xml and sun-ejb-jar.xml elements related to web services are ignored.
For information about Update Tool, see Update Tool in Oracle GlassFish Server 3.0.1 Administration Guide.
The following guidelines apply when deploying a web service in GlassFish Server:
Web Service Endpoint. Deploy a web service endpoint to GlassFish Server as you would any servlet or stateless session bean. If the deployed module has a web service endpoint, the endpoint is detected automatically during deployment. The GlassFish Server -specific deployment descriptor files, sun-web.xml and sun-ejb-jar.xml, provide optional web service enhancements in their webservice-endpoint and webservice-description elements.
JSR 181 Annotated File. Use the autodeployment feature to deploy a JSR 181 annotated file. See To Deploy an Application or Module Automatically.
For more information about web services, see JSR 181 and Chapter 6, Developing Web Services, in Oracle GlassFish Server 3.0.1 Application Development Guide.