10 Developing Java Clients

ACC Security

The ACC determines when authentication is needed. This typically occurs when the client refers to an EJB component that requires authorization or when annotations in the client's main class trigger injection which, in turn, requires contact with the GlassFish Server's naming service. To authenticate the end user, the ACC prompts for any required information, such as a username and password. The ACC itself provides a very simple dialog box to prompt for and read these values.

The ACC integrates with the GlassFish Server's authentication system. It also supports SSL (Secure Socket Layer)/IIOP if configured and when necessary; see Using RMI/IIOP Over SSL.

You can provide an alternate implementation to gather authentication information, tailored to the needs of the application client. To do so, include the class to perform these duties in the application client and identify the fully-qualified name of this class in the callback-handler element of the application-client.xml descriptor for the client. The ACC uses this class instead of its default class for asking for and reading the authentication information. The class must implement the javax.security.auth.callback.CallbackHandler interface. See the Java EE specification, section 9.2, Application Clients: Security, for more details.

Application clients can use Programmatic Login.

ACC Naming

The client container enables the application clients to use the Java Naming and Directory Interface (JNDI) to look up Java EE services (such as JMS resources, EJB components, web services, security, and so on.) and to reference configurable parameters set at the time of deployment.

Application Client Annotation

Annotation is supported for the main class and the optional callback handler class in application clients. For more information, see "Deployment Descriptors and Annotations" in Oracle GlassFish Server Application Deployment Guide.

Java Web Start

Java Web Start allows your application client to be easily launched and automatically downloaded and updated. It is enabled for all application clients by default. For more information, see Using Java Web Start.

Application Client JAR File

In GlassFish Server 3.1.2, the downloaded appclient JAR file is smaller than in previous releases, with dependent classes in separate JAR files. When copying the downloaded appclient to another location, make sure to include the JAR files containing the dependent classes as well. You can also use the asadmin get-client-stubs command to retrieve the appclient and all associated application JAR files and place them in another location.

To Access an EJB Component From an Application Client

1. In your client code, reference the EJB component by using an @EJB annotation or by looking up the JNDI name as defined in the ejb-jar.xml file.

   For more information about naming and lookups, see Accessing the Naming Context.

   If load balancing is enabled as in Step 7 and the EJB components being accessed are in a different cluster, the endpoint list must be included in the lookup, as follows:

   corbaname:host1:port1,host2:port2,.../NameService#ejb/jndi-name
   

2. Define the @EJB annotations or the ejb-ref elements in the application-client.xml file. Define the corresponding ejb-ref elements in the glassfish-application-client.xml file.

   For more information on the glassfish-application-client.xml file, see "The glassfish-application-client.xml file" in Oracle GlassFish Server Application Deployment Guide. For a general explanation of how to map JNDI names using reference elements, see Mapping References.

3. Deploy the application client and EJB component together in an application.

   For more information on deployment, see the Oracle GlassFish Server Application Deployment Guide. To get the client JAR file, use the --retrieve option of the asadmin deploy command.

   To retrieve the stubs and ties generated during deployment, use the asadmin get-client-stubs command. For details, see the Oracle GlassFish Server Reference Manual.

4. Ensure that the client JAR file includes the following files:

   • A Java class to access the bean.

   • application-client.xml - (optional) Java EE application client deployment descriptor.

   • glassfish-application-client.xml - (optional) GlassFish Server specific client deployment descriptor. For information on the glassfish-application-client.xml file, see "The glassfish-application-client.xml file" in Oracle GlassFish Server Application Deployment Guide.

   • The MANIFEST.MF file. This file contains a reference to the main class, which states the complete package prefix and class name of the Java client.

5. Prepare the client machine.

   This step is not needed for Java Web Start. This step is not needed if the client and server machines are the same.

   If you are using the appclient script, package the GlassFish Server system files required to launch application clients on remote systems using the package-appclient script, then retrieve the application client itself using the asadmin get-client-stubs command.

   For more information, see Using the package-appclient Script and the Oracle GlassFish Server Reference Manual.

