Lesson 3: Developing a Client Applet

This lesson introduces the basics of writing a CORBA client applet. Many of these programming tasks are identical to those required for the application; the major difference is that the applet code appears in the init() method rather than in main(). The steps in this lesson are:

1. Performing Basic Setup
2. Creating an ORB Object
3. Finding the Hello Server
4. Invoking the sayHello() Operation
5. Compiling and Running the Hello World Applet

To see a completed version of HelloApplet.java, follow the link.

Performing Basic Setup

Start your text editor and save a new file titled HelloApplet.java to your project directory.

Import the packages required for the client class:

// The package containing our stubs.
import HelloApp.*;

// HelloClient will use the naming service.
import org.omg.CosNaming.*;

// The package containing special exceptions thrown by the name service.
import org.omg.CosNaming.NamingContextPackage.*;

// All CORBA applications need these classes.
import org.omg.CORBA.*;

// Needed for the applet.
import java.awt.Graphics;

Declare the applet class:

public class HelloApplet extends java.applet.Applet
{
  // Put the init() method here in the next step.
}

Declare a standard init() method:

  public void init()
  {
    // Add the try-catch block here in the next step.
  }

Because all CORBA programs can throw CORBA system exceptions at runtime, you will place all of the init() functionality within a try-catch block. CORBA programs throw system exceptions whenever trouble occurs during any of the processes (marshaling, unmarshaling, upcall) involved in invocation.

The exception handler simply prints the name of the exception and its stack trace to standard output (the Java console) so you can see what kind of thing has gone wrong.

Inside init(), set up a try-catch block:

    try{
    
      // Add all further HelloApplet code here.
    
    } catch(Exception e) {
        System.out.println("HelloApplet exception: " + e);
        e.printStackTrace(System.out);
      }

Save your file.

Creating an ORB Object

A CORBA client needs a local ORB object to perform all of its marshaling and IIOP work. Every client instantiates an org.omg.CORBA.ORB object and initializes it by passing to the ORB certain information about itself.

If you closed HelloApplet.java, open it now.

Inside the try-catch block, declare and initialize an ORB variable:

      Properties props = new Properties();
      props.put("org.omg.CORBA.ORBInitialPort", "1050");
      ORB orb = ORB.init(this, props);

The call to the ORB's init() method passes in the applet, allowing you to set certain properties at runtime. Here we have set the ORBInitialPort property to 1050 so that it connects properly to the HelloServer.

Remember to save your file.

Finding the Hello Server

Now that the applet has an ORB, it can ask the ORB to locate the actual service it needs, in this case the Hello server. There are a number of ways for a CORBA client to get an initial object reference; your client applet will use the COS Naming Service specified by OMG and provided with Java IDL.

Obtaining the Initial Naming Context

The first step in using the naming service is to get the initial naming context. In the try-catch block, below your ORB initialization, call orb.resolve_initial_references() to get an object reference to the name service:

      org.omg.CORBA.Object objRef = 
            orb.resolve_initial_references("NameService");

The string "NameService" is defined for all CORBA ORBs. When you pass in that string, the ORB returns a naming context object that is an object reference to the name service.

Narrowing the Object Reference

As with all CORBA object references, objRef is a generic CORBA object. To use it as a NamingContext object, you must narrow it to its proper type. Add the call to narrow() just below the previous statement.

      NamingContext ncRef = NamingContextHelper.narrow(objRef);

Here you see the use of an idltojava-generated helper class, similar in function to HelloHelper. The ncRef object is now an org.omg.CosNaming.NamingContext, and you can use it to access the naming service and find other services. You will do that in the next step.

Finding a Service in Naming

Names can have different structures depending upon the implementation of the naming service. Consequently, CORBA name servers handle complex names by way of NameComponent objects. Each NameComponent holds a single part, or element, of the object's full name. An array of NameComponent objects can hold a fully-qualified path to an object on any computer file or disk system.

To find the Hello server, you first need a NameComponent to hold an identifying string for it. Add this code directly below the call to narrow().

      NameComponent nc = new NameComponent("Hello", "");

This statement sets the id field of nc to "Hello" and the kind field to the empty string.

