Using ILU With Java

Using ILU with Java

Introduction

This tutorial will show how to use the ILU system with the programming language Java, both as a way of developing software libraries, and as a way of building distributed systems. In an extended example, we'll build an ILU module that implements a simple four-function calculator, capable of addition, subtraction, multiplication, and division. It will signal an error if the user attempts to divide by zero. The example demonstrates how to specify the interface for the module; how to implement the module in Java; how to use that implementation as a simple library; how to provide the module as a remote service; how to write a client of that remote service; and how to use subtyping to extend an object type and provide different versions of a module. We'll also demonstrate how to use OMG IDL with ILU, and discuss the notion of network garbage collection.

Each of the programs and files referenced in this tutorial is available as a complete program in a separate appendix to this document; parts of programs are quoted in the text of the tutorial.

Specifying the Interface

Our first task is to specify more exactly what it is we're trying to provide. A typical four-function calculator lets a user enter a value, then press an operation key, either +, -, /, or *, then enter another number, then press = to actually have the operation happen. There's usually a CLEAR button to press to reset the state of the calculator. We want to provide something like that.

We'll recast this a bit more formally as the interface of our module; that is, the way the module will appear to clients of its functionality. The interface typically describes a number of function calls which can be made into the module, listing their arguments and return types, and describing their effects. ILU uses object-oriented interfaces, in which the functions in the interface are grouped into sets, each of which applies to an object type. These functions are called methods.

For example, we can think of the calculator as an object type, with several methods: Add, Subtract, Multiply, Divide, Clear, etc. ILU provides a standard notation to write this down with, called ISL (which stands for "Interface Specification Language"). ISL is a declarative language which can be processed by computer programs. It allows you to define object types (with methods), other non-object types, exceptions, and constants.

The interface for our calculator would be written in ISL as:

INTERFACE Tutorial;

EXCEPTION DivideByZero;

TYPE Calculator = OBJECT
  METHODS
    SetValue (v : REAL),
    GetValue () : REAL,
    Add (v : REAL),
    Subtract (v : REAL),
    Multiply (v : REAL),
    Divide (v : REAL) RAISES DivideByZero END
  END;

This defines an interface Tutorial, an exception DivideByZero, and an object type Calculator. Let's consider these one by one.

The interface, Tutorial, is a way of grouping a number of type and exception definitions. This is important to prevent collisions between names defined by one group and names defined by another group. For example, suppose two different people had defined two different object types, with different methods, but both called Calculator! It would be impossible to tell which calculator was meant. By defining the Calculator object type within the scope of the Tutorial interface, this confusion can be avoided.

The exception, DivideByZero, is a formal name for a particular kind of error, division by zero. Exceptions in ILU can specify an exception-value type, as well, which means that real errors of that kind have a value of the exception-value type associated with them. This allows the error to contain useful information about why it might have come about. However, DivideByZero is a simple exception, and has no exception-value type defined. We should note that the full name of this exception is Tutorial.DivideByZero, but for this tutorial we'll simply call our exceptions and types by their short name.

The object type, Calculator (again, really Tutorial.Calculator), is a set of six methods. Two of those methods, SetValue and GetValue, allow us to enter a number into the calculator object, and "read" the number. Note that SetValue takes a single argument, v, of type REAL. REAL is a built-in ISL type, denoting a 64-bit floating point number. Built-in ISL types are things like INTEGER (32-bit signed integer), BYTE (8-bit unsigned byte), and CHARACTER (16-bit Unicode character). Other more complicated types are built up from these simple types using ISL type constructors, such as SEQUENCE OF, RECORD, or ARRAY OF.

Note also that SetValue does not return a value, and neither do Add, Subtract, Multiply, or Divide. Rather, when you want to see what the current value of the calculator is, you must call GetValue, a method which has no arguments, but which returns a REAL value, which is the value of the calculator object. This is an arbitrary decision on our part; we could have written the interface differently, say as

TYPE NotOurCalculator = OBJECT
  METHODS
    SetValue () : REAL,
    Add (v : REAL) : REAL,
    Subtract (v : REAL) : REAL,
    Multiply (v : REAL) : REAL,
    Divide (v : REAL) : REAL RAISES DivideByZero END
  END;

-- but we didn't.