6. To access EJB components that are residing in a remote system, make the following changes to the sun-acc.xml file or the appclient script. This step is not needed for Java Web Start.

   • Define the target-server element's address and port attributes to reference the remote server machine and its ORB port. See "target-server" in Oracle GlassFish Server Application Deployment Guide.

   • Use the -targetserver option of the appclient script to reference the remote server machine and its ORB port. For more information, see Running an Application Client Using the appclient Script.

   To determine the ORB port on the remote server, use the asadmin get command. For example:

   asadmin --host rmtsrv get server-config.iiop-service.iiop-listener.iiop-listener1.port
   

   For more information about the asadmin get command, see the Oracle GlassFish Server Reference Manual.

7. To set up load balancing and failover of remote EJB references, define at least two target-server elements in the sun-acc.xml file or the appclient script. This step is not needed for Java Web Start.

   If the GlassFish Server instance on which the application client is deployed participates in a cluster, the ACC finds all currently active IIOP endpoints in the cluster automatically. However, a client should have at least two endpoints specified for bootstrapping purposes, in case one of the endpoints has failed.

   The target-server elements in the sun-acc.xml file specify one or more IIOP endpoints used for load balancing. The address attribute is an IPv4 address or host name, and the port attribute specifies the port number. See "client-container" in Oracle GlassFish Server Application Deployment Guide.

   The --targetserver option of the appclient script specifies one or more IIOP endpoints used for load balancing. For more information, see Running an Application Client Using the appclient Script.

Next Steps

• For instructions on running the application client, see Using Java Web Start or Running an Application Client Using the appclient Script.

• For more information about RMI-IIOP load balancing and failover, see "RMI-IIOP Load Balancing and Failover" in Oracle GlassFish Server High Availability Administration Guide.

To Access a JMS Resource From an Application Client

1. Create a JMS client.

   For detailed instructions on developing a JMS client, see "Java Message Service Examples" in The Java EE 6 Tutorial.

2. Next, configure a JMS resource on the GlassFish Server.

   For information on configuring JMS resources, see "Administering JMS Connection Factories and Destinations" in Oracle GlassFish Server Administration Guide.

3. Define the @Resource or @Resources annotations or the resource-ref elements in the application-client.xml file. Define the corresponding resource-ref elements in the glassfish-application-client.xml file.

   For more information on the glassfish-application-client.xml file, see "The glassfish-application-client.xml file" in Oracle GlassFish Server Application Deployment Guide. For a general explanation of how to map JNDI names using reference elements, see Mapping References.

4. Ensure that the client JAR file includes the following files:

   • A Java class to access the resource.

   • application-client.xml - (optional) Java EE application client deployment descriptor.

   • glassfish-application-client.xml - (optional) GlassFish Server specific client deployment descriptor. For information on the glassfish-application-client.xml file, see "The glassfish-application-client.xml file" in Oracle GlassFish Server Application Deployment Guide.

   • The MANIFEST.MF file. This file contains a reference to the main class, which states the complete package prefix and class name of the Java client.

5. Prepare the client machine.

   This step is not needed for Java Web Start. This step is not needed if the client and server machines are the same.

   If you are using the appclient script, package the GlassFish Server system files required to launch application clients on remote systems using the package-appclient script, then retrieve the application client itself using the asadmin get-client-stubs command.

   For more information, see Using the package-appclient Script and the Oracle GlassFish Server Reference Manual.

6. Run the application client.

   See Using Java Web Start or Running an Application Client Using the appclient Script.

Using Java Web Start

Java Web Start allows your application client to be easily launched and automatically downloaded and updated. General information about Java Web Start is available at http://www.oracle.com/technetwork/java/javase/tech/index-jsp-136112.html.

The following topics are addressed here:

• Enabling and Disabling Java Web Start

• Downloading and Launching an Application Client

• The Application Client URL

• Signing JAR Files Used in Java Web Start

• Error Handling

• Vendor Icon, Splash Screen, and Text

• Creating a Custom JNLP File

asadmin set applications.application.app-name.property.java-web-start-enabled="false"

asadmin set applications.application.module-name.property.java-web-start-enabled="false"

http://host:port/context-root

http://host:port/appclient-module-id

http://host:port/application-id/appclient-path

http://localhost:8080/testClient?arg=-color&arg=red

asadmin deploy --property jar-signing-alias=MyAlias MyApp.ear

<vendor>icon-image-URI::splash-screen-image-URI::vendor-text</vendor>

<vendor>images/icon.jpg::otherDir/splash.jpg::MyCorp, Inc.</vendor>

<vendor>images/icon.jpg::MyCorp, Inc.</vendor>

<vendor>::otherDir/splash.jpg::MyCorp, Inc.</vendor>

<vendor>MyCorp, Inc.</vendor>

[path-to-JAR-in-EAR!]path-to-JNLP-in-JAR

<java-web-start-access>
   <jnlp-doc>custom/myInfo.jnlp</jnlp-doc>
</java-web-start-access>

<java-web-start-access>
   <jnlp-doc>other/myLib.jar!custom/myInfo.jnlp</jnlp-doc>
</java-web-start-access>

[path-to-JAR-in-EAR!]path-to-JNLP-in-JAR

path-to-JNLP-in-EAR

<nativelib href="windows/myLib.jar"/>

<jnlp>
   <resources os="Windows">
      <nativelib href="windows/myLib.jar"/>
   </resources>
</jnlp>

<jnlp codebase="xxx" ...>

<jnlp href="xxx" ...>

<jnlp>
  <security>

<jnlp>
  <application-desc>
    <argument> ...

<jnlp spec="xxx" ...>

<jnlp>
  <information [no-attributes]>

<jnlp>
  <resources [no-attributes]>
    <java version="xxx" 
        java-vm-args="yyy" ...>

<jnlp>
  <information [attributes]>

<jnlp>
  <resources [attributes]>

<jnlp>
  <resources [no-attributes]>
    <jar ...>

<jnlp>
  <resources [no-attributes]>
    <nativelib ...>

<jnlp>
  <resources [no-attributes]>
    <property ...>

<jnlp>
  <resources [no-attributes]>
    <extension ...>

<jnlp>
  <component-desc ...>

<jnlp>
  <installer-desc ...>

Using the Embeddable ACC

You can embed the ACC into your application client. If you place the as-install/lib/gf-client.jar file in your runtime classpath, your application creates the ACC after your application code has started, then requests that the ACC start the application client portion. The basic model for coding is as follows:

1. Create a builder object.

2. Operate on the builder to configure the ACC.

3. Obtain a new ACC instance from the builder.

4. Present a client archive or class to the ACC instance.

5. Start the client running within the newly created ACC instance.

Your code should follow this general pattern:

// one TargetServer for each ORB endpoint for bootstrapping
TargetServer[] servers = ...;

// Get a builder to set up the ACC
AppClientContainer.Builder builder = AppClientContainer.newBuilder(servers);

// Fine-tune the ACC's configuration. Note ability to "chain" invocations.
builder.callbackHandler("com.acme.MyHandler").authRealm("myRealm"); // Modify config

// Get a container for a client.
URI clientURI = ...; // URI to the client JAR
AppClientContainer acc = builder.newContainer(clientURI);

or

Class mainClass = ...;
AppClientContainer acc = builder.newContainer(mainClass);

// In either case, start the client running.
String[] appArgs = ...;
acc.startClient(appArgs); // Start the client

...

acc.close(); // close the ACC(optional)

