Chapter 9 Developing Java Clients

This chapter describes how to develop, assemble, and deploy J2EE Application 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 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 server then processes the authentication data using the configured Java^TM Authentication and Authorization Service (JAAS) module. See Authenticating an Application Client.

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

Using an Application Client to Access an EJB Component

Using an Application Client to Access a JMS Resource

Authenticating an Application Client

Running an Application Client Using the ACC

Packaging an Application Client Using the ACC

Using an Application Client to Access an EJB Component

To access an EJB component from an application client, perform the following steps:

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("beanA_JNDI_name");
BeanAHome = (BeanAHome)PortableRemoteObject.narrow(ref,BeanAHome.class);

For more information about naming and lookups, see “Accessing the Naming Context” on page 387.

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” on page 237. For a general explanation of how to map JNDI names using reference elements, see “Mapping References” on page 395.

Deploy the application client and EJB component together in an application. For more information on deployment, see “Tools for Deployment” on page 106. You can use the --retrieve option to get the client JAR file.

You can also use the asadmin get-client-stubs command to retrieve the stubs and ties whether or not you requested their generation during deployment. The syntax is as follows:

asadmin get-client-stubs --user user --appname app_name local_dirpath

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 - Sun Java System Application Server specific client deployment descriptor. For information on the sun-application-client.xml file, see “The sun-application-client.xml file” on page 237.

The MANIFEST.MF file. This file contains the main class, which states the complete package prefix and classname 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

If you need to access EJB components that are residing in a remote system other than the system where the application client is being developed, make the following changes to the sun-acc.xml file:

Define the <target-server> address attribute to reference the remote server machine.

Define the <target-server> 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 Reference.

For more information about the sun-acc.xml file, see “The sun-acc.xml File” on page 241.

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

Using an Application Client to Access a JMS Resource

To access a JMS resource from an application client, perform the following steps:

Create a JMS client. For detailed instructions on developing a JMS client, see the J2EE tutorial:

http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JMS.html#wp84181

Next, configure a JMS resource on the Sun Java System Application Server. For information on configuring JMS resources, see “Creating JMS Resources: Destinations and Connection Factories” on page 403.

Set the environment variable LD_LIBRARY_PATH. This variable should point to the Application Server, the Sun Java System Message Queue JAR files, and shared libraries:

LD_LIBRARY_PATH=/usr/lib/mps:/opt/SUNWappserver/lib:/usr/lib

If the Application Server is on a different system, copy all the JAR files and shared libraries from the /opt/SUNWappserver/lib, /usr/share/lib/imq, and /usr/lib/mps directories to the target system.

Define the resource-ref elements in the application-client.xml file and the corresponding sun-application-client.xml file.

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

The MANIFEST.MF file. This file contains the main class, which states the complete package prefix and classname 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

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

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

Authenticating an Application Client

Running an Application Client Using the ACC

appclient -client client_application_jar [-mainclass client_application_main_class_name|-name display_name][-xml sun-acc.xml] [-textauth] [-user user_name] [-password password] [app_args]

-client: Specifies the name and location of the client JAR file. This is a required parameter.

-mainclass: Specifies the class name whose main() method is to be invoked. By default, the class specified in the client JAR’s Main-class attribute of the MANIFEST file is used. This is optional.



Note	The class name must be the full name, for example, com.sun.test.AppClient.

-name: Specifies the display name that is located in the client JAR file. By default, the display name is specified in the client JAR application-client.xml file and identified by the display-name attribute. This is optional.



Note	The -mainclass and -name parameters are optional for a single client application. For multiple client applications, you must use either the -classname option or the -name option.

-xml: Specifies the name and location of the ACC configuration XML file, which is required if you are not using the default domain. By default, the ACC uses domain_dir/config/sun-acc.xml for clients running on the application server, or install_dir/lib/appclient/sun-acc.xml for clients that are packaged using the package-applclient script.

-textauth: Specifies authentication using the text format. This is optional.

-user: Specifies the user.

-password: Specifies the user’s password.

app_args: Specifies the arguments passed to the client’s main() method. This is optional.

The following example shows how to run the sample application client, rmiConverter:

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

Using the package-appclient Script

Editing the Configuration File

Modify the environment variables in asenv.conf file located in the default-config_dir 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 libs.

$AS_JAVA to reference the location where you have installed the JDK.

