Sun Java System Application Server 

Samples Index

The RMI-Simple Sample Application

Overview

This sample is based on the Currency Converter EJB sample. It demonstrates RMI/IIOP-based access to a simple stateless session bean. This sample will help you to understand how to enable concurrent access to the EJBs via both RMI/IIOP-based Java clients and web-based servlets/JSP clients. RMI/IIOP-based Java clients are executed within the Application Client Container (ACC) or as a standalone client, while the web-based servlet/JSP client is executed in Web container as shown in the figure below. The section Running the Sample Application demonstrates how to run application client without ACC or with ACC.


Access to EJBs via Java and Web Clients

The general instructions for building, deploying, and running sample applications are provided in Building, Deploying, and Running Sample Applications. In reading this document, use the following application-specific variables for this application:

Compiling and Assembling the Sample Application

This section describes how to compile and assemble the sample using a asant.

Deploying the Sample Application

Use Admin Console or asadmin to deploy the EAR file assembled in the previous section.

Deploying with asant

  1. Change your working directory to be the application base directory, install_dir/samples/rmi-iiop/apps/simple/.
  2. Execute asant deploy

This deploys the application in a server instance: 

domain_root_dir/domain_name/applications/j2ee-apps/rmi-simple

Deploying with asadmin

Alternativly, deploy the application using the Application Server command-line administration tool, asadmin. Use this command: 
asadmin deploy --user
username --password password --host host
--port admin-port rmi-simple.ear
You can also use this to verify the registration: 
asadmin list-components --user
username --password password

Deploying with Admin Console

Since a pre-built enterprise archive (.ear) file for the sample application is included with the application server, you can use the Admin Console to quickly read in the .ear file and deploy it to the application server.

  1. Start the admin server if it is not already started:
  2. Start Admin console. See Using Admin Console for instructions.
  3. When prompted, enter the administrator user name and password, then click Login.
  4. In the left frame, click Applications > Enterprise Applications in the tree.
  5. In the right frame, click on the "Deploy..."  button.
  6. Choose the file to be deployed by clicking on the Browse, and navigate to select component to deploy.
  7. In the browse dialog, click OK.
  8. In the right frame, click Next.
  9. In the right frame, optionally fill in remaining values for application to be deployed, then click OK.
  10. In the left hand pane, you will see the newly deployed module's icon in the tree. In the right hand pane you will also see the component listed as deployed.

Running the Sample Application

You can run this sample application:

The Application Client Container (ACC) is a set of Java classes, libraries and other files used to execute a first-tier application client program in its own Java VM. It communicates with the Application Server using RMI-IIOP.

Using a Web Client

To run the application using a Web browser client, follow these steps:

  1. Enter the following URL in the browser: 
    http://hostname:port;/rmi-iiop-simple/index.jsp
    The default web page will be displayed.
  2. In the text field, enter a numeric figure, for example 100, and press the Submit button.
  3. This invokes the ConverterBean with a request to convert 100 units of USD to Yen and 100 Yen to Euro. The stateless session bean returns the results to the caller and the JSP displays the result in the same page.

Using a Local RMI/IIOP Client in ACC

In this case, the Java client runs on the same machine that the Application Server is running.

Follow these steps:

  1. In a command shell, change your working directory to the application base directory: 
    cd app_dir
  2. If you are using the predeployed samples domain (Platform Edition only), enter this command to retrieve client stubs: 
    asadmin get-client-stubs --port 4858 --appname rmi-simple
    This step is not required if you deployed the application yourself.
  3. Then run the client application: 
    install_dir/bin/appclient -client app_dir/rmi-simpleClient.jar
  4. You will see the last two lines from screen as the result of converting 100 units of USD to Yen, and 100 Yen to Euro.

Remote RMI/IIOP-based Client in ACC

In this case, the Java client runs on a different machine than the one on which the Application Server is running.

  1. On the machine where application server is running, package the ACC: 
    cd install_dir/bin
