# Getting Started with Java IDL: Developing a Client Application

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

1. Creating HelloClient.java
2. Understanding HelloClient.java
3. Compiling HelloClient.java

## Creating HelloClient.java

To create `HelloClient.java`,

1. Start your text editor and create a file named `HelloClient.java` in your main project directory, `Hello`.

2. Enter the following code for `HelloClient.java` in the text file. The following section, Understanding HelloClient.java, explains each line of code in some detail.

   HelloClient.java

       // Copyright and License

       import HelloApp.*;
       import org.omg.CosNaming.*;
       import org.omg.CosNaming.NamingContextPackage.*;
       import org.omg.CORBA.*;

       public class HelloClient
       {
         static Hello helloImpl;

         public static void main(String args[])
           {
             try{
               // create and initialize the ORB
       	ORB orb = ORB.init(args, null);

               // get the root naming context
               org.omg.CORBA.Object objRef =
       	    orb.resolve_initial_references("NameService");
               // Use NamingContextExt instead of NamingContext. This is
               // part of the Interoperable naming Service.
               NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

               // resolve the Object Reference in Naming
               String name = "Hello";
               helloImpl = HelloHelper.narrow(ncRef.resolve_str(name));

               System.out.println("Obtained a handle on server object: " + helloImpl);
               System.out.println(helloImpl.sayHello());
               helloImpl.shutdown();

       	} catch (Exception e) {
                 System.out.println("ERROR : " + e) ;
       	  e.printStackTrace(System.out);
       	  }
           }

       }

3. Save and close `HelloClient.java`.

## Understanding HelloClient.java

This section explains each line of `HelloClient.java`, describing what the code does, as well as why it is needed for this application.

### 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 handle exceptions.

#### Importing Required Packages

First, we 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.CosNaming.NamingContextPackage.*;
    import org.omg.CORBA.*; // All CORBA applications need these classes

#### Declaring the Client Class

The next step is to declare the client class:

    public class HelloClient
    {
      // The main() method goes here.
    }

#### Defining a `main()` Method

Every Java application needs a `main()` method. It is declared within the scope of the `HelloClient` class, as follows:

      public static void main(String args[])
      {
        // The try-catch block goes here.
      }

#### Handling CORBA System Exceptions

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

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.

The try-catch block is set up inside `main()`,

        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.

The ORB variable is declared and initialized inside the try-catch block.

    	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.

The two options for Naming Services shipped with J2SE v.1.4 are `orbd`, which is a daemon process containing a Bootstrap Service, a Transient Naming Service, a Persistent Naming Service, and a Server Manager, and `tnameserv`, a transient naming service. This example uses `orbd`.

#### 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, you 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. The string "NameService" indicates:

- The persistent naming service will be used when using ORBD as the naming service.
- The transient naming service will be used when using `tnameserv` as the naming service.

The string "TNameService" indicates that the transient naming service will be used when ORBD is the naming service. In this example, we are using the persistent naming service that is a part of `orbd`.

#### Narrowing the Object Reference

As with all CORBA object references, `objRef` is a generic CORBA object. To use it as a `NamingContextExt` object, you must narrow it to its proper type.

            NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

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

The `NamingContextExt` object is new to J2SE v.1.4, and is part of the Interoperable Naming Service.

#### Resolve the Object Reference in Naming

To publish a reference in the Naming Service to the `Hello` object implementing the `Hello` interface, you first need an identifying string for the `Hello` object.

          String name = "Hello";

Finally, we pass `name` to the naming service's `resolve_str()` method to get an object reference to the Hello server and narrow it to a `Hello` object:

            helloImpl = HelloHelper.narrow(ncRef.resolve-str(name));
            System.out.println("Obtained a handle on server object: " + helloImpl);

Here you see the `HelloHelper` helper class at work. The `resolve-str()` 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. Then, you send a message to the screen confirming that the object reference has been obtained.

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

Finally, we print the results of the invocation to standard output and explicitly shutdown the ORB:

            System.out.println(helloImpl.sayHello());
            helloImpl.shutdown();

## Compiling HelloClient.java

Now we will compile `HelloClient.java` so that we can correct any errors before continuing with this tutorial.

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

To compile `HelloClient.java`,

1. Change to the `Hello` directory.

2. Run the Java compiler on `HelloClient.java`:

       javac HelloClient.java HelloApp/*.java

3. Correct any errors in your file and recompile if necessary.
4. The `HelloClient.class` is generated to the `Hello` directory.

### Running the Client Application

Running the Hello World application is covered in Running the Hello World Application.

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

Previous: Developing the Hello World Server
Next: Running the Hello World Application
Tutorial home: Getting Started with Java IDL

Java IDL Home

Copyright © 1996-2001 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.