Getting Started with RMI - a Hello World Example

 

This example provides a distributed version of the classic Hello World program using remote method invocation (RMI) in a BEA WebLogic Enterprise environment.

This topic includes the following sections:

• Where Can I Find the RMI Hello World Example?

• What Is the RMI Hello World Example and What Do I Need to Run It?

• Building and Running the Hello World Example

• Cleaning Up the Directory

• Understanding the Hello World Example

 

---

Where Can I Find the RMI Hello World Example?

In addition to the fully supported examples supplied on the CD-ROM with this release of BEA WebLogic Enterprise, several unsupported code examples are provided on a password-protected Web site for BEA WebLogic Enterprise customers. You can get all the files for the BEA WebLogic Enterprise RMI Hello World example from this Web site. The URL for the unsupported samples BEA WebLogic Enterprise Web site is specified in the product Release Notes under "About This BEA WLE Release" in the subsection "Unsupported Samples and Tools Web Page." On the samples Web page, the RMI HelloWorld example is in a directory similar to the following:

/unsupported/samples/rmi/helloworld

 

---

What Is the RMI Hello World Example and What Do I Need to Run It?

The BEA WebLogic Enterprise RMI Hello World example is a simple application for demonstrating remote method invocations in a distributed BEA WebLogic Enterprise environment. The example shows a client making a remote method call to a server object running on the host. When you run the client at the command line, "Hello World!" is displayed in response.

Required Software and Environment

To run the BEA WebLogic Enterprise RMI Hello World example, you need BEA WebLogic Enterprise installed on your system and the appropriate environment variables set. The Hello World example does some automated environment setup for you, so for now the only variables you should need to check are these:

• Make sure TUXDIR is set to the full pathname of the directory where you installed the BEA WebLogic Enterprise software

• Make sure JAVAHOME is set to the full pathname of the directory where you installed the JDK software

For complete information on how to verify these settings, see the topic Setting Up Your BEA WebLogic Enterprise Development Environment.

Hello World Files

The files needed for this example are supplied on the BEA WebLogic Enterprise unsupported samples Web site. You can get the URL for this Web site, and other related information about it, from the product Release Notes.

The files included are shown in Table 2-1.

Table 2-1 Hello World Files

File	Description
examples/hello/Hello.java	A remote interface.
examples/hello/HelloImpl.java	A remote object implementation that implements examples.hello.Hello.
examples/hello/HelloClient.java	A client that invokes the remote method, sayHello.
ServerImpl.java	Registers the RMI implementation with the BEA WebLogic Enterprise server at startup.
server.xml	Server description file, which provides information about the BEA WebLogic Enterprise application required by the buildjavaserver command. When you run the runme script, one of the things it does is package the generated class files into a JAR file by running the BEA WebLogic Enterprise command buildjavaserver on the server.xml file.
runme.cmd runme.ksh	Windows (DOS) and UNIX scripts, respectively, that you can run to build and run the Hello World example. The runme script calls on all other files listed here, and generates new files.
clobber.cmd clobber.ksh	Windows (DOS) and UNIX scripts, respectively, that you can run to remove files generated by the Hello World example.

 

---

Building and Running the Hello World Example

We suggest that first you just find the Hello World RMI example (on the Web site indicated in the product Release Notes), build it, and run it. This is an easy way to get familiar with WebLogic RMI on IIOP.

To build and run the Hello World example do the following:

1. Make sure BEA WebLogic Enterprise is installed on your local system, and that the following environment variables are set to indicate the appropriate paths:

   • JAVA_HOME-set to the full pathname of your Java Development Kit (JDK)

   • TUXDIR-set to the full pathname of your WLE installation directory

     The Hello World example script automatically sets the TUXCONFIG environment variable for you, so you do not need to set this variable now. The TUXCONFIG variable indicates the location of the TUXCONFIG file for the WLE application you want to run, in this case our Hello World example application. The script also adds the HelloWorld application classes to your CLASSPATH, and the required paths for TUXDIR and the JDK bin to your PATH.

2. Copy the RMI helloworld directory and files from the WLE Unsupported Samples Web page onto your local system.

   The URL for the unsupported samples BEA WebLogic Enterprise Web site is specified in the product Release Notes under "About This BEA WLE Release" in the subsection "Unsupported BEA WebLogic Enterprise Samples and Tools on BEA Web Site." On the samples Web page, the RMI HelloWorld example is in a directory similar to the following:

   /unsupported/samples/rmi/helloworld

