Using ILU Interface Specifications

Service types and ILU interfaces

Every shared object in the KOE has a type that is defined by an ILU interface specification. Many of these types are built into the system. The namespace, for example, uses contexts and desciptors that have a type defined in the official Namespace interface specification (in the file koe/interfaces/Namespace.isl).

A KP creates a service using the bind_service() call, which takes the service's type as one of its arguments. In this context, type refers to an Object declared in an interface specification. The name of the type is a string of the form InterfaceName.ObjectTypeName. Most of the types used by the KOE follow a convention that the interface name ends with "API", e.g. "BitBucketAPI.BitBucket". By appending the string "API" to the interface name we can distinguish it from the specific object type BitBucket that is part of the interface specification.

Developing a new application will probably involve creating a new interface specification to describe the communications patterns among the Knowbot Programs and plugins that make up the application. The example programs define new interfaces that include application-specific types.

An interface is defined using the ILU Interface Specification Language (ISL). The interface must stored in a file in koe/interfaces. An interface specification begins with a declaration INTERFACE Name that specifies the interface's name. An interface includes declaration for basic datatypes, ranging from byte and integer to array and union, for exceptions, and for object datatypes. All the bindings in the KOE namespace are to instances of object types. For more information about the specifics of ILU ISL, refer to chapter two of the ILU reference manual. If you have not downloaded and installed ILU yet, the distribution can be obtained here.

Programs that use these interfaces needs stub code generated by ILU. The python-stubber, included in the ILU distribution, generates stub code for client and server from the interface definition. (In ILU terminology, the client code is stub code and server code is skeleton code.)

Services that are used or provided by KPs are instances of an object type. For a KP to use a service -- either to create a service using bind_service() or to act as a client of a service found using lookup_serivce() -- the service station where the KP is running must have the stub code installed in koe/interfaces/stubs. An important consequence of this requirement is that KPs can't expect a service station run under someone else's control to have the same interfaces that are defined locally.

Installing New Interfaces

This section describes how to install a new interface specification so that it is available for use by KPs and plugins.

Put the ISL file in koe/interfaces. Be sure that the name of the file containing the interface definition is the same as the name used in the INTERFACE declaration.
Update the file koe/interfaces/stubs/Makefile.in. Add an entry to the definition of the TARGETS macro. The target is the Python stub code generated from the interface definition. For the interface BitBucketAPI (in file BitBucketAPI.isl), the entry in TARGETS should be BitBucketAPI.py.
Generate the new koe/interfaces/stubs/Makefile by running the program isldepend.py in that directory. This program calculates all the target dependencies and appends them to the source of Makefile.in, writing the results to Makefile. Run isldepend.py like this:
```
$ ./isldepend.py `(cd .. ; ls *.isl)`
```
Type 'make' in the $KOSROOT directory. This will build the stubs needed by KPs that use the interface.