test

Oracle GlassFish Server 3.0.1 Application Development Guide

Chapter 11 Developing Java Clients

This chapter describes how to develop, assemble, and deploy Java clients in the following sections:

Note –

The Web Profile of the OracleGlassFishTM Server supports the EJB 3.1 Lite specification, which allows enterprise beans within web applications, among other features. The full GlassFish Server supports the entire EJB 3.1 specification. For details, see JSR 318.

Accordingly, the Application Client Container is supported only in the full GlassFish Server, not in the Web Profile.

JMS resources are supported only in the full GlassFish Server, not in the Web Profile. See Chapter 17, Using the Java Message Service.

Introducing the Application Client Container

The Application Client Container (ACC) includes a set of Java classes, libraries, and other files that are required for and distributed with Java client programs that execute in their own Java Virtual Machine (JVM). The ACC manages the execution of Java EE application client components (application clients), which are used to access a variety of Java EE services (such as JMS resources, EJB components, web services, security, and so on.) from a JVM outside the Oracle GlassFish Server.

The ACC communicates with the GlassFish Server using RMI-IIOP protocol and manages the details of RMI-IIOP communication using the client ORB that is bundled with it. Compared to other Java EE containers, the ACC is lightweight.

For information about debugging application clients, see Application Client Debugging.

Note –

Interoperability between application clients and GlassFish Servers running under different major versions is not supported.

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.

ACC 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 3.0.1 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.0.1, the appclient JAR file is smaller than in previous releases, with dependent classes in separate JAR files. When copying the 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.

Developing Clients Using the ACC

This section describes the procedure to develop, assemble, and deploy client applications using the ACC. This section describes the following topics:

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

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

    For more information on the sun-application-client.xml file, see The sun-application-client.xml file in Oracle GlassFish Server 3.0.1 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 3.0.1 Application Deployment Guide. To get the client JAR file, use the ----retrieve option of the asadmin deploy command.

    To retrieve the stubs and ties whether or not you requested their generation during deployment, use the asadmin get-client-stubs command. For details, see the Oracle GlassFish Server 3.0.1 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.

    • sun-application-client.xml - (optional) GlassFish Server specific client deployment descriptor. For information on the sun-application-client.xml file, see The sun-application-client.xml file in Oracle GlassFish Server 3.0.1 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.

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

    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 3.0.1 Reference Manual.

  7. Run the application client.

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

ProcedureTo Access a JMS Resource From an Application Client

  1. Create a JMS client.

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

    For information on configuring JMS resources, see Creating JMS Resources: Destinations and Connection Factories.

  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 sun-application-client.xml file.

    For more information on the sun-application-client.xml file, see The sun-application-client.xml file in Oracle GlassFish Server 3.0.1 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.

    • sun-application-client.xml - (optional) GlassFish Server specific client deployment descriptor. For information on the sun-application-client.xml file, see The sun-application-client.xml file in Oracle GlassFish Server 3.0.1 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.

    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 3.0.1 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://java.sun.com/javase/technologies/desktop/javawebstart/index.jsp.

Java Web Start is discussed in the following topics:

Enabling and Disabling Java Web Start

Java Web Start is enabled for all application clients by default.

The application developer or deployer can specify that Java Web Start is always disabled for an application client by setting the value of the eligible element to false in the sun-application-client.xml file. See the Oracle GlassFish Server 3.0.1 Application Deployment Guide.

The GlassFish Server administrator can disable Java Web Start for a previously deployed eligible application client using the asadmin set command.

To disable Java Web Start for all eligible application clients in an application, use the following command:


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

To disable Java Web Start for a stand-alone eligible application client, use the following command:


asadmin set domain1.applications.appclient-module.module-name.java-web-start-enabled="false"

Setting java-web-start-enabled="true" re-enables Java Web Start for an eligible application client. For more information about the asadmin set command, see the Oracle GlassFish Server 3.0.1 Reference Manual.

Downloading and Launching an Application Client

