test

Sun Java System Application Server Platform Edition 9 Developer's Guide

Chapter 11 Developing Java Clients

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

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 Sun Java System Application Server.

The ACC communicates with the Application 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.

ACC Security

The ACC is responsible for collecting authentication data such as the username and password and sending the collected data to the Application Server. The Application Server then processes the authentication data.

Authentication techniques are provided by the client container, and are not under the control of the application client component. The container integrates with the platform’s authentication system. When you execute a client application, it displays a login window and collects authentication data from the user. It also supports SSL (Secure Socket Layer)/IIOP if configured and when necessary; see Using RMI/IIOP Over SSL.

Application clients can use Programmatic Login.

For more information about security for application clients, see the Java EE 5 Specification, Section EE.9.7, “Java EE Application Client XML Schema.”

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 application clients. For more information, see section 9.4 of the Java EE 5 Specification and Java EE Standard Annotation in Sun Java System Application Server Platform Edition 9 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.

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 annotations in application clients, see section 9.4 of the Java EE 5 Specification.

    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 application-client.xml file, see the Java EE 5 Specification, Section EE.9.7, “Java EE Application Client XML Schema.”

    For more information on the sun-application-client.xml file, see The sun-application-client.xml file in Sun Java System Application Server Platform Edition 9 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 Sun Java System Application Server Platform Edition 9 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 Sun Java System Application Server Platform Edition 9 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. For information on the application-client.xml file, see the Java EE 5 Specification, Section EE.9.7, “Java EE Application Client XML Schema.”

    • sun-application-client.xml - (optional) Application Server specific client deployment descriptor. For information on the sun-application-client.xml file, see The sun-application-client.xml file in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.

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

    If you are not using Java Web Start, you can package the application client using the package-appclient script. This is optional. See Using the package-appclient Script.

  5. If you are not using Java Web Start, copy the following JAR files to the client machine and include them in the classpath on the client side:

    • appserv-rt.jar - available at install-dir/lib

    • javaee.jar - available at install-dir/lib

    • The client JAR file

  6. To access EJB components that are residing in a remote system, make the following changes to the sun-acc.xml file.

    This information can be obtained from the domain.xml file on the remote system. For more information on domain.xml file, see the Sun Java System Application Server Platform Edition 9 Administration Reference.

    For more information about the sun-acc.xml file, see The sun-acc.xml File in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.

  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.

    For detailed instructions on developing a JMS client, see “Chapter 33: The Java Message Service API” in the Java EE 5 Tutorial.

  2. Next, configure a JMS resource on the Application 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 application-client.xml file, see the Java EE 5 Specification, Section EE.9.7, “Java EE Application Client XML Schema.”

    For more information on the sun-application-client.xml file, see The sun-application-client.xml file in Sun Java System Application Server Platform Edition 9 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. For information on the application-client.xml file, see the Java EE 5 Specification, Section EE.9.7, “Java EE Application Client XML Schema.”

    • sun-application-client.xml - (optional) Application Server specific client deployment descriptor. For information on the sun-application-client.xml file, see The sun-application-client.xml file in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.

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

    If you are not using Java Web Start, you can package the application client using the package-appclient script. This is optional. See Using the package-appclient Script.

  5. If you are not using Java Web Start, copy the following JAR files to the client machine and include them in the classpath on the client side:

    • appserv-rt.jar - available at install-dir/lib

    • javaee.jar - available at install-dir/lib

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

    • The client JAR file

  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/products/javawebstart/reference/api/index.html.

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 Sun Java System Application Server Platform Edition 9 Application Deployment Guide.

The Application 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 --user adminuser 
domain1.applications.j2ee-application.app-name.java-web-start-enabled="false"

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


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

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


asadmin set --user adminuser 
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 Sun Java System Application Server Platform Edition 9 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 Admin 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 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 in Sun Java System Application Server Platform Edition 9 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. See Sun Java System Application Server Platform Edition 9 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. Each argument and each value must begin with arg= and end with an ampersand (&). 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 Application 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 Application Server, which starts an application client during a Java Web Start launch: install-dir/lib/appserv-jwsacc.jar.

The other type is a generated application client JAR file. As part of deployment, the Application 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 in the Admin 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 Application Server automatically creates a signed version of the required JAR file if none exists. When a Java Web Start request for the appserv-jwsacc.jar file arrives, the Application Server looks for domain-dir/java-web-start/appserv-jwsacc.jar. When a request for an application's generated application client JAR file arrives, the Application 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 Application Server creates a signed version of the JAR file automatically and deposits it in the relevant directory. Whether the Application 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 Application Server uses its self-signed certificate. When you create a new domain, either by installing the Application Server or by using the asadmin create-domain command, the Application 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.

Manually Signing appserv-jwsacc.jar

You can sign the appserv-jwsacc.jar file manually any time after you have installed the Application Server. Copy the unsigned file from install-dir/lib to a different working directory and use the jarsigner command provided with the JDK to create a signed version of exactly the same name using your certificate. Then manually copy the signed file into domain-dir/java-web-start. From then on, the Application Server serves the JAR file signed with your certificate whenever a Java Web Start request asks that domain for the appserv-jwsacc.jar file. Note that you can sign each domain's appserv-jwsacc.jar file differently.

Remember that if you create a new domain and do not sign appserv-jwsacc.jar manually for that domain, the Application Server creates an auto-signed version of it for use by the new domain. Also, if you create a domain-specific signed appserv-jwsacc.jar, delete the domain, and then create a new domain with the same name as the just-deleted domain, the Application Server does not remember the earlier signed appserv-jwsacc.jar. You must recreate the manually signed version.

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 in the Admin 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.

Running an Application Client Using the appclient Script

To run an application client that does not have Java Web Start enabled, you can launch the ACC using the appclient script. This is optional. This script is located in the install-dir/bin directory. For details, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

Using the package-appclient Script

You can package an application client that does not have Java Web Start enabled into a single appclient.jar file using the package-appclient script. This is optional. This script is located in the install-dir/bin directory. For details, see the Sun Java System Application Server Platform Edition 9 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/security1.2/tour2/index.html.

For more information about the permissions you can set in the client.policy file, see http://java.sun.com/j2se/1.5.0/docs/guide/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 Sun Java System Application Server Platform Edition 9 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 VMARGS environment variable in one of the following ways: