Previous | Next | Trail Map | Programming with Java IDL | The Hello Client Server Example

Developing a Client Application

This lesson introduces the basics of writing a CORBA client application. Included in this lesson are:

Here's a completed version of HelloClient.java.

Applet Note: While this lesson focuses on writing a CORBA client application, many of the steps are identical to those required for writing applets. The major difference is that the applet code appears in the init method rather than in main. For information on how to set up the applet's HTML page, see Setting Up the HTML Page. Here's the complete code for the applet version, HelloApplet.java.

Performing Basic Setup

The basic shell of a CORBA client is the same as many Java applications: You import required library packages, declare the application class, define a main method, and remember to handle any exceptions.

Importing Required Packages
Start your text editor and save a new file titled HelloClient.java to your project directory.

Import the packages required for the client class: 

import HelloApp.*;           // The package containing our stubs.
import org.omg.CosNaming.*;  // HelloClient will use the naming service.
import org.omg.CORBA.*;      // All CORBA applications need these classes.
Applet Note: If you are writing an applet, you also need to import java.awt.Graphics and org.omg.CosNaming.NamingContextPackage.*. The latter package contains special exceptions thrown by the name service.

Declaring the Client Class
In HelloClient.java, declare the client class: 

public class HelloClient
{
    // Add the main method here in the next step.
}
Applet Note: In the applet version of this code, HelloApplet.java, you declare the applet class like this: 

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

Defining a main Method
Every Java application needs a main method. Declare it within the scope of the HelloClient class, as follows: 

public static void main(String args[])
{
    // Put the try-catch block here in the next step.
}

Handling CORBA System Exceptions
Because all CORBA programs can throw CORBA system exceptions at runtime, you will place all of the main functionality within a try-catch block. CORBA programs throw system exceptions whenever trouble occurs during any of the processes involved in invoking the server from the client.

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

Inside main, set up a try-catch block block: 

try {
    // Add the rest of the HelloClient code here.
} catch(Exception e) {
    System.out.println("ERROR : " + e);
    e.printStackTrace(System.out);
}

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 object certain information about itself.

If you closed HelloClient.java, open it now.

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

ORB orb = ORB.init(args, null);

The call to the ORB's init method passes in your application's command line arguments, allowing you to set certain properties at runtime.

Finding the Hello Server

Now that the application 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; our client application will use the COS Naming Service specified by OMG and provided with Java IDL. See Using Stringified Object References for information on how to get an initial object reference when there is no naming service available.

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

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 the initial naming context, 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 we 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 name. An array of NameComponent objects can hold a fully specified 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 the Hello server. Add this code directly below the call to narrow. 

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

This statement sets the id field of the new NameComponent,nc, to "Hello" and the kind field to an 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 path 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 helper 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.

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 generated code, invocation is really the easiest part of CORBA programming.

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

  2. Still in the try-catch block, below the call to the name service's resolve method, enter the invocation: 
          String Hello = helloRef.sayHello;
  3. Finally, print the results of the invocation to standard output: 
          System.out.println(Hello);
  4. Save and close HelloClient.java.

Compiling and Running the Hello World Application

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

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

Application Setup

  1. Create a new project directory, called Application.

  2. Copy your HelloClient.java file to the Application directory.

  3. Copy HelloServer.class and HelloServant.class from [Path_to_JDK]\docs\guide\idl\tutorial\app to the Application directory.

  4. Copy [Path_to_JDK]\docs\guide\idl\tutorial\app\HelloApp and its complete contents to the Application directory.

Your project directory should look like this: 

Application
 |-HelloClient.java
 |-HelloServant.class
 |-HelloServer.class
 |-HelloApp
    |-_HelloImplBase.class
    |-_HelloStub.class
    |-Hello.class
    |-HelloHelper.class
    |-HelloHolder.class

Compiling the Client Application
  1. Change directory to the Application directory you created.

  2. Run the Java compiler on HelloClient.java: 
    javac HelloClient.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 HelloClient.class in the Application directory.
Running the Client Application
  1. Start the Java IDL name server: 
    tnameserv -ORBInitialPort 1050 &
  2. Start the Hello server: 
    java HelloServer -ORBInitialPort 1050 &
  3. Run the Hello application client from another window: 
    java HelloClient -ORBInitialPort 1050

    The string prints to the command line: 

    Hello world!!

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

Troubleshooting
Specifying ORB Initial Port
The default ORB Initial Port is port 900. If you prefer, you can omit the port specifications if you start the name server on port 900. Using Solaris software, you must become root to start a process on a port under 1024. Remember to exit from root access before continuing with the tutorial if you choose to use this port for your name server.
Setting Up the HTML File (Applets Only)

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 trail).

For More Information
[PENDING]

Previous | Next | Trail Map | Programming with Java IDL | The Hello Client Server Example