The ACC loads the application client's main class, performs any required injection, and transfers control to the static main method. The ACC's run method returns to the calling application as soon as the client's main method returns to the ACC.

If the application client's main method starts any asynchronous activity, that work continues after the ACC returns. The ACC has no knowledge of whether the client's main method triggers asynchronous work. Therefore, if the client causes work on threads other than the calling thread, and if the embedding application needs to know when the client's asynchronous work completes, the embedding application and the client must agree on how this happens.

The ACC's shutdown handling is invoked from the ACC's close method. The calling application can invoke acc.close() to close down any services started by the ACC. If the application client code started any asynchronous activity that might still depend on ACC services, invoking close before that asynchronous activity completes could cause unpredictable and undesirable results. The shutdown handling is also run automatically at VM shutdown if the code has not invoked close before then.

The ACC does not prevent the calling application from creating or running more than one ACC instance during a single execution of the application either serially or concurrently. However, other services used by the ACC (transaction manager, security, ORB, and so on) might or might not support such serial or concurrent reuse.

Running an Application Client Using the appclient Script

To run an application client, you can launch the ACC using the appclient script, whether or not Java Web Start is enabled. This is optional. This script is located in the as-install/bin directory. For details, see the Oracle GlassFish Server Reference Manual.

Using the package-appclient Script

You can package the GlassFish Server system files required to launch application clients on remote systems into a single JAR file using the package-appclient script. This is optional. This script is located in the as-install/bin directory. For details, see the Oracle GlassFish Server Reference Manual.

The client.policy File

The client.policy file is the J2SE policy file used by the application client. Each application client has a client.policy file. The default policy file limits the permissions of Java EE deployed application clients to the minimal set of permissions required for these applications to operate correctly. If an application client requires more than this default set of permissions, edit the client.policy file to add the custom permissions that your application client needs. Use the J2SE standard policy tool or any text editor to edit this file.

For more information on using the J2SE policy tool, see http://download.oracle.com/javase/tutorial/security/tour2/index.html.

For more information about the permissions you can set in the client.policy file, see http://download.oracle.com/javase/6/docs/technotes/guides/security/permissions.html.

Using RMI/IIOP Over SSL

You can configure RMI/IIOP over SSL in two ways: using a username and password, or using a client certificate.

To use a username and password, configure the ior-security-config element in the glassfish-ejb-jar.xml file. The following configuration establishes SSL between an application client and an EJB component using a username and password. The user has to login to the ACC using either the sun-acc.xml mechanism or the Programmatic Login mechanism.

<ior-security-config>
  <transport-config>
    <integrity>required</integrity>
    <confidentiality>required</confidentiality>
    <establish-trust-in-target>supported</establish-trust-in-target>
    <establish-trust-in-client>none</establish-trust-in-client>
  </transport-config>
  <as-context>
    <auth-method>username_password</auth-method>
    <realm>default</realm>
    <required>true</required>
  </as-context>
 <sas-context>
    <caller-propagation>none</caller-propagation>
 </sas-context>
</ior-security-config>

For more information about the glassfish-ejb-jar.xml and sun-acc.xml files, see the Oracle GlassFish Server Application Deployment Guide.

To use a client certificate, configure the ior-security-config element in the glassfish-ejb-jar.xml file. The following configuration establishes SSL between an application client and an EJB component using a client certificate.

<ior-security-config>
  <transport-config>
    <integrity>required</integrity>
    <confidentiality>required</confidentiality>
    <establish-trust-in-target>supported</establish-trust-in-target>
    <establish-trust-in-client>required</establish-trust-in-client>
  </transport-config>
  <as-context>
    <auth-method>none</auth-method>
    <realm>default</realm>
    <required>false</required>
  </as-context>
  <sas-context>
    <caller-propagation>none</caller-propagation>
  </sas-context>
</ior-security-config>

To use a client certificate, you must also specify the system properties for the keystore and truststore to be used in establishing SSL. To use SSL with the Application Client Container (ACC), you need to set these system properties in one of the following ways:

• Use the new syntax of the appclient script and specify the system properties as JVM options. See Running an Application Client Using the appclient Script.

• Set the environment variable VMARGS in the shell. For example, in the ksh or bash shell, the command to set this environment variable would be as follows:

  export VMARGS="-Djavax.net.ssl.keyStore=${keystore.db.file} 
  -Djavax.net.ssl.trustStore=${truststore.db.file} 
  -Djavax.net.ssl.keyStorePass word=${ssl.password} 
  -Djavax.net.ssl.trustStorePassword=${ssl.password}"
  

• Optionally, you can set the env element using Ant. For example:

  <target name="runclient">
    <exec executable="${S1AS_HOME}/bin/appclient">
      <env key="VMARGS" value=" -Djavax.net.ssl.keyStore=${keystore.db.file} 
        -Djavax.net.ssl.trustStore=${truststore.db.file} 
        -Djavax.net.ssl.keyStorePasword=${ssl.password} 
        -Djavax.net.ssl.trustStorePassword=${ssl.password}"/>
      <arg value="-client"/>
      <arg value="${appClient.jar}"/>
    </exec>
  </target>
  

Connecting to a Remote EJB Module Through a Firewall

To deploy and run an application client that connects to an EJB module on a GlassFish Server instance that is behind a firewall, you must set ORB Virtual Address Agent Implementation (ORBVAA) options. Use the asadmin create-jvm-options command as follows:

asadmin create-jvm-options -Dcom.sun.corba.ee.ORBVAAHost=public-IP-adress
asadmin create-jvm-options -Dcom.sun.corba.ee.ORBVAAPort=public-port
asadmin create-jvm-options 
-Dcom.sun.corba.ee.ORBUserConfigurators.com.sun.corba.ee.impl.plugin.hwlb.VirtualAddressAgentImpl=x

Set the ORBVAAHost and ORBVAAPort options to the host and port of the public address. The ORBUserConfigurators option tells the ORB to create an instance of the VirtualAddressAgentImpl class and invoke the configure method on the resulting object, which must implement the com.sun.corba.ee.spi.orb.ORBConfigurator interface. The ORBUserConfigurators value doesn't matter. Together, these options create an ORB that in turn creates Object references (the underlying implementation of remote EJB references) containing the public address, while the ORB listens on the private address specified for the IIOP port in the GlassFish Server configuration.

Specifying a Splash Screen

Java SE 6 offers splash screen support, either through a Java command-line option or a manifest entry in the application's JAR file. To take advantage of this Java SE feature in your application client, you can do one of the following:

• Create the appclient JAR file so that its manifest contains a SplashScreen-Image entry that specifies the path to the image in the client. The java command displays the splash screen before starting the ACC or your client, just as with any Java application.

• Use the new appclient ... -jar launch format, using the -splash command-line option at runtime or the SplashScreen-Image manifest entry at development time. See Running an Application Client Using the appclient Script.

• In the environment that runs the appclient script, set the VMOPTS environment variable to include the -splash option before invoking the appclient script to launch the client.

• Build an application client that uses the embeddable ACC feature and specify the splash screen image using one of the following:

  • The -splash option of the java command

  • SplashScreen-Image in the manifest for your program (not the manifest for the application client)

  See Using the Embeddable ACC.

During application (EAR file) deployment, the GlassFish Server generates façade JAR files, one for the application and one for each application client in the application. During application client module deployment, the GlassFish Server generates a single facade JAR for the application client. The appclient script supports splash screens inside the application client JAR only if you launch an application client facade or appclient client JAR. If you launch the facade for an application or the undeployed application itself, the appclient script cannot take advantage of the Java SE 6 splash screen feature.

Setting Login Retries

You can set a JVM option using the appclient script that determines the number of login retries allowed. This option is -Dorg.glassfish.appclient.acc.maxLoginRetries=n where n is a positive integer. The default number of retries is 3.

