CS696: Doc 21, CORBA IDL part 2

	CS 696 Emerging Technologies: Distributed Objects

Spring Semester, 1998
CORBA IDL part 2
To Lecture Notes Index
© 1998, All Rights Reserved, SDSU & Roger Whitney
San Diego State University -- This page last updated 21-Apr-98

Contents of Doc 21, CORBA IDL part 2

References

References

CORBA Specification V2.1 Chapter 3 OMG IDL Syntax and Semantics, August 1997

CORBA Specification V2.2 Chapter 24, Mapping of OMG IDL to Java, February 1998

OrbixWeb Programmer's Guide, IONA Technologies PLC, November 1997, chapter 5 Introduction to CORBA IDL, chapter 6 IDL to Java Mapping pp 79 - 140

Iona's IDL compiler

Doc 21, CORBA IDL part 2 Slide # 2

Operations

CORBA supports three type of parameter passing

in

parameter is passed into the operation from the caller

out

parameter is passed out of the operation to the caller, but no value is passed in

inout

parameter is passed into the operation and returned to the caller

An implementation should not attempt to modify an in parameter

The ability to even attempt to change an in parameter is language specific, the effect is undefined

If an exception is raised in the operation the values of the return, an any out and inout parameters is not defined

When an unbounded string or sequence is passed as an inout parameter, the returned value cannot be longer than the input value

Doc 21, CORBA IDL part 2 Slide # 3

Java Mapping to Parameters

Java uses a Holder class to implement out and inout parameters
The IDL

interface In_Out_Examples
   {
   void just_out( out short a);
   void in_out( inout string b);
   void just_in( in char c);
   };

The Java generated interface

public interface In_Out_Examples
    extends org.omg.CORBA.Object
{
    public void just_out(org.omg.CORBA.ShortHolder a) ;
    public void in_out(org.omg.CORBA.StringHolder b) ;
    public void just_in(char c) ;
    public java.lang.Object _deref() ;
}

Holder class for built-in types

package org.omg.CORBA
final public class ShortHolder
   {
   public short value;
   public ShortHolder() {}
   public ShortHolder(short initial)
      {
      value = initial;
      }
   }
Doc 21, CORBA IDL part 2 Slide # 4

Using the Holder

class SampleUse
   {
   public void aMethod()
      {
      In_Out_Examples sample = get_A_real_object();
      ShortHolder out = new ShortHolder();
      sample.just_out( out);
      short theRealValue = out.value;
      }
   }

class In_Out_Examples extends _In_Out_ExamplesImplBase
   {
   public void just_out(org.omg.CORBA.ShortHolder a)
      {
      a.value = (short) 3;
      }

   etc.
   }

Template for all Holder classes of built-in types

final public class <Type>Holder
   {
   public <type> value;
   public <Type>Holder() {}
   public <Type>Holder(<type> intial)
      {
      value = initial;
      }
   }

Doc 21, CORBA IDL part 2 Slide # 5

Holders and User Defined Types
All user defined types also need holders for when they are passed as parameters or return types

Example of Holder for user defined types

// Generated by IDL compiler

import IE.Iona.OrbixWeb._OrbixWeb;

public final class In_Out_ExamplesHolder
     implements org.omg.CORBA.portable.Streamable
{
    public In_Out_Examples value;

    public In_Out_ExamplesHolder() {}

    public In_Out_ExamplesHolder(In_Out_Examples value) {
        this.value = value;
    }
    public void _read (org.omg.CORBA.portable.InputStream _stream) {
        value = In_Out_ExamplesHelper.read(_stream);
    }
    public void _write (org.omg.CORBA.portable.OutputStream _stream) {
        In_Out_ExamplesHelper.write(_stream, value);
    }
    public org.omg.CORBA.TypeCode _type () {
        return In_Out_ExamplesHelper.type();
    }
}
Doc 21, CORBA IDL part 2 Slide # 6

Oneway Operation

A oneway method does not block on a response from the server object

The method is not guaranteed to be delivered

The invocation semantics are "best-effort", which implies the method will invoked at most once

A oneway operation can not return a value or contain out or inout parameters or explicitly raise an exception

interface No_Blocking_Here
   {
   oneway void no_reply( in string message);
   };

Java Mapping