3. Change directories (cd) to your local BEA WebLogic Enterprise RMI Hello World example and type the following at the command-line prompt:

   runme

   Running this script compiles, builds, and runs the RMI Hello World example. You should see output similar to the following, as a result of running the runme script.

   C:\myWLEapps\rmi\helloworld>runme
   Setting up for RMI HelloWorld sample.
   --- Verifying some variables...
   --- Creating setenv.cmd...
   --- Creating ubbconfig...
   --- Creating run_client.cmd...
   --- Compiling Java sources...
   --- Generating Stub and Skeleton...
   --- Building the Jar...
   --- Creating tuxconfig...
   --- Booting WLE...
   Booting all admin and server processes in C:\myWLEapps\rmi\helloworld\tuxconfig
   INFO: BEA Engine, Version 2.4
   INFO: Serial #: 123456789, Expiration 2000-06-21, Maxusers 200
   INFO: Licensed to: Samantha Stevens

   Booting admin processes ...

   exec BBL -A :
           process id=271 ... Started.

   Booting server processes ...

   exec TMSYSEVT -A :
           process id=239 ... Started.
   exec TMFFNAME -A -- -N -M :
           process id=240 ... Started.
   exec TMFFNAME -A -- -N :

           process id=243 ... Started.
   exec TMFFNAME -A -- -F :
           process id=284 ... Started.
   exec JavaServer -A :
           process id=225 ... Started.
   exec ISL -A -- -n //SAMS:2468 :
           process id=274 ... Started.
   7 processes started.
   --- Running the RMI Client... (Should say "Hello World!")...
   Hello World!
   --- Shutting down WLE...
   Shutting down all admin and server processes in C:\myWLEapps\rmi\helloworld

   Shutting down server processes ...
   Server Id = 5 Group Id = GROUP1 Machine = simple: shutdown succeeded
   Server Id = 6 Group Id = GROUP2 Machine = simple: shutdown succeeded
   Server Id = 4 Group Id = GROUP1 Machine = simple: shutdown succeeded
   Server Id = 3 Group Id = GROUP1 Machine = simple: shutdown succeeded
   Server Id = 2 Group Id = GROUP1 Machine = simple: shutdown succeeded
   Server Id = 1 Group Id = GROUP1 Machine = simple: shutdown succeeded
   Shutting down admin processes ...

   Server Id = 0 Group Id = simple Machine = simple: shutdown succeeded
   7 processes stopped.
   --- Finished.
   C:\rmiHelloExample\helloworld>

   Some of the tasks performed by the script are:

   • Sets up your BEA WebLogic Enterprise environment. This includes setting WLE environment variables, and creating a UBBCONFIG file based on your system name. The UBBCONFIG file is used to generate a TUXCONFIG file.

   • Generates a directory called classes (if it does not already exist) and adds the classes directory in your local CLASSPATH (if it is not already included).

   • Runs the javac compiler on the examples/hello/*.java files to generate executable Java class files, and puts the generated class files under a directory called classes.

   • Runs the command java weblogic.rmic on the implementation class HelloImpl.class file to generate an RMI client stub and RMI server skeleton.

   • Packages the class files into a JAR file by running the buildjavaserver command on server.xml.

   • Boots the WLE server (tmboot -y).

   • Runs the RMI client.

   • Stops the WLE server (tmshutdown -y).

Notice also that as a result of running the runme script, you get several new files. Some of the more interesting ones are shown in Table 2-2.

Table 2-2 Files Produced by the Hello World Example Runme Script

Generated File(s)	Description
Java class files in classes/examples/helloworld/	The classes Hello.class, HelloClient.class, and HelloImpl.class were created by running the javac command on Hello.java, HelloClient.java, and HelloImpl.java, respectively.
RMI stub and skeleton classes in classes/examples/helloworld/	Hello_WLStub.class is a proxy for the client and Hello_WLSkel.class is a proxy class for the server. These class files were created by running the command java weblogic.rmic on the fully qualified package name of the implementation class, HelloImpl.class (Java weblogic.rmic examples.hello.HelloImpl).
classes/ServerImpl.class	Registers the application at startup. This was created by running the javac command on ServerImpl.java.
server.jar	The Hello World application packaged into a Java ARchive (JAR) file for deployment. This was created by running the buildjavaserver command on the file server.xml.
server.ser	Serialized version of the server-implementation as specified in the server-descriptor-name section of the server.xml file. running the buildjavaserver command on the file server.xml.
UBBCONFIG file	ASCII version of the BEA WebLogic Enterprise application configuration file containing parameters that the WLE software interprets to create an executable application.
TUXCONFIG file	Binary version of the BEA WebLogic Enterprise application configuration file. This was generated by running tmloadcf on the UBBCONFIG file.
setenv.cmd setenv.ksh	Windows (DOS) and UNIX commands to set the BEA WebLogic Enterprise specific environment variables APPDIR and TUXDIR based on your current environment.
run_client.cmd run_client.ksh	Windows (DOS) and UNIX commands to run the client with appropriate arguments.

For more information about these files, refer to Developing RMI Applications in BEA WebLogic Enterprise.

 

---

Cleaning Up the Directory

If you want to start over, you can quickly remove all generated files from the example directory by running the following command in the helloworld directory:

clobber

Running the clobber command removes all generated files for the Hello World example, leaving only the original example files: the Java source files, server.xml file, and the runme commands for Windows and UNIX.

 

---

Understanding the Hello World Example

After you successfully run the RMI Hello World example, you can walk through the process used to create it by referring to Developing RMI Applications in BEA WebLogic Enterprise. This topic steps through the entire development and run-time process using the Hello World files as an example.

Each of the key Java source code files is explained in detail in the following subtopics:

• Hello.java is explained in Step 2: Write the source code for a remote interface

• HelloImpl.java is explained in Step 3: Write the source code for a remote object that implements the remote interface

• HelloClient.java is explained in Step 4: Write the source code for a client that invokes methods on the remote object

This topic also explains how to compile the Java source files with the javac compiler, how to generate stubs and skeletons with the WebLogic RMI compiler, package the class files into a BEA WebLogic Enterprise application, and build and run the application in the BEA WebLogic Enterprise environment.