If Java Web Start is enabled for your deployed application client, you can launch it for testing. Simply click on the Launch button next to the application client or application's listing on the App Client Modules page in the Administration Console.

On other machines, you can download and launch the application client using Java Web Start in the following ways:

When you launch an application client, Java Web Start contacts the server to see if a newer client version is available. This means you can redeploy an application client without having to worry about whether client machines have the latest version.

The Application Client URL

The default URL for an application or module generally is as follows:


http://host:port/context-root

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


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

The default URL for an application client module embedded within an application is as follows. Note that the relative path to the application client JAR file is included. 


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

If the context-root, appclient-module-id, or application-id is not specified during deployment, the name of the JAR or EAR file without the extension is used. If the application client module or application is not in JAR or EAR file format, an appclient-module-id or application-id is generated.

Regardless of how the context-root or id is determined, it is written to the server log. For details about naming, see Naming Standards in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

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. This overrides the appclient-module-id or application-id. See Oracle GlassFish Server 3.0.1 Application Deployment Guide.

You can also pass arguments to the ACC or to the application client's main method as query parameters in the URL. If multiple application client arguments are specified, they are passed in the order specified.

A question mark separates the context root from the arguments. Ampersands (&) separate the arguments and their values. Each argument and each value must begin with arg=. Here is an example URL with a -color argument for a stand-alone application client. The -color argument is passed to the application client's main method.


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