This retry loop happens when the ACC attempts to perform injection if you annotated the client's main class (for example, using @Resource). If instead of annotations your client uses the InitialContext explicitly to look up remote resources, the retry loop does not apply. In this case, you could write logic to catch an exception around the lookup and retry explicitly.

For details about the appclient script syntax, see the Oracle GlassFish Server Reference Manual.

Using Libraries with Application Clients

The Libraries field in the Administration Console's deployment page and the --libraries option of the asadmin deploy command do not apply to application clients. Neither do the as-install/lib, domain-dir/lib, and domain-dir/lib/classes directories comprising the Common Class Loader. These apply only to applications and modules deployed to the server. For more information, see Class Loaders.

To use libraries with an application client, package the application client in an application (EAR file). Then, either place the libraries in the /lib directory of the EAR file or specify their location in the application client JAR file's manifest Class-Path.

To access an EJB component from a stand-alone client

1. In your client code, instantiate the InitialContext:

   InitialContext ctx = new InitialContext();
   

   It is not necessary to explicitly instantiate a naming context that points to the CosNaming service.

2. In the client code, look up the home object by specifying the JNDI name of the home object.

   Here is an EJB 2.x example:

   Object ref = ctx.lookup("jndi-name");
   BeanAHome = (BeanAHome)PortableRemoteObject.narrow(ref,BeanAHome.class);
   

   Here is an EJB 3.x example:

   BeanRemoteBusiness bean =(BeanRemoteBusiness) ctx.lookup("com.acme.BeanRemoteBusiness");
   

   If load balancing is enabled as in Step 6 and the EJB components being accessed are in a different cluster, the endpoint list must be included in the lookup, as follows:

   corbaname:host1:port1,host2:port2,.../NameService#ejb/jndi-name
   

   For more information about naming and lookups, see Accessing the Naming Context.

3. Deploy the EJB component to be accessed.

   For more information on deployment, see "About Deployment Tools" in Oracle GlassFish Server Application Deployment Guide.

4. Copy the as-install/lib/gf-client.jar file to the client machine and include it in the classpath on the client side.

   The gf-client.jar file references GlassFish Server JAR files in its MANIFEST.MF file. If there is no GlassFish Server installation on the client machine, you must also copy the as-install/modules directory to the client machine and maintain its directory structure relative to the as-install/lib/gf-client.jar file. Or you can use the package-appclient script; see Using the package-appclient Script.

5. To access EJB components that are residing in a remote system, set the following system properties for the Java Virtual Machine startup options:

   -Dorg.omg.CORBA.ORBInitialHost=${ORBhost}
   -Dorg.omg.CORBA.ORBInitialPort=${ORBport}
   

   Here ORBhost is the GlassFish Server hostname and ORBport is the ORB port number (default is 3700 for the default server instance, named server).

   You can use the asadmin get command to get the IIOP port numbers. For example:

   asadmin get "configs.config.server-config.iiop-service.iiop-listener.orb-listener-1.*"
   

6. To set up load balancing and remote EJB reference failover, define the endpoints property as follows:

   -Dcom.sun.appserv.iiop.endpoints=host1:port1,host2:port2,...
   

   The endpoints property specifies a comma-separated list of one or more IIOP endpoints used for load balancing. An IIOP endpoint is in the form host:port, where the host is an IPv4 address or host name, and the port specifies the port number.

   If the endpoints list is changed dynamically in the code, the new list is used only if a new InitialContext is created.

7. Make sure the etc/hosts file on the client machine maps the GlassFish Server hostname and external IP address.

8. Run the stand-alone client.

   As long as the client environment is set appropriately and the JVM is compatible, you merely need to run the main class.

To access an EJB component from a server-side module

A server-side module can be a servlet, another EJB component, or another type of module.

