Deploying an Application Client (Sun GlassFish Enterprise Server 2.1 Application Deployment Guide)

Sun GlassFish Enterprise Server 2.1 Application Deployment Guide

Deploying an Application Client

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. It is enabled by default both in application clients and in the Enterprise Server.

This section contains the following topics:

To Deploy an Application Client

Assemble the necessary client files.

Assemble the EJB components to be accessed by the client.

Package the client and EJB components together in an application.

Deploy the application as described in Tools for Deployment.

If you are using the appclient script to run the application client, retrieve the client JAR file.

The client JAR file contains the ties and necessary classes for the application client.

You can use the --retrieve option to get the client JAR file.

You can also use the asadmin get-client-stubs command to retrieve the stubs and ties whether or not you requested their generation during deployment. For details, see the Sun GlassFish Enterprise Server 2.1 Reference Manual.

If you are using the appclient script to run the application client, copy the client JAR file to the client machine.

Next Steps

You can execute the client on the Enterprise Server machine to test it 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 page to launch the application client using Java Web Start.
You can also use the appclient script in the as-install/bin directory to run an application client. 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.

To Prepare Another Machine for Executing an Application Client

If Java Web Start is enabled, the default URL for an application is as follows:

http://host:port/context-root

The default URL for a stand-alone application client module is as follows:

http://host:port/module-id

If the context-root or module-id is not specified during deployment, the name of the EAR or JAR file without the 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.

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

If Java Web Start is not enabled for the application client, follow these steps.

You can use the package-appclient script in the as-install/bin directory to create the ACC package JAR file. This is optional.

This JAR file is created in the as-install/lib/appclient directory.

Copy the ACC package JAR file to the client machine and unjar it.

Configure the sun-acc.xml file.

This file is located in the appclient/appserv/lib/appclient directory by default if you used the package-appclient script.

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 execute the client.

Undeployment of Application Clients

Once application clients are downloaded, they remain on the client until removed manually. The Java Web Start control panel provides a simple interface you can use to discard downloaded application clients that used Java Web Start. When you undeploy an application client, you can no longer use Java Web Start, or any other mechanism, to download the application client. 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 depend on whether the application client has been written to tolerate such situations.

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