Our list of methods on Calculator is bracketed by the two keywords METHODS and END, and the elements are separated from each other by commas. This is pretty standard in ISL: elements of a list are separated by commas; the keyword END is used when an explicit list-end marker is needed (but not when it's not necessary, as in the list of arguments to a method); the list often begins with some keyword, like METHODS. The raises clause (the list of exceptions which a method might raise) of the method Divide provides another example of a list, this time with only one member, introduced by the keyword RAISES.

Another standard feature of ISL is separating a name, like v, from a type, like REAL, with a colon character. For example, constants are defined with syntax like

CONSTANT Zero : INTEGER = 0;

Definitions, of interface, types, constants, and exceptions, are terminated with a semicolon.

We should expand our interface a bit by adding more documentation on what our methods actually do. We can do this with the docstring feature of ISL, which allows the user to add arbitrary text to object type definitions and method definitions. Using this, we can write

INTERFACE Tutorial;

EXCEPTION DivideByZero
  "this error is signalled if the client of the Calculator calls
the Divide method with a value of 0";

TYPE Calculator = OBJECT
  COLLECTIBLE
  DOCUMENTATION "4-function calculator"
  METHODS
    SetValue (v : REAL) "Set the value of the calculator to `v'",
    GetValue () : REAL  "Return the value of the calculator",
    Add (v : REAL)      "Adds `v' to the calculator's value",
    Subtract (v : REAL) "Subtracts `v' from the calculator's value",
    Multiply (v : REAL) "Multiplies the calculator's value by `v'",
    Divide (v : REAL) RAISES DivideByZero END
      "Divides the calculator's value by `v'"
  END;

Note that we can use the DOCUMENTATION keyword on object types to add documentation about the object type, and can simply add documentation strings to the end of exception and method definitions. These docstrings would be passed on to the lisp docstring system, so that they are available at runtime from lisp. Documentation strings cannot currently be used for non-object types or from Java.

ILU provides a program, islscan, which can be used to check the syntax of an ISL specification. islscan parses the specification and summarizes it to standard output:

% islscan Tutorial.isl
Interface "Tutorial", imports "ilu"
  {defined on line 1
   of file /tmp/tutorial/Tutorial.isl (Fri Jan 27 09:41:12 1995)}

Types:
  real                       {<built-in>, referenced on 10 11 12 13 14 15}

Classes:
  Calculator                 {defined on line 17}
    methods:
      SetValue (v : real);                          {defined 10, id 1}
        "Set the value of the calculator to `v'"
      GetValue () : real;                           {defined 11, id 2}
        "Return the value of the calculator"
      Add (v : real);                               {defined 12, id 3}
        "Adds `v' to the calculator's value"
      Subtract (v : real);                          {defined 13, id 4}
        "Subtracts `v' from the calculator's value"
      Multiply (v : real);                          {defined 14, id 5}
        "Multiplies the calculator's value by `v'"
      Divide (v : real) {DivideByZero};             {defined 16, id 6}
        "Divides the calculator's value by `v'"
    documentation:
      "4-function calculator"
    unique id:  ilu:cigqcW09P1FF98gYVOhf5XxGf15

Exceptions:
  DivideByZero               {defined on line 5, refs 15}
%

islscan simply lists the types defined in the interface, separating out object types (which it calls "classes"), the exceptions, and the constants. Note that for the Calculator object type, it also lists something called its unique id. This is a 160-bit number (expressed in base 64) that ILU assigns automatically to every type, as a way of distinguishing them. While it might interesting to know that it exists (:-), the ILU user never has know what it is; islscan supplies it for the convenience of the ILU implementors, who sometimes do have to know it.

Implementing the True Module

After we've defined an interface, we then need to supply an implementation of our module. Implementations can be done in any language supported by ILU. Which language you choose often depends on what sort of operations have to be performed in implementing the specific functions of the module. Different languages have specific advantages and disadvantages in different areas. Another consideration is whether you wish to use the implementation mainly as a library, in which case it should probably be done in the same language as the rest of your applications, or mainly as a remote service, in which case the specific implementation language is less important.

We'll demonstrate an implementation of the Calculator object type in Java, which is one of the most capable of all the ILU-supported languages. This is just a matter of defining a Java class, corresponding to the Tutorial.Calculator type. Before we do that, though, we'll explain how the names and signatures of the Java functions are arrived at.

What the Interface Looks Like in Java

For every programming language supported by ILU, there is a standard mapping defined from ISL to that programming language. This mapping defines what ISL type names, exception names, method names, and so on look like in that programming language.

The mapping for Java is simple. For type names, such as Tutorial.Calculator, the Java name of the ISL type Interface.Name is Interface.Name, with any hyphens replaced by underscores. That is, the name of the interface in ISL becomes the name of a class in Java. So the name of our Calculator type in Java would be Tutorial.Calculator, which is really the name of a Java class.

The Java mapping for a method name such as SetValue is the method name, with any hyphens replaced by underscores. The return type of this Java method is whatever is specified in the ISL specification for the method, or void if no type is specified. The arguments for the Java method are the same as specified in the ISL; their types are the Java types corresponding to the ISL types. An instance is simply a value of that type. Thus the Java method corresponding to our ISL SetValue would have the prototype signature

   void SetValue(float v) throws xerox.ilu.SystemException

Similarly, the signatures for the all methods, in Java, are encapsulated in this generated interface

package Tutorial;

public interface Calculator extends xerox.ilu.IluObject{
  public void SetValue(double v)
    throws xerox.ilu.IluSystemException;
  public double GetValue()
    throws xerox.ilu.IluSystemException;
  public void Add(double v)
    throws xerox.ilu.IluSystemException;
  public void Subtract(double v)
    throws xerox.ilu.IluSystemException;
  public void Multiply(double v)
    throws xerox.ilu.IluSystemException;
  public void Divide(double v)
    throws DivideByZero, xerox.ilu.IluSystemException;
} //Calculator

Note that we don't always want to generate code in a package name derived directly from the interface name. The stubber allows to specify a prefix package.

Note that even though most methods do not raise an exception, we still dedclare the system exceptions. The mapping of exception names is similar to the mapping used for types. So the exception Tutorial.DivideByZero would also have the name Tutorial.DivideByZero, in Java.

One way to see what all the Java names for an interface look like is to run the program java-stubber. This program reads an ISL file, and generates the necessary Java code to support that interface in Java. One of the files generated is `Interface.java', which contains the definitions of all the Java types for that interface.

% java-stubber Tutorial.isl
writing file javastubs/Tutorial/DivideByZero.java
writing file javastubs/Tutorial/Factory.java
writing file javastubs/Tutorial/FactoryStub.java
writing file javastubs/Tutorial/Calculator.java
writing file javastubs/Tutorial/CalculatorStub.java
%

Building the Implementation

Now we provide an implementation of our object; the CalculatorImpl class implement the generated Java interface for our Calculator class:

package Tutorial;

/*
 * While this class complies to the Tutorial.isl specification
 * it is a local implementation.  Its instances need to be
 * registered explicitely or implicitely with Ilu before they 
 * are publicly accessible.
 */

public class CalculatorImpl implements 
            Tutorial.Calculator {
    double theValue = 0.0;
    public CalculatorImpl(){
        theValue = 0.0;
    }
    public void SetValue(double v) {
        theValue = v;
    }
    public double GetValue() {
        return theValue;
    }
    public void Add(double v) {
        theValue = theValue + v;
    }
    public void Subtract(double v) {
        theValue = theValue - v;
    }
    public void Multiply(double v) {
        theValue = theValue * v;
    }
    public void Divide(double v) throws Tutorial.DivideByZero {
        if (v==0.0) throw new Tutorial.DivideByZero();
        theValue = theValue / v;
    }
} //CalculatorImpl

Each instance of a Tutorial.CalculatorImpl implements a Tutorial.Calculator. Each has an instance variable called theValue, which maintains a running total of the `accumulator' for that instance. We can create an instance of a Tutorial.CalculatorImpl object by simply calling new Tutorial.CalculatorImpl().

So, a very simple program to use the Tutorial module might be the following:

/*
 * A simple client program that demonstrates the use of the
 * Calculator module as a library.
 */ 
 
/*
 * Run this like
 * java Tutorial.simple1 number [number...]
 */ 

package Tutorial;

public class simple1 {
    
    public static void main(String argv[]) {
        CalculatorImpl calc;
        //create the calculator
        calc = new CalculatorImpl();
        if (calc==null) {
            System.err.println("Got null TapeCalculator");
            System.exit(1);
        }
        //clear the calculator before using it
        calc.SetValue(0.0);
        //now loop over the arguments, adding each in turn
        int i = 0;
        while (i<argv.length) {
            Double v = Double.valueOf(argv[i]); //don't bother about exceptions
            calc.Add(v.doubleValue());
            i = i+1;
        } 
        //and print the result
        System.out.println("The sum is " + calc.GetValue());
    } //main
    
} //simple1

This program would be compiled and then run as follows:

% java Tutorial.simple1 34.9 45.23111 12
the sum is 92.13111
%

This is a completely self-contained use of the Tutorial implementation; when a method is called, it is the true method that is invoked. The use of ILU in this program adds some overhead in terms of included code, but has almost the same performance as a version of this program that does not use ILU.

Using ILU generated interfaces

Lets do this little change: instead of

        CalculatorImpl calc;
        calc = new CalculatorImpl();

we will write

        Tutorial.Calculator calc;
        calc = new CalculatorImpl();

This obvously doesn't cause any real change but conceptionally the change is quite large: calc isn't simply a local class anymore but now is the java interface representing the ILU object.