1. In your module code, instantiate the InitialContext:

   InitialContext ctx = new InitialContext();
   

   It is not necessary to explicitly instantiate a naming context that points to the CosNaming service.

   To set up load balancing and remote EJB reference failover, define the endpoints property as follows:

   Hashtable env = new Hashtable();
   env.put("com.sun.appserv.iiop.endpoints","host1:port1,host2:port2,...");
   InitialContext ctx = new InitialConext(env);
   

   The endpoints property specifies a comma-separated list of one or more IIOP endpoints used for load balancing. An IIOP endpoint is in the form host:port, where the host is an IPv4 address or host name, and the port specifies the port number.

   You can use the asadmin get command to get the IIOP port numbers. For example:

   asadmin get "configs.config.server-config.iiop-service.iiop-listener.orb-listener-1.*"
   

   If the endpoints list is changed dynamically in the code, the new list is used only if a new InitialContext is created.

2. In the module code, look up the home object by specifying the JNDI name of the home object.

   Here is an EJB 2.x example:

   Object ref = ctx.lookup("jndi-name");
   BeanAHome = (BeanAHome)PortableRemoteObject.narrow(ref,BeanAHome.class);
   

   Here is an EJB 3.x example:

   BeanRemoteBusiness bean =(BeanRemoteBusiness) ctx.lookup("com.acme.BeanRemoteBusiness");
   

   If load balancing is enabled as in Step 1 and the EJB components being accessed are in a different cluster, the endpoint list must be included in the lookup, as follows:

   corbaname:host1:port1,host2:port2,.../NameService#ejb/jndi-name
   

   For more information about naming and lookups, see Accessing the Naming Context.

3. Deploy the EJB component to be accessed.

   For more information on deployment, see "About Deployment Tools" in Oracle GlassFish Server Application Deployment Guide.

4. To access EJB components that are residing in a remote system, set the following system properties for the Java Virtual Machine startup options:

   -Dorg.omg.CORBA.ORBInitialHost=${ORBhost}
   -Dorg.omg.CORBA.ORBInitialPort=${ORBport}
   

   Here ORBhost is the Application Server hostname and ORBport is the ORB port number (default is 3700 for the default server instance, named server).

5. Deploy the module.

   For more information on deployment, see "About Deployment Tools" in Oracle GlassFish Server Application Deployment Guide.

To access a JMS resource from a stand-alone client

1. Create a JMS client.

   For detailed instructions on developing a JMS client, see "Java Message Service Examples" in The Java EE 6 Tutorial.

2. Configure a JMS resource on GlassFish Server.

   For information on configuring JMS resources, see "Administering JMS Connection Factories and Destinations" in Oracle GlassFish Server Administration Guide.

3. Copy the following JAR files to the client machine and include them in the classpath on the client side:

   • gf-client.jar - available at as-install/lib

   • imqjmsra.jar - available at as-install/lib/install/aplications/jmsra

   The gf-client.jar file references GlassFish Server JAR files in its MANIFEST.MF file. If there is no GlassFish Server installation on the client machine, you must also copy the as-install/modules directory to the client machine and maintain its directory structure relative to the as-install/lib/gf-client.jar file. Or you can use the package-appclient script; see Using the package-appclient Script.

4. To access EJB components that are residing in a remote system, set the following system properties for the Java Virtual Machine startup options:

   -Dorg.omg.CORBA.ORBInitialHost=${ORBhost}
   -Dorg.omg.CORBA.ORBInitialPort=${ORBport}
   

   Here ORBhost is the Application Server hostname and ORBport is the ORB port number (default is 3700 for the default server instance, named server).

   You can use the asadmin get command to get the IIOP port numbers. For example:

   asadmin get "configs.config.server-config.iiop-service.iiop-listener.orb-listener-1.*"
   

5. Run the stand-alone client.

   As long as the client environment is set appropriately and the JVM is compatible, you merely need to run the main class.