Using IDL

This section describes how to use the CORBA interface description language (IDL).

Introduction to IDL

The Interface Definition Language (IDL) is a descriptive language (not a programming language) to describe the interfaces being implemented by the remote objects. Within IDL, you define the name of the interface, the names of each of the attributes and methods, and so forth. Once you’ve created the IDL file, you can use an IDL compiler to generate the client stub file and the server skeleton file in the Java programming language.

For more information see “Using IDL”.

The OMG has defined specifications for such language mapping. Information about the language mapping is not covered in this manual since VisiBroker adheres to the specification set forth by OMG. If you need more information about language mapping, see the OMG web site at http://www.omg.org.

Note

The CORBA 3.0 formal specification can be found at
http://www.omg.org/technology/documents/vault.htm#CORBA_IIOP.

Discussions on the IDL can be quite extensive. Because VisiBroker adheres to the specification defined by OMG, you can visit the OMG site for more information about IDL.

How the IDL compiler generates code

You use the Interface Definition Language (IDL) to define the object interfaces that client programs may use. The idl2java compiler uses your interface definition to generate code.

Example IDL specification

Your interface definition defines the name of the object as well as all of the methods the object offers. Each method specifies the parameters that will be passed to the method, their type, and whether they are for input or output or both. The IDL sample below shows an IDL specification for an object named example. The example object has only one method, op1.

// IDL specification for the example object
interface example {
long op1(in char x, out short y);
};

Looking at the generated code

The IDL compiler generates several files from the above Example IDL specification.

•	_exampleStub.java is the stub code for the example object on the client side.

•	example.java is the example interface declaration.

•	exampleHelper.java declares the exampleHelper class, which defines helpful utility functions and support functions for the example interface.

•	exampleHolder.java declares the exampleHolder class, which provides a holder for passing out and inout parameters.

•	exampleOperations.java defines the methods in the example interface and is used both on the client and the server side. It also works together with the tie classes to provide the tie mechanism.

•	examplePOA.java contains the skeleton code (implementation base code) for the example object on the server side.

•	examplePOATie.java contains the class used to implement the example object on the server side using the tie mechanism.

_<interface_name>Stub.java

For each user-defined type, a stub class is created by the idl2java compiler. This is the class which is instantiated on the client side which implements the <interface_name> interface.