If you are using the javaws URL command to launch Java Web Start with a URL that contains arguments, enclose the URL in double quotes (") to avoid breaking the URL at the ampersand (&) symbol.

Ideally, you should build your production application clients with user-friendly interfaces that collect information which might otherwise be gathered as command-line arguments. This minimizes the degree to which users must customize the URLs that launch application clients using Java Web Start. Command-line argument support is useful in a development environment and for existing application clients that depend on it.

Signing JAR Files Used in Java Web Start

Java Web Start enforces a security sandbox. By default it grants any application, including application clients, only minimal privileges. Because Java Web Start applications can be so easily downloaded, Java Web Start provides protection from potentially harmful programs that might be accessible over the network. If an application requires a higher privilege level than the sandbox permits, the code that needs privileges must be in a JAR file that was signed. When Java Web Start downloads such a signed JAR file, it displays information about the certificate that was used to sign the JAR, and it asks you whether you want to trust that signed code. If you agree, the code receives elevated permissions and runs. If you reject the signed code, Java Web Start does not start the downloaded application.

The GlassFish Server serves two types of signed JAR files in response to Java Web Start requests. One type is a JAR file installed as part of the GlassFish Server, which starts an application client during a Java Web Start launch: as-install/modules/gf-client.jar.

The other type is a generated application client JAR file. As part of deployment, the GlassFish Server generates a new application client JAR file that contains classes, resources, and descriptors needed to run the application client on end-user systems. When you deploy an application with the asadmin deploy command's ----retrieve option, use the asadmin get-client-stubs command, or select the Generate RMIStubs option from the EJB Modules deployment page in the Administration Console, this is the JAR file retrieved to your system. Because application clients need access beyond the minimal sandbox permissions to work in the Java Web Start environment, the generated application client JAR file must be signed before it can be downloaded to and executed on an end-user system.

A JAR file can be signed automatically or manually. The following sections describe the ways of signing JAR files.

Automatically Signing JAR Files

The GlassFish Server automatically creates a signed version of the required JAR file if none exists. When a Java Web Start request for the gf-client.jar file arrives, the GlassFish Server looks for domain-dir/java-web-start/gf-client.jar. When a request for an application's generated application client JAR file arrives, the GlassFish Server looks in the directory domain-dir/java-web-start/app-name for a file with the same name as the generated JAR file created during deployment.

In either case, if the requested signed JAR file is absent or older than its unsigned counterpart, the GlassFish Server creates a signed version of the JAR file automatically and deposits it in the relevant directory. Whether the GlassFish Server just signed the JAR file or not, it serves the file from the domain-dir/java-web-start directory tree in response to the Java Web Start request.

To sign these JAR files, the GlassFish Server uses its self-signed certificate. When you create a new domain, either by installing the GlassFish Server or by using the asadmin create-domain command, the GlassFish Server creates a self-signed certificate and adds it to the domain's key store.

A self-signed certificate is generally untrustworthy because no certification authority vouches for its authenticity. The automatic signing feature uses the same certificate to create all required signed JAR files. To sign different JAR files with different certificates, do the signing manually.

Using the jar-signing-alias Deployment Property

The asadmin deploy command property jar-signing-alias specifies the alias for the security certificate with which the application client container JAR file is signed.

Java Web Start won't execute code requiring elevated permissions unless it resides in a JAR file signed with a certificate that the user's system trusts. For your convenience, GlassFish Server signs the JAR file automatically using the self-signed certificate from the domain, s1as. Java Web Start then asks the user whether to trust the code and displays the GlassFish Server certificate information.

To sign this JAR file with a different certificate, first add the certificate to the domain keystore. You can use a certificate from a trusted authority, which avoids the Java Web Start prompt, or from your own company, which users know they can trust. To add a certificate to the domain keystore, see Administering JSSE Certificates in Oracle GlassFish Server 3.0.1 Administration Guide.

Next, deploy your application using the jar-signing-alias property. For example:


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

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

Manually Signing the Generated Application Client JAR File

You can sign the generated application client JAR file for an application any time after you have deployed the application. As you deploy the application, you can specify the asadmin deploy command's ----retrieve option or select the Generate RMIStubs option on the EJB Modules deployment page in the Administration Console. Doing either of these tasks returns a copy of the generated application client JAR file to a directory you specify. Or, after you have deployed an application, you can download the generated application client JAR file using the asadmin get-client-stubs command.

Once you have a copy of the generated application client JAR file, you can sign it using the jarsigner tool and your certificate. Then place the signed JAR file in the domain-dir/java-web-start/app-name directory. You do not need to restart the server to start using the new signed JAR file.

Error Handling

When an application client is launched using Java Web Start, any error that the application client logic does not catch and handle is written to System.err and displayed in a dialog box. This display appears if an error occurs even before the application client logic receives control. It also appears if the application client code does not catch and handle errors itself.

Vendor Icon, Splash Screen, and Text

To specify a vendor-specific icon, splash screen, text string, or a combination of these for Java Web Start download and launch screens, use the vendor element in the sun-application-client.xml file. The complete format of this element's data is as follows:

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

The following example vendor element contains an icon, a splash screen, and a text string:

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

The following example vendor element contains an icon and a text string:

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

The following example vendor element contains a splash screen and a text string; note the initial double colon:

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

The following example vendor element contains only a text string:

<vendor>MyCorp, Inc.</vendor>

The default value is the text string Application Client.

For more information about the sun-application-client.xml file, see the Oracle GlassFish Server 3.0.1 Application Deployment Guide.

Using the Embeddable ACC

You can embed the ACC into your application client. If you place the as-install/modules/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. GlassFish Server 3.0.1 introduces new features and syntax for the appclient script, including the -targetserver option and the ability to specify JVM options more conveniently. For details, see the Oracle GlassFish Server 3.0.1 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 3.0.1 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://java.sun.com/docs/books/tutorial/security/tour2/index.html.

For more information about the permissions you can set in the client.policy file, see http://java.sun.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 sun-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 sun-ejb-jar.xml and sun-acc.xml files, see the Oracle GlassFish Server 3.0.1 Application Deployment Guide.

To use a client certificate, configure the ior-security-config element in the sun-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:

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.

Using JavaFX Code

To use JavaFXTM code in an application client, compile the JavaFX script into a Java class and place the Java class in the appclient JAR file. To access back-end resources such as EJB components from a JavaFX script, you can write static public methods in your application client main class that refer to injected resources. The JavaFX script code can then refer to those static methods.

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:

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 3.0.1 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 Chapter 2, 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.