Because the path to the Hello object has just one element, create a single-element array out of nc. The NamingContext.resolve() method requires this array for its work:

      NameComponent path[] = {nc};

Finally, pass the NameComponent array to the naming service's resolve() method to get an object reference to the Hello server and narrow it to a Hello object:

      Hello helloRef = HelloHelper.narrow(ncRef.resolve(path));

Here you see the HelloHelper class at work. The resolve() method returns a generic CORBA object as you saw above when locating the name service itself. Therefore, you immediately narrow it to a Hello object, which is the object reference you need to perform the rest of your work.

Save HelloApplet.java.

Invoking the sayHello() Operation

CORBA invocations look like a method call on a local object. The complications of marshaling parameters to the wire, routing them to the server-side ORB, unmarshaling, and placing the upcall to the server method are completely transparent to the client programmer. Because so much is done for you by the generated code, invocation is really the easiest part of CORBA programming.

1. Open HelloApplet.java if it isn't open.

2. Still in the try-catch block (below the last statement), enter the invocation:

         message = helloRef.sayHello();
   

3. Finally, print the results of the invocation. Place the following code completely outside your init() method (but still within the HelloApplet class):

   String message = "";
   
   public void paint(Graphics g)
   {
     g.drawString(message, 25, 50);
   }
   

4. Save and close HelloApplet.java.

To run HelloApplet, you will need some server files that you have not yet created. These files are provided for you in [Path_to_JDK]/docs/guide/idl/tutorial/applet. Copy them as needed to build your project directory.

Windows users note that you should substitute backslashes (\) for the slashes (/) in all paths in this document.

Applet Setup

1. Create a new project directory, called Applet.

2. Copy your HelloApplet.java file to the Applet directory

3. Copy HelloServer.class, HelloServant.class, and Tutorial.html from [Path_to_JDK]/docs/guide/idl/tutorial/applet to the Applet directory.

4. Copy [Path_to_JDK]/docs/guide/idl/tutorial/applet/HelloApp and its entire contents to the Applet directory.

Your project directory should look like this:

Applet
 |-HelloApplet.java
 |-HelloServant.class
 |-HelloServer.class
 |-Tutorial.html
 |-HelloApp
    |-_HelloImplBase.class
    |-_HelloStub.class
    |-Hello.class
    |-HelloHelper.class
    |-HelloHolder.class

Tutorial.html, stored in [Path_to_JDK]/docs/guide/idl/tutorial/applet is provided for displaying your finished applet, but you need to customize a few attributes and parameters.

1. Open Tutorial.html in your text editor.

2. Inside the APPLET tag, enter the path to your project Applet directory as the value for the CODEBASE attribute.

3. In the first PARAM tag, enter the name of the machine where the CORBA name server runs (most likely your local machine name) as the value for ORBInitialHost.

4. In the second PARAM tag, ensure that the value of ORBInitialPort is the one you are using to run the name server (1050 if you are following the examples in this tutorial).

Save and close Tutorial.html.

Compiling the Client Applet

1. Change directory to the Applet directory you created.

2. Run the Java compiler on HelloApplet.java:

   javac HelloApplet.java
   

3. Correct any errors in your file and recompile if necessary. (You can copy the file from the [Path_to_JDK]/docs/guide/idl/tutorial/app directory if you have trouble finding your typographical errors).

4. You should see HelloApplet.class in the Applet directory.

1. Start the Java IDL name server:

   tnameserv -ORBInitialPort 1050 &

2. Start the Hello server:

   java HelloServer -ORBInitialPort 1050 &

3. Start the appletviewer and browse Tutorial.html.

   appletviewer Tutorial.html

   The string prints to the appletviewer frame:

   Hello world!!

4. You can also use Netscape Communicator 4.0 or higher to browse Tutorial.html and the "Hello world!!" string will print in the browser frame.

Remember to stop both server processes before continuing to the next lesson.

For More Information

Developing Clients

Covers topics of interest to CORBA client programmers

Exceptions: System Exceptions

Explains how CORBA system exceptions work and provides details on the minor codes of Java IDL's system exceptions

Initialization:  System Properties

Explains what properties can be passed to the ORB at initialization

Naming Service

Covers the COS Naming Service in greater detail