package-appclient

    This creates appclient.jar

  2. Copy appclient.jar and rmi-simpleClient.jar files from the Application Server machine to the remote machine.

    The appclient.jar is intended to be used on a remote machine with same type of operating system. For example, if created on a Solaris system, it will not function on a Windows system.

  3. Install the container. On the remote machine, unpack applicient.jar under a directory of your choice, acc_install_dir. This installs ACC in acc_install_dir/appclient
  4. Configure the container on the remote machine:

    1. Modify environment in the file acc_install_dir/appclient/config/asenv.conf
      For example, 
       AS_INSTALL=acc_install_dir/appclient
 AS_WEBSERVICES_LIB=acc_install_dir/appclient/lib
 AS_IMQ_LIB=acc_install_dir/appclient/imq/lib
 AS_ACC_CONFIG=acc_install_dir/appclient/config/sun-acc.xml
 AS_JAVA=JDK-location
    2. Modify client script in the file 
      acc_install_dir/appclient/bin/appclient

      Ensure the path to the environment file, asenv.conf is set to: acc_install_dir/appclient/config/asenv.conf

    3. Modify XML configuration file for ORB host and port. The file is acc_install_dir/appclient/config/sun-acc.xml
      For example, 
       <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE client-container SYSTEM
    "file:acc_install_dir/appclient/lib/dtds/sun-application-client-container_1_0.dtd ">
 <client-container>
   <target-server name="acchost"  address="ashost" port="3700"/>
   <client-credential user-name="j2ee" password="j2ee"/>
   <log-service file="" level="WARNING"/>
 </client-container>
      In this example, Application Server is running on the machine with hostname ashost and with default ORB-port 3700, and Application Client Container is on the machine with hostname acchost.
  5. Run the client application:

    1. On the remote machine, (acchost), go to the directory acc_install_dir/appclient/bin
    2. Run the client application: 
      install_dir/bin/appclient -client app_dir/rmi-simpleClient.jar
-xml install_dir/domain_root_dir/domain_name/config/sun-acc.xml
    3. The application will displaye the host name and port number of the Application Server machine: 
       ......
 INFO: ACC014: ORB host name: [ashost]
 ......
 INFO: ACC013: ORB port number: [3700]
 ......
    4. Then the last two lines displayed will show the result of converting 100 units of USD to Yen, and 100 Yen to Euro.

Using a Standalone RMI/IIOP Client

The Java client is executed without using the interface of Application Client Container. By default it executes on the local machine. The client application runs from the command line: 

java -classpath classpath ClientApp JNDIName

where classpath includes three JAR files for CLASSPATH which are rmi-simpleClient.jar, j2ee.jar and appserv-rt.jar. The file of rmi-simpleClient.jar is copied to the current directory from the deployment directory, install_dir/domains/domain_name/applications/j2ee-apps/rmi-simple. The files j2ee.jar and appserv-rt.jar are copied to the current directory from AS installation, install_dir/lib.

ClientApp refers to the client program. In this example, it is samples.rmi.simple.client.ConverterClient. JNDIName matches in the deployment file. In the example, it is rmiconverter which can be found as <jndi-name>rmiconverter</jndi-name> in the file app_dir/simple/simple-ejb/src/conf/sun-ejb-jar.xml.

To run the client application on a remote machine, transfer the rmi-simpleClient.jar, j2ee.jar and appserv-rt.jar files to the client machine. Although the rmi-simpleClient.jar file is used in this example to run application client with or without an ACC, it contains more files than necessary for the situation in which an ACC is not used. The minimal files required to run the example on a remote machine without an ACC are the j2ee.jar and appserv-rt.jar file and the following files as extracted from the rmi-simpleClient.jar file:

The j2ee.jar file is required on the client machine because it contains the javax.ejb package that the client needs, and also contains the implementation and interface for J2EE APIs that the client may need.

For example, on Solaris or Linux: 

java -classpath rmi-simpleClient.jar:j2ee.jar:appserv-rt.jar
samples.rmi.simple.client.ConverterClient rmiconverter

On Windows, the colons (:) are replaced by semicolons (;).

java -classpath rmi-simpleClient.jar;j2ee.jar;appserv-rt.jar
samples.rmi.simple.client.ConverterClient rmiconverter

After that, you should see the last two lines from screen as the result of converting 100 units of USD to Yen, and 100 Yen to Euro.

NOTE: To run the client from a remote machine you will need to pass org.omg.CORBA.ORBInitialHost=remote-host-name and org.omg.CORBA.ORBInitialPort=remote-ORB-port. For example: 

java
-Dorg.omg.CORBA.ORBInitialHost=hostname
-Dorg.omg.CORBA.ORBInitialPort=port
-classpath ./rmi-simpleClient.jar:/tmp/SUNWappserver/lib/appserv-rt.jar:/tmp/SUNWappserver/lib/j2ee.jar
samples.rmi.simple.client.ConverterClient rmiconverter

Replace hostname and port with actual remote machine name and ORB port (usually 3700).

Troubleshooting

If you encounter problems when running the application, review the server log file at domain_root_dir/domain_name/logs/server.log

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.