// Java generated by the OrbixWeb IDL compiler

public interface No_Blocking_Here
    extends org.omg.CORBA.Object
{
    public void no_reply(String message) ;

    public java.lang.Object _deref() ;
}

Doc 21, CORBA IDL part 2 Slide # 7

Attributes

Attributes are logically equivalent to a pair of accessor functions

A readonly attribute means just produce the get accessor methods

interface Account
   {
   readonly attribute float balance;
   attribute string name;
   };

Java Mapping

// Java generated by the OrbixWeb IDL compiler

public interface Account
    extends org.omg.CORBA.Object
{
    public float balance();

    public String name();
    public void name(String value);

    public java.lang.Object _deref() ;
}

Doc 21, CORBA IDL part 2 Slide # 8

Exceptions

User defined exceptions are checked

module University
   {
   exception party_time { string event; };
   exception break { short term; short year; };
   interface partyAnimal
      {
      void study( in string man) raises (party_time, break);
      };
   };

Java Mapping

// Java generated by the OrbixWeb IDL compiler

package University;

public interface partyAnimal
    extends org.omg.CORBA.Object
{
    public void study(String man)
        throws University.party_time, University._break;

    public java.lang.Object _deref() ;
}

Doc 21, CORBA IDL part 2 Slide # 9

 // Java generated by the OrbixWeb IDL compiler
package University;

public final class party_time
    extends org.omg.CORBA.UserException
    implements java.lang.Cloneable
{
    public String event;

    public party_time() {
        super();
    }

    public party_time(String event) {
        super();
        this.event = event;
    }

    public java.lang.Object clone() { code removed }
}

Doc 21, CORBA IDL part 2 Slide # 10

Standard CORBA Exceptions

All predefined (standard) CORBA exceptions are unchecked

A standard CORBA exception may not be listed in a raises

All standard CORBA includes a completion_status code which takes on one of the following values:

COMPLETED_YES

Object implementation completed processing prior to exception being raised

COMPLETED_NO

Object implementation was never initiated prior to exception being raised

COMPLETED_MAYBE

Status of the implementation is indeterminate

Each standard exception includes a minor code to designate the subcategory of the exception

The values used for the minor code are left to each ORB implementation

Doc 21, CORBA IDL part 2 Slide # 11

package org.omg.CORBA;

abstract public class SystemException extends 
      java.lang.RunTimeException {
   public int minor;
   public CompletionStatus completed;

   protected SystemException( String reason,
                                 int minor,
                                 CompletionStatus status) {
      super( reason );
      this.minor = minor;
      this.status = status;
   }
}

CompletionStatus is defined by the IDL:

enum CompletionStatus { COMPLETED_YES,
                  COMPLETED_NO,
                  COMPLETED_MAYBE};
Doc 21, CORBA IDL part 2 Slide # 12

Constructed Types

There are three constructed types:

Structures
Enumerations
Discriminated Unions

module ConstructedTypes {
   struct Time {
      short hour;
      short minute;
      short second;
   };
   
   typedef Time CORBA_Time;

   enum Grades {A, B, Forget_it};

};

Doc 21, CORBA IDL part 2 Slide # 13

Structures

module ConstructedTypes {
   struct Time {
      short hour;
      short minute;
      short second;
   };
   
   typedef Time CORBA_Time;
};

The Java Mapping

// Java generated by the OrbixWeb IDL compiler

package ConstructedTypes;

public final class Time
    implements java.lang.Cloneable  {
    public short hour;
    public short minute;
    public short second;

    public Time () {}

    public Time (short hour,short minute,short second) {
        this.hour = hour;
        this.minute = minute;
        this.second = second;
    }

    public java.lang.Object clone() { code removed    }
}
Doc 21, CORBA IDL part 2 Slide # 14

Typedef

module ConstructedTypes {
   struct Time {
      short hour;
      short minute;
      short second;
   };
   
   typedef Time CORBA_Time;

   interface test {
      CORBA_Time when();
   };
};

Doc 21, CORBA IDL part 2 Slide # 15

Enumerations

A maximum of 2³² items can defined in an enumeration

module ConstructedTypes
   {
   enum Grades {A, B, Forget_it};
    };
Doc 21, CORBA IDL part 2 Slide # 16

