Not For Publication   
Glassfish Review Draft
Sun Java System Application Server Platform Edition 9.0 Developer's Guide 
Previous     Contents     Index     Next
Chapter 10

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.

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.

Programmatic Login can be used by both application clients and stand-alone clients.

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.

Annotation

Annotation is supported only for application clients. Stand-alone clients cannot use annotation. 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.0 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. Stand-alone clients cannot use Java Web Start. 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:

For information about Java-based clients that are not packaged using the ACC, see Developing Clients Without the ACC.

ProcedureTo access an EJB component from an application client

Steps
  1. In your client code, reference the home object by using an 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-ref elements in the application-client.xml file and the corresponding sun-application-client.xml file.

    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.0 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.0 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.0 2006Q1 Reference Manual.

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

    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:

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

Steps
  1. Create a JMS client.

    For detailed instructions on developing a JMS client, see the Java EE 5 Tutorial at http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JMS.html#wp84181.

  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-ref elements in the application-client.xml file and the corresponding sun-application-client.xml file.

    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.0 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:

    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:

  6. Run the application client.

    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.0 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 domain.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 domain.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 domain.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.0 2006Q1 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.0 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.0 Application Deployment Guide.

The following table lists supported ACC command-line arguments. All ACC arguments are optional except where noted.

Table 10-1 ACC Command-Line Arguments

Argument

Default

Description

-mainclass

Main-Class attribute in MAINFEST.MF

Specifies the class to instantiate and run. Required for an application with more than one application client module if name is not specified.

-name

display-name value in application-client.xml

Specifies the display name associated with the main class. Required for an application with more than one application client module if mainclass is not specified.

-xml

domain-dir/config

Specifies the location of the sun-acc.xml file to be used.

-textauth

not present

Specifies text authentication instead of dialog box authentication. If you use textauth, you must also supply user and password arguments.

If textauth is not specified and the application client doesn't request the user and password, Java Web Start prompts for them using a dialog box.

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 -xml and -color arguments for a stand-alone application client. The -xml argument is passed to the ACC. The -color argument is passed to the application client's main method.

http://localhost:8080/testClient?arg=-xml&arg=/home/joeuser/sun-acc.xml&arg=-color&arg=red

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.

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.0 2006Q1 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. Packaging an application client involves the following main steps:

Editing the Configuration File

Modify the environment variables in asenv.conf file located in the install-dir/config directory as shown below:

Editing the appclient Script

Modify the appclient script file as follows:

UNIX:

Change $CONFIG_HOME/asenv.conf to your-ACC-dir/config/asenv.conf.

Windows:

Change %CONFIG_HOME%\config\asenv.bat to your-ACC-dir\config\asenv.bat

Editing the sun-acc.xml File

Modify sun-acc.xml file to set the following attributes:

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

Setting Security Options

You can run the application client using SSL with certificate authentication. To set the security options, modify the sun-acc.xml file as shown in the code illustration below. For more information on the sun-acc.xml file, see "The sun-acc.xml File" in Sun Java System Application Server Platform Edition 9.0 Application Deployment Guide.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE client-container SYSTEM
"file:install-dir/lib/dtds/sun-application-client-container_1_2.dtd">
<client-container>
<target-server name="qasol-e1" address="qasol-e1" port="3700">
<security>
<ssl cert-nickname="cts"
ssl2-enabled="false"
ssl2-ciphers="-rc4,-rc4export,-rc2,-rc2export,-des,-desede3"
ssl3-enabled="true"
ssl3-tls-ciphers="+rsa_rc4_128_md5,-rsa_rc4_40_md5,+rsa3_des_sha,
+rsa_des_sha,-rsa_rc2_40_md5,-rsa_null_md5,-rsa_des_56_sha,
-rsa_rc4_56_sha"
tls-enabled="true"
tls-rollback-enabled="true"/>
<cert-db path="ignored" password="ignored"/> <!-- not used -->
</security>
</target-server>
<client-credential user-name="j2ee" password="j2ee"/>
<log-service level="WARNING"/>
</client-container>

ProcedureTo use the package-appclient script bundled with the Application Server

Steps
  1. Under install-dir /bin directory, run the package-appclient script.

    For details, see the Sun Java System Application Server Platform Edition 9.0 2006Q1 Reference Manual.

    This creates an appclient.jar file and stores it under install-dir/lib/appclient/ directory.


    Note - The appclient.jar file provides an application client container package targeted at remote hosts and does not contain a server installation. You can run this file from a remote machine with the same operating system as where it is created. That is, appclient.jar created on a Solaris platform does not function on Windows.


  2. Copy the install-dir /lib/appclient/appclient.jar file to the desired location.

    The appclient.jar file contains the following files:

client.policy

The client.policy file is the Java SE 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 Java SE standard policy tool or any text editor to edit this file.

For more information on using the Java SE 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.4/docs/guide/security/permissions.html.

Developing Clients Without the ACC

This section describes the procedure to create, assemble, and deploy a Java-based client that is not packaged using the Application Client Container (ACC). This section describes the following topics:

For information about using the ACC, see Developing Clients Using the ACC.

ProcedureTo access an EJB component from a stand-alone client

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

    For example:

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

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

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

  2. Deploy the EJB component to be accessed.

    For more information on deployment, see the Sun Java System Application Server Platform Edition 9.0 Application Deployment Guide.

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

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

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

    Here ORBhost is the Application Server hostname and ORBport is the ORB port number (default is 3700).

    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.0 Administration Reference.

  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.

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

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

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

    For example:

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

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

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

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

    Here ORBhost is the Application Server hostname and ORBport is the ORB port number (default is 3700).

    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.0 Administration Reference.

  5. Deploy the module.

    For more information on deployment, see the Sun Java System Application Server Platform Edition 9.0 Application Deployment Guide.

ProcedureTo access a JMS resource from a stand-alone client

Steps
  1. Create a JMS client.

    For detailed instructions on developing a JMS client, see the Java EE 5 Tutorial at http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JMS.html#wp84181.

  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. Copy the following JAR files to the client machine and include them in the classpath on the client side:

  4. Set the values for the Java Virtual Machine startup options:

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

    Here ORBhost is the Application Server hostname and ORBport is the ORB port number (default is 3700).

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

  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.


Previous     Contents     Index     Next