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

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.

To access an EJB component from an application client

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.

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.

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.

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.

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.

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

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.

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

To access a JMS resource from an application client

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.

Next, configure a JMS resource on the Application Server.

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

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.

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.

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

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

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

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.

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.