Sun Java System Application Server 

Samples Index

The RMI-Simple Sample Application


Overview

This sample is based on the Currency Converter EJB sample included in Sun's J2EE Developer's Guide. 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/JSPs clients. RMI/IIOP-based Java clients are executed inside Application Client Container (ACC) or outside ACC, while the web-based servlets/JSPs clients are executed in Web Container as shown in Figure 1. The section Running the Sample Application demonstrates how to run application client without ACC or with ACC.

Figure 1    Access to EJBs via Java and Web Clients


Compiling and Assembling the Sample Application

This procedure describes how to compile and assemble the sample using a Command Line Interface (CLI).

Deploying the Sample Application

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

Command Line Deployment

  1. Add <install_dir>/binto your path.
  2. In the application base directory, <install_dir>/samples/rmi-iiop/apps/simple/. Execute asant deploy

This deploys the application in a server instance:

<install_dir>/domains/domain1/applications/j2ee-apps/rmi-simple
An alternative way to deploy is to use Application Server Administration Tool.
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

Using 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 GUI 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. Here are the commands for each platform:
    1. Unix - Execute the <install_dir>/bin/asadmin start-domain domain1 command.
    2. Windows - Click "Start->Programs->Sun Microsystems->J2EE 1.4 SDK->Start Default Server"  command.
  2. Open the .ear file.
    1. Start Admin GUI, by entering URL  http://localhost:<admin.port>/asadmin   in browser. See replacing "localhost" and <admin.port> note here to determine correct values to use for your environment
    2. You are prompted to supply the user name and password of the application server. Enter correct values for your installed application server for "User Name:"  and "Password:" input fields, then click on the "Login" button.
    3. In the left-hand frame, click Applications-->Enterprise Applications  icon in the tree.
    4. In the right-hand frame, click on the "Deploy..."  button.
    5. Choose the file to be deployed by clicking on the "Browse..."  button, and navigate to select component to deploy (rmi-simple.ear).
    6. In the browse dialog, click on the "OK"  button.
    7. In the right-hand frame, click on the "Next"  button.
    8. In the right-hand frame, click on the "OK"  button. (Optionally fill in remaining values for application to be deployed)
    9. 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

1. Web-based client.

The Servlets/JSPs client will be run via a browser.
  • From a browser, go to the following URL:

      http://<hostname>:<port>/rmi-iiop-simple/index.jsp

  • Enter a numeric figure, e.g. 100, and press the Submit button.

  • It 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.

2. Local RMI/IIOP-based client with ACC.

The Java client will be run on the same machine where the Application Server is running.
  • Get client file, which was returned during deployment step.

      <install_dir>/samples/rmi-iiop/apps/simple/rmi-simpleClient.jar

  • Go to the directory,

      <install_dir>/bin

  • Run client application. For example:

      <install_dir>/bin/appclient -client <path>/rmi-simpleClient.jar

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

3. Remote RMI/IIOP-based client with ACC.

The Java client will be run on the different machine where the Application Server is running.
  • Package Application Client Container.
    Application Client Container (ACC) is a set of java classes, libraries and other files used to execute a first tier application client program in it own JVM. It communicates with the Application Server using RMI-IIOP.

    On the first machine where application server is running, package ACC. Go to the directory of


      <install_dir>/bin

    execute the script as following,

      package-appclient

    It creates the package as

      <install_dir>/bin/appclient.jar

  • Transfer the container and client files.
    Copy appclient.jar and rmi-simpleClient.jar from the first machine to the second machine.

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

  • Install the container.
    On the second machine, unpack ACC, i.e. applicient.jar, under a directory of your choice, e.g.

      <acc_install_dir>

    This installs ACC in

      <acc_install_dir>/appclient

  • Configure the container.
    On the second machine:
    • Modify environment in the file of
      <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=<Location of JDK Installed>          
      
    • Modify client script in the file of
      <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
    • Modify XML configuration file of
      <acc_install_dir>/appclient/config/sun-acc.xml

      for ORB host and port. 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.
  • Run client application:
    • On the second machine, e.g. (acchost),
    • Go to the directory <acc_install_dir>/appclient/bin
    • Run the client application:
       <install_dir>/bin/appclient -client <path>/rmi-simpleClient.jar
    • You will see the host and port of the first machine from screen:
       ......
       INFO: ACC014: ORB host name: [ashost]
       ......
       INFO: ACC013: ORB port number: [3700]
       ......          
      
    • After that, 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.

4. Local or remote RMI/IIOP-based client without ACC.

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 <CP> <ClientApp> <JNDIName>

where <CP> 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

Ifyou intend to run the client application on a remote machine, you need to 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 absolutely 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:

  • samples/rmi/simple/ejb/Converter.class- Remote Interface
  • samples/rmi/simple/ejb/ConverterHome.class - Home Interface
  • samples/rmi/simple/ejb/_Converter_Stub.class - Remote Stub
  • samples/rmi/simple/ejb/_ConverterHome_Stub.class - Home Stub
  • samples/rmi/simple/client/ConverterClient.class - Client Application Main Class

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.

<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 <install_dir>/samples/rmi-iiop/apps/simple/simple-ejb/src/conf/sun-ejb-jar.xml.

As a complete example for the command, it looks like the following for this sample,

On Solaris:

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

On Windows:

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 machine hostname> and org.omg.CORBA.ORBInitialPort=<ORB port of the remote machine> 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

Please 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_dirdomain_name/logs/server.log


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