public class exampleStub extends com.inprise.vbroker.CORBA.portable.ObjectImpl
implements example {
final public static java.lang.Class _opsClass = exampleOperations.class;
public java.lang.String[] ids () {
...
}
public int op1 (char x, org.omg.CORBA.ShortHolder y) {
...
}

<interface_name>.java

The <interface_name>.java file is the Java interface generated for each IDL interface. This is the direct mapping of the IDL interface definition to the appropriate Java interface. This interface is then implemented by both the client and server skeleton.

public interface example extends com.inprise.vbroker.CORBA.Object,
exampleOperations,
org.omg.CORBA.portable.IDLEntity {
}

<interface_name>Helper.java

For each user-defined type, a helper class is created by idl2java. The Helper class is an abstract class with various static methods for the generated Java interface.

public final class exampleHelper {
public static example narrow (final org.omg.CORBA.Object obj) {
...
}
public static example unchecked_narrow (org.omg.CORBA.Object obj) {
...
}
public static example bind (org.omg.CORBA.ORB orb) {
...
}
public static example bind (org.omg.CORBA.ORB orb,
java.lang.String name) {
...
}
public static example bind (org.omg.CORBA.ORB orb, java.lang.String name,
java.lang.String host,
com.inprise.vbroker.CORBA.BindOptions _options) {
...
}
public static example bind (org.omg.CORBA.ORB orb, java.lang.String
fullPoaName,
byte[] oid) {
...
}
public static example bind (org.omg.CORBA.ORB orb,
java.lang.String fullPoaName, byte[] oid,
java.lang.String host,
com.inprise.vbroker.CORBA.BindOptions _options) {
...
}
public java.lang.Object read_Object (final org.omg.CORBA.portable.
InputStream istream) {
...
}
public void write_Object (
final org.omg.CORBA.portable.OutputStream ostream,
final java.lang.Object obj) {
...
}
public java.lang.String get_id () {
...
}
public org.omg.CORBA.TypeCode get_type () {
...
}
public static example read (
final org.omg.CORBA.portable.InputStream _input) {
...
}
public static void write (
final org.omg.CORBA.portable.OutputStream _output,
final example value) {
...
}
public static void insert (
final org.omg.CORBA.Any any, final example value) {
...
}
public static example extract (final org.omg.CORBA.Any any) {
...
}
public static org.omg.CORBA.TypeCode type () {
...
}
public static java.lang.String id () {
...
}
}

<interface_name>Holder.java

For each user-defined type, a holder class is created by the idl2java compiler. It provides a class for an object which wraps objects which support the <interface_name> interface when passed as out and inout parameters.

public final class exampleHolder
implements org.omg.CORBA.portable.Streamable {
public foo.example value;
public exampleHolder () {
}
public exampleHolder (final foo.example _vis_value) {
...
}
public void _read (final org.omg.CORBA.portable.InputStream input) {
...
}
public void _write (final org.omg.CORBA.portable.OutputStream output) {
...
}
public org.omg.CORBA.TypeCode _type () {
...
}
}

<interface_name>Operations.java

For each user-defined type, an operations class is created by the idl2java compiler which contains all the methods defined in the IDL declaration.

public interface exampleOperations {
public int op1(char x, org.omg.CORBA.ShortHolder y);
}

<interface_name>POA.java

The <interface_name>POA.java file is the server-side skeleton for the interface. It unmarshals in parameters and passes them in an upcall to the object implementation and marshals back the return value and any out parameters.

public abstract class examplePOA
extends org.omg.PortableServer.Servant
implements org.omg.CORBA.portable.InvokeHandler, exampleOperations {
public example _this () {
...
}
public example _this (org.omg.CORBA.ORB orb) {
...
}
public java.lang.String[] _all_interfaces (
final org.omg.PortableServer.POA poa,
...
}
public org.omg.CORBA.portable.OutputStream _invoke (java.lang.String opName,
org.omg.CORBA.portable.InputStream _input,
org.omg.CORBA.portable.ResponseHandler handler) {
...
}
public static org.omg.CORBA.portable.OutputStream _invoke (exampleOperations _self,
int _method_id, org.omg.CORBA.portable.InputStream _input,
org.omg.CORBA.portable.ResponseHandler _handler) {
...
}
}

<interface_name>POATie.java

The <interface_name>POATie.java file is a delegator implementation for the <interface_name> interface. Each instance of the tie class must be initialized with an instance of an implementation class that implements the <interface_name>Operations class to which it delegates every operation.

public class examplePOATie extends examplePOA {
public examplePOATie (final exampleOperations _delegate) {
...
}
public examplePOATie (final exampleOperations _delegate,
final org.omg.PortableServer.POA _poa) {
...
}
public exampleOperations _delegate () {
...
}
public void _delegate (final exampleOperations delegate) {
...
}
public org.omg.PortableServer.POA _default_POA () {
...
}
public int op1 (char x, org.omg.CORBA.ShortHolder y) {
...
}
}

Defining interface attributes in IDL

In addition to operations, an interface specification can also define attributes as part of the interface. By default, all attributes are read-write and the IDL compiler will generate two methods, one to set the attribute's value, and one to get the attribute's value. You can also specify read-only attributes, for which only the reader method is generated.

The IDL sample below shows an IDL specification that defines two attributes, one read-write and one read-only.

interface Test {
attribute long count;
readonly attribute string name;
};

The following code sample shows the operations class generated for the interface declared in the IDL.

public interface TestOperations {
public int count ();
public void count (int count);
public java.lang.String name ();
}

Specifying one-way methods with no return value

IDL allows you to specify operations that have no return value, called one-way methods. These operations may only have input parameters. When a oneway method is invoked, a request is sent to the server, but there is no confirmation from the object implementation that the request was actually received.

VisiBroker uses TCP/IP for connecting clients to servers. This provides reliable delivery of all packets so the client can be sure the request will be delivered to the server, as long as the server remains available. Still, the client has no way of knowing if the request was actually processed by the object implementation itself.

Note

One-way operations cannot raise exceptions or return values.

interface oneway_example {
oneway void set_value(in long val);
};

Specifying an interface in IDL that inherits from another interface

IDL allows you to specify an interface that inherits from another interface. The classes generated by the IDL compiler will reflect the inheritance relationship. All methods, data type definitions, constants and enumerations declared by the parent interface will be visible to the derived interface.

interface parent {
void operation1();
};
interface child : parent {
...
long operation2(in short s);
};

The code sample below shows the code that is generated from the interface specification shown above.

public interface parentOperations {
public void operation1 ();
}
public interface childOperations extends parentOperations {
public int operation2 (short s);
}
public interface parent
extends com.inprise.vbroker.CORBA.Object, parentOperations,
org.omg.CORBA.portable.IDLEntity {
}
public interface child extends childOperations, Baz.parent,
org.omg.CORBA.portable.IDLEntity {
}