The JavaTM Tutorial

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Trail: IDL
Lesson: The Hello Client-Server Example

## Developing a Client Application

> This lesson introduces the basics of writing a CORBA client application. Here's the 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 File (Applets Only). 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:

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

> Inside`HelloClient.java`'s `try-catch` 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

> Once 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 no naming service is 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 `nc`, the new `NameComponent`, 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. Continuing with the try-catch block in `HelloClient.java`, enter the following invocation below the call to the name service's `resolve`method:

>    >     String hello = helloRef.sayHello();

> 2. Finally, add code to print the results of the invocation to standard output:

>    >     System.out.println(hello);

> 3. Save and close `HelloClient.java`.

### Setting Up the HTML File (Applets Only)

> `Tutorial.html` 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 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. Make sure the second `PARAM` tag is set to the value of `ORBInitialPort` that you are using to run the name server (it's preset to 1050 to work with the default used in the examples in this trail). In any case, it should be a value above 1028.

Now you're ready to write the server code.

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Copyright 1995-2004 Sun Microsystems, Inc. All rights reserved.