$AS_ACC_CONFIG to reference the configuration xml (sun-acc.xml). The sun-acc.xml is located at install_dir/config.

$AS_IMQ_LIB to reference the imq home. It should be: domain_dir/imq/lib.

Editing the appclient Script

Editing the sun-acc.xml File

Ensure that the DOCTYPE references %%%SERVER_ROOT%%%/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.

If you want to log the messages in a file, specify a file name for the <log-service> file attribute. You can also set the log level. For example:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE client-container SYSTEM "file:{Your installed server root}/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>

Setting Security Options

You can run the application client using SSL with certificate authentication. In order 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” on page 241.

<!DOCTYPE client-container SYSTEM "file:////opt/SUNWappserver/lib/dtds/sun-application-client-container_1_0.dtd">

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"

Using the package-appclient Script

The following steps describe the procedure to use the package-appclient script that is bundled with Sun Java System Application Server:

Under install_dir/bin directory, run the package-appclient script. 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 will 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 which you use 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 - is 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

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 you develop an application client that requires more than this default set of permissions, you can edit the client.policy file to add the custom permissions that your applications need. You can use the J2SE standard policy tool or any text editor to edit this file.

For more information about the permissions you can set in the client.policy file, visit the following URL:

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:

Using a Stand-Alone Client to Access an EJB Component

Using a Stand-Alone Client to Access a JMS Resource

Authenticating a Stand-Alone Client

Using a Stand-Alone Client to Access an EJB Component

To access an EJB component from a stand-alone client, perform the following steps:

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 interoperable name of the home object. For example:

Object ref = ctx.lookup("beanA_interop_name");
BeanAHome = (BeanAHome)PortableRemoteObject.narrow(ref,BeanAHome.class);

For more information about naming and lookups, see “Accessing the Naming Context” on page 387.

Deploy the EJB component to be accessed. For more information on deployment, see “Tools for Deployment” on page 106. You can use the --retrieve option to get the client JAR file.

You can also use the asadmin get-client-stubs command to retrieve the stubs and ties whether or not you requested their generation during deployment. The syntax is as follows:

asadmin get-client-stubs --user user --appname app_name local_dirpath

Ensure that the client JAR file includes the following files:

a Java class to access the bean

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

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

If you need to access EJB components that are residing in a remote system other than the system where the application client is being developed, 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 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 Reference.

Run the stand-alone client. As long as the client environment is set appropriately and you are using a compatible JVM, you merely need to run the main class.

Using a Stand-Alone Client to Access a JMS Resource

To access a JMS resource from a stand-alone client, perform the following steps:

Create a JMS client. For detailed instructions on developing a JMS client, see the J2EE tutorial:

http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JMS.html#wp84181

Set the environment variable LD_LIBRARY_PATH. This variable should point to the Application Server, the Sun Java System Message Queue JAR files, and shared libraries:

LD_LIBRARY_PATH=/usr/lib/mps:/opt/SUNWappserver/lib:/usr/lib

If the Application Server is on a different system, copy all the JAR files and shared libraries from the /opt/SUNWappserver/lib, /usr/share/lib/imq, and /usr/lib/mps directories to the target system.

Ensure that the client JAR file includes the following files:

a Java class to access the resource

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

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

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

Run the stand-alone client. As long as the client environment is set appropriately and you are using a compatible JVM, you merely need to run the main class.

Authenticating a Stand-Alone Client

This section describes the necessary steps and procedure to create a client that accesses secure EJBs from outside the ACC.

First, you must setup your client development environment using the following steps:

Set org.omg.CORBA.ORBInitialHost to the host on which the IIOP listener is running.

env.setProperty("org.omg.CORBA.ORBInitialHost", "name service hostname");

Set org.omg.CORBA.ORBInitialPort to the port on which the IIOP listener is listening (usually 3700).

env.setProperty("org.omg.CORBA.ORBInitialPort", "3700");

Set the following property:

env.setProperty("com.sun.CORBA.connection.ORBSocketFactory", "com.sun.enterprise.iiop.IIOPSSLSocketFactory");

Set java.security.auth.login.config to install_dir/lib/appclient/appclientlogin.conf



Note	Do not set java.naming.factory.initial. The default JNDI provider is by default picked from the set classpath.