The Java Mapping

// Java generated by the OrbixWeb IDL compiler

package ConstructedTypes;

public final class Grades
    implements java.lang.Cloneable
{
    public static final int _A = 0;
    public static final Grades A = new Grades(_A);
    public static final int _B = 1;
    public static final Grades B = new Grades(_B);
    public static final int _Forget_it = 2;
    public static final Grades Forget_it = new Grades(_Forget_it);

    public static final Grades IT_ENUM_MAX = new Grades(Integer.MAX_VALUE);

    public int value () {
        return ___value;
    }

   public static Grades from_int (int value) {
        switch (value) {
            case _A : return A;
            case _B : return B;
            case _Forget_it : return Forget_it;
            default :
               throw new org.omg.CORBA.BAD_PARAM("Enum out of range");
        }
    }

    private Grades (int value) {
        ___value = value;
    }

    private int ___value;

    public java.lang.Object clone(){
        return from_int(___value);
    }
}
Doc 21, CORBA IDL part 2 Slide # 17

Template Types

There are three template types:

Sequences
Strings
Fixed point

Strings

interface Bank {
   // unbonded string
   readonly attribute string address;

   // bounded size string
   readonly attribute string first_name<10>;

   // string using wchars
   readonly attribute wstring last_name<5>;
};

OMG IDL strings are mapped to java.lang.String

Since java strings do not have bounds, IDL strings passed to/from operations are check for size

If the actual size is larger than the OMG IDL string allows, a run time exception is thrown

Doc 21, CORBA IDL part 2 Slide # 18

Sequence

A sequence is one-dimensional array with a maximum size and length

A sequence must be named by an IDL typedef declaration before it can be used as the type of an IDL attribute or operation parameter

OMG IDL sequences are mapped to java arrays

Since java arrays do not have bounds, IDL arrays passed to/from operations are check for size

If the actual size is larger than the OMG IDL arrays allows, a run time exception is thrown

interface Account {
   readonly attribute string name;
};

struct Accounts {
   // bounded
   sequence<Account, 10> acountList;
   // unbounded
   sequence<short> ID;
};

typedef sequence<long> accountNmbers;

interface Bank {
   void accountList( out accountNmbers list);
};

Doc 21, CORBA IDL part 2 Slide # 19

Java Mappings

// Java generated by the OrbixWeb IDL compiler
//

import Account;
import AccountHelper;
import AccountHolder;
import _AccountOperations;
import _AccountStub;

public final class Accounts
    implements java.lang.Cloneable
{
    public Account[] acountList;
    public short[] ID;

    public Accounts () {}

    public Accounts (Account[] acountList,short[] ID) {
        this.acountList = acountList;
        this.ID = ID;
    }

    public java.lang.Object clone() { code removed    }
}

Doc 21, CORBA IDL part 2 Slide # 20

Fixed Point Types

Not supported by Java mappings at this time

Doc 21, CORBA IDL part 2 Slide # 21

Arrays

Array can be multi-dimensional and have fixed size

An array must be named by an IDL typedef declaration before it can be used as the type of an IDL attribute or operation parameter

Arrays are mapped to java arrays

typedef short BankCode[4];

typedef long multi[2, 4];

interface Sample {
   readonly attribute BankCode code;
};

Java Mapping for Sample

// Java generated by the OrbixWeb IDL compiler

import BankCodeHelper;
import BankCodeHolder;

public interface Sample
    extends org.omg.CORBA.Object
{
    public short[] code();
    public java.lang.Object _deref() ;
}
Doc 21, CORBA IDL part 2 Slide # 22

Java Holder for BankCode
Since each OMG IDL type needs a Holder and a Helper, they are generated for the type BankCode, even though it is mapped to an array

// Java generated by the OrbixWeb IDL compiler

import IE.Iona.OrbixWeb._OrbixWeb;

public final class BankCodeHolder
     implements org.omg.CORBA.portable.Streamable
{
    public short[] value;
    public BankCodeHolder() {}

    public BankCodeHolder(short[] value) {
        this.value = value;
    }
    public void _read ( blah) { code removed }
    public void _write (blah) { code removed }
    public org.omg.CORBA.TypeCode _type ()
      { code removed }
}

visitors since 19-Mar-98