Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Developer's Guide

- Previous: Chapter 7 Using Container-Managed Persistence for Entity Beans
- Next: Chapter 9 Developing Connectors

# Chapter 8 Developing Java Clients

This chapter describes how to develop, assemble, and deploy J2EE Application Clients in the following sections:

- Introducing the Application Client Container

- Developing Clients Using the ACC

- Developing Clients Without the ACC

# 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 J2EE application client components, which are used to access a variety of J2EE 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 J2EE 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 using the configured JavaTM Authentication and Authorization Service (JAAS) module.

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.

## Naming

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

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

- To access an EJB component from an application client

- To access a JMS resource from an application client

- Running an Application Client Using the ACC

- Packaging an Application Client Using the ACC

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

## To access an EJB component from an application client

1. In your client code, instantiate the `InitialContext` using the default (no argument) constructor:

       InitialContext ctx = new InitialContext();

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

2. In your client code, look up the home object by specifying the JNDI name of the home object as specified in the `ejb-jar.xml` file.

   For example:

       Object ref = ctx.lookup("java:comp/env/ejb-ref-name");
       BeanAHome = (BeanAHome)PortableRemoteObject.narrow(ref,BeanAHome.class);

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

3. 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. For a general explanation of how to map JNDI names using reference elements, see Mapping References.

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

   For more information on deployment, see Tools for Deployment. To get the client JAR file, use the `--retrieve` option.

   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 8.1 2005Q2 Update 2 Reference Manual.

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

   - a Java class to access the bean

   - `application-client.xml` - J2EE 1.4 application client deployment descriptor.

   - `sun-application-client.xml` - Application Server specific client deployment descriptor. For information on the `sun-application-client.xml` file, see The sun-application-client.xml file.

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

   You can package the application client using the `package-appclient` script. This is optional. See Packaging an Application Client Using the ACC.

6. 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`

   - `j2ee.jar` - available at install-dir`/lib`

   - The client JAR file

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

   - Define the target-server element’s `address` attribute to reference the remote server machine.

   - Define the target-server element’s `port` attribute to reference the ORB port on the remote server.

   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 8.1 2005Q2 Update 2 Administration Reference.

   For more information about the `sun-acc.xml` file, see The sun-acc.xml File.

8. Run the application client. See Running an Application Client Using the ACC.

## To access a JMS resource from an application client

1. Create a JMS client.

   For detailed instructions on developing a JMS client, see the J2EE 1.4 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. 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` - J2EE 1.4 application client deployment descriptor.

   - `sun-application-client.xml` - Application Server specific client deployment descriptor. For information on the `sun-application-client.xml` file, see The sun-application-client.xml file.

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

   You can package the application client using the `package-appclient` script. This is optional. See Packaging an Application Client Using the ACC.

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

   - `j2ee.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 Running an Application Client Using the ACC.

## Running an Application Client Using the ACC

To run an application client, launch the ACC using the `appclient` script. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Reference Manual.

## Packaging an Application Client Using the ACC

The `package-appclient` script, located in the install-dir`/bin` directory, is used to package a client application into a single `appclient.jar` file. Packaging an application client involves the following main steps:

- Editing the Configuration File

- Editing the appclient Script

- Editing the sun-acc.xml File

- Setting Security Options

- To use the `package-appclient` script bundled with the Application Server

### Editing the Configuration File

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

- `$AS_INSTALL` to reference the location where the package was un-jared plus `/appclient`. For example: `$AS_INSTALL=``/`install-dir`/appclient`.

- `$AS_NSS` to reference the location of the NSS libraries. For example:

  UNIX:

  `$AS_NSS=/`install-dir`/appclient/lib`

  WINDOWS:

  `%AS_NSS%=\`install-dir`\appclient\bin`

- `$AS_JAVA` to reference the location where the JDK is installed.

- `$AS_ACC_CONFIG` to reference the configuration XML file (`sun-acc.xml`). The `sun-acc.xml` is located at install-dir`/config`.

- `$AS_IMQ_LIB` to reference the imq home. Use domain-dir`/imq/lib`.

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

- Ensure that the `DOCTYPE` references install-dir`/lib/dtds` to your-ACC-dir`/lib/dtds`.

- Ensure that the `<target-server> address` attribute references the remote server machine.

- Ensure that the `<target-server> port` attribute references the ORB port on the remote server.

- To log the messages in a file, specify a file name for the `log-service` element’s `file` attribute. You can also set the log level. For example:

      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE client-container SYSTEM
      "file:install-dir/lib/dtds/sun-application-client-container_1_0.dtd">
      <client-container>
          <target-server name="qasol-e1" address="qasol-e1" port="3700">
          <log-service level="WARNING"/>
      </client-container>

For more information on the `sun-acc.xml` file, see The sun-acc.xml File.

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

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE client-container SYSTEM
    "file:install-dir/lib/dtds/sun-application-client-container_1_0.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>

### To use the `package-appclient` script bundled with the Application Server

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

   For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 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:

   - `appclient/bin` - contains the `appclient` script used to launch the ACC.

   - `appclient/lib` - contains the JAR and runtime shared library files.

   - `appclient/lib/appclient` - contains the following files:

     - `sun-acc.xml` - the ACC configuration file.

     - client.policy file- the security manager policy file for the ACC.

     - `appclientlogin.conf` file - the login configuration file.

     - `client.jar` file - created during the deployment of the client application.

   - `appclient/lib/dtds` - contains `sun-application_client-container_1_0.dtd`, which is the DTD corresponding to `sun-acc.xml`.

## client.policy

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

- To access an EJB component from a stand-alone client

- To access an EJB component from a server-side module

- To access a JMS resource from a stand-alone client

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

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

   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 Tools for Deployment.

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

   - `j2ee.jar` - available at install-dir`/lib`

5. 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 8.1 2005Q2 Update 2 Administration Reference.

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

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 Tools for Deployment.

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 8.1 2005Q2 Update 2 Administration Reference.

5. Deploy the module.

   For more information on deployment, see Tools for Deployment.

## To access a JMS resource from a stand-alone client

1. Create a JMS client.

   For detailed instructions on developing a JMS client, see the J2EE 1.4 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:

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

   - `j2ee.jar` - available at install-dir`/lib`

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

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 8.1 2005Q2 Update 2 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: Chapter 7 Using Container-Managed Persistence for Entity Beans
- Next: Chapter 9 Developing Connectors

- © 2010, Oracle Corporation and/or its affiliates