Obtain a username and a password. To obtain a username and a password, you can either write your own JAAS login callback handler or use the standard one provided with Sun Java System Application Server (com.sun.enterprise.security.auth.login.LoginCallbackHandler).

The following code line illustrates the use of standard handler using GUI-based authentication:

LoginCallbackHandler handler = new LoginCallbackHandler(true);

The following code line illustrates the use of standard handler using the text authentication:

LoginCallbackHandler handler = new LoginCallbackHandler(false);

The following code line is an example code for writing your own login callback handler:

import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.NameCallback;
import javax.security.auth.callback.PasswordCallback;

public class LoginCallbackHandler implements CallbackHandler {

private String username = "j2ee";
private String password = "j2ee";

public void handle(Callback[] callbacks) throws UnsupportedCallbackException {
try {
  for (int i = 0; i <callbacks.length; i++) {
  if (callbacks[i] instanceof NameCallback) {
    NameCallback nc = (NameCallback)callbacks[i];
    nc.setName(username);
    } else if(callbacks[i] instanceof PasswordCallback) {
      PasswordCallback pc = (PasswordCallback)callbacks[i];
      pc.setPassword(password.toCharArray());
    }
  }

  } catch (Exception ex) {
    ex.printStackTrace();
  }
  }
}

Pass an instance of your handler to the security infrastructure using the following call:

LoginContextDriver.doClientLogin(AppContainer.USERNAME_PASSWORD, handler);

The following two imports are required for the above call:

import com.sun.enterprise.appclient.AppContainer;
import com.sun.enterprise.security.auth.LoginContextDriver;

Configuring the ORB

This section describes how to configure the built-in ORB or a third party ORB in the following topics:

ORB Support Architecture

Configuring Load-Balancing for EJB Client Applications

Third Party ORB Support

ORB Support Architecture

CORBA client support in the Application Server involves communication between the ORB on the client and the ORB on the server, as shown in the following figure.

You can use the ORB that is bundled as part of the Application Server, or you can use a third-party ORB (ORBIX 2000 or ORBacus 4.1).

Configuring Load-Balancing for EJB Client Applications

If you are using built-in Sun Java System Application Server ORB, you can configure client-side load balancing using the Round Robin DNS approach.

To implement a simple load balancing scheme without making source code changes to your client, you can leverage the round robin feature of DNS. In this approach, you define a single virtual host name representing multiple physical IP addresses on which server instance ORBs are listening. Assuming that you configure all of the ORBs to listen on a common IIOP port number, the client applications can use a single host_name: IIOP port during the JNDI lookup. The DNS server resolves the host name to a different IP address each time the client is executed.

You can also implement client-side load balancing using the Sun Java System Application Server-specific naming factory class SIASCtxFactory. You can use this class both on the client-side and on the server-side which maintains a pool of ORB instances in order to limit the number of ORB instances that are created in a given process.

env.setProperty("java.naming.factory.initial","com.sun.appserv.naming.S1AS CtxFactory");

If you set a single URL property for the host and port above, your code would look like this:

env.setProperty("java.naming.factory.initial", "com.sun.appserv.naming.S1ASCtxFactory");

env.setProperty("java.naming.provider.url", "iiop://"name service hostname:name service port number");

If you prefer, you may set the host and port values and the URL value as Java System properties, instead of setting them in the environment as shown in the above code illustration. The values set in your code will, however, override any System property settings. Also, if you set both the URL and the host and port properties, the URL takes precedence.

Note that the [name service hostname] value mentioned above could be a name that maps to multiple IP addresses. The S1ASCtxFactory will appropriately round robin ORB instances across all the IP addresses everytime a user calls new InitialContext() method.

You can also use the following property of S1ASCtxFactory class to implement client-side load balancing:

com.sun.appserv.iiop.loadbalancingpolicy=roundrobin,host1:port1,host2:port2...

This property provides you with a list of host:port combinations to round robin the ORBs. These host names may also map to multiple IP addresses. If you use this property along with org.omg.CORBA.ORBInitialHost and org.omg.CORBA.ORBInitialPort as system properties, the round robin algorithm will round robin across all the values provided. If, however, you provide a host name and port number in your code, in the environment object, that value will override any such system property settings.

Third Party ORB Support

Sun Java System Application Server provides a built-in ORB to support IIOP access to the EJBs. For information on configuring the built-in ORB for supporting CORBA clients, see the Sun Java System Application Server Administration Guide.

You can also install and configure a third party ORB to use IIOP with Application Server. J2EE components (such as Servlet and EJBs) deployed to Sun Java System Application Server can access backend CORBA objects through third party Object Request Brokers (ORBs). This support enables J2EE applications to leverage investments in the existing CORBA-based business components. In addition to supporting server side access to backend CORBA objects, you can also use the built-in ORB for RMI/IIOP-based access to EJB components from Java or C++ application clients as explained in the RMI/IIOP samples.

Configuring the Orbix ORB with the Sun Java System Application Server involves the following steps:

Installing Orbix

Configuring Sun Java System Application Server to Use Orbix

Overriding the Built-in ORB

Installing Orbix

Ensure that you have the Orbix 2000 software available for installation.

Install the software. For instructions, read the Orbix Installation Guide.

Verify that the Orbix configuration is correct.

Configuring Sun Java System Application Server to Use Orbix

You must configure the runtime environment to enable the Sun Java System Application Server to load the Orbix ORB classes. Add the following to the classpath:

Orbix classes

OMG classes

Directory containing the Orbix license file

http://host:port/asadmin

For example:

http://localhost:4848/asadmin

Go to the Application Server page.

Click on the JVM Settings tab, then click on Path Settings.

Append the following to the Classpath Suffix text field, all on one line:

/etc/opt/iona/:/opt/iona/orbix_art/1.2/classes/orbix2000.jar:/opt/iona/ orbix_art/1.2/classes/omg.jar

Click Save.

Overriding the Built-in ORB

Sun Java System Application Server relies on a built-in ORB to support RMI/IIOP access to EJB components from Java application clients. When implementing servlets and EJB components that access backend CORBA-based applications residing outside of the application server, you may need to override the built-in ORB classes with the ORB classes from third party products such as Orbix 2000.

You can use any of the following approaches to override the built-in ORB classes with ORB classes from third party products:

ORB.init() Properties Approach

orb.properties Approach

Providing JVM Start-up Arguments

ORB.init() Properties Approach

The code illustration given below overrides the built-in ORB classes with ORB classes from IONA’s ORBIX 2000.

orbProperties.put("org.omg.CORBA.ORBClass","com.iona.corba.art.artimpl.ORBImpl");

orbProperties.put("org.omg.CORBA.ORBSingletonClass","com.iona.corba.art.artimpl.ORBSingleton");

The advantage of this approach is that RMI/IIOP access to EJB components housed in the application server will still be performed using the built-in ORB classes while only access from servlets and EJB components to backend CORBA-based applications will use the third party ORB classes. This is the efficient method of supporting simultaneous use of multiple ORBs in the application server environment.

orb.properties Approach

In Java 2 1.2.1 environment, the JVM’s orb.properties file contains property settings to identify the ORB implementation classes that are used by default throughout the JVM. To override the use of the built-in ORB classes, you can simply modify the orb.properties file to specify third party ORB classes and restart the application server.

For example, to set the implementation classes to specify the Orbix 2000 classes, make the following modification to the orb.properties file located at install_dir/jdk/jre/lib/.

The javax.rmi classes are used to support RMI/IIOP client access to EJB components housed in the application server. Since these classes are not used to access backend CORBA servers, you do not need to override these settings.

The main advantage of this approach is that it involves only one time setting for all applications deployed to the application server. There is no need for each servlet and/or EJB component that is acting as a client to a backend CORBA application to specify the ORB implementation classes.

Providing JVM Start-up Arguments

You can also specify the ORB implementation classes as server’s JVM_ARGS in the domain.xml file.

Go to domain_dir/config and edit the domain.xml file and add these JVM options as a subelement under <java-config> element.

<jvm-options>
-Dorg.omg.CORBA.ORBClass=com.iona.corba.art.artimpl.ORBImpl
</jvm-options>
<jvm-options>
-Dorg.omg.CORBA.ORBSingletonClass=com.iona.corba.art.artimpl.ORBSingleton
</jvm-options>

This approach gives the benefit of specifying the ORB implementation classes only once, but the main advantage when compared to changing the orb.properties file is that, the changes made to server’s configuration file are specific to server instance and are applicable to all the applications running on a particular instance only.

Previous Contents Index Next
Sun Java System Application Server Platform Edition 8 Developer's Guide