Assembling and Deploying an Application Client Module

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

1. Assemble the necessary client components.

   The client JAR file is created.

2. Assemble the EJB components that are to be accessed by the client.

   The EJB JAR file is created.

3. Assemble the client and EJB JAR files together in an EAR.

   An EAR file contains all the components of the application.

4. Deploy the application.

   Instructions are contained in To Deploy an Application or Module.

5. 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. In this release of GlassFish Server, the 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(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.
6. (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.

See Also

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

For more detailed information about creating application clients, see Chapter 10, Developing Java Clients, in Oracle GlassFish Server 3.1 Application Development Guide. 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 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 glassfish-application-client.xml file.

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

Before You Begin

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

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

2. Copy the application client package JAR file to the client machine.
3. Extract the contents of the JAR file.

   For example: jar xf filename.jar

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

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

6. Copy the client JAR file to the client machine.

   You are now ready to run the client.

See Also

For more detailed information about Java Web Start and 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. 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.