OSIMIS APIs: PAST, PRESENT AND FUTURE
-------------------------------------

This note attempts to summarise the evolution of OSIMIS APIs
and to highlight expected changes due to future developments.
An understanding of the OSIMIS architecture, models and APIs is assumed.


CURRENT STATUS
--------------

OSIMIS is currently in version 3.3 (ICM version) and its APIs
are essentially those of version 3.0. In versions previous to 3.0
APIs changed frequently as these were development versions:
version 3.0 is considered as the first object-oriented one
with well defined APIs separating generic and application specific parts.

The only non-backwards compatible changes between 3.3 and 3.0 are:

a. that the Time attribute now holds the time as a char* and not as UTC
   (UTCtime*): this change should not affect agent applications as usually
   the time is manipulated as seconds in the UNIX tradition

b. the "Switch Gauge::set(double)" method is now called "setreal"
   to cope with the strictness of the ATT C++ compiler

c. some RMIB API methods have additional parameters; actually the RMIB
   support service existed only minimally in 3.0

In any case, these changes will be thoroughly documented in the next version
of the manual.



THE OSIMIS APIs
---------------

Let's first make clear what is meant by OSIMIS APIs. These are APIs to
manager, agent or hybrid applications that "harness and hide" generic
functionality:

- the OO ASN.1 API (Attr class)
- the Coordination Support API (Coordinator/KS class)
- the GMS agent API as supported by the GDMO compiler (MO/MOClassInfo classes)
- the RMIB manager API (RMIBAgent/RMIBManager classes)
- the MSAP raw CMIS manager/agent API
- the Directory Support Service manager/agent API

These are examined separately below, with special emphasis
on the GMS one as it is the most complex.



OBJECT-ORIENTED ASN.1 API
-------------------------

This consists of the Attr class and subclasses. The name Attr for that
class is unfortunate and is retained for historical reasons. A better
name would be AsnType, as this is exactly what this class models.

This API has remained stable since its development stabilised. The only
incremental change to it was the introduction of a _compare() method
which helps implementing filtering in a generic fashion. As already
stated, this was only an incremental addition.

This API is not expected to change. The only cosmetic change envisaged
is to remove any dependencies to CMIS types: currently a few methods return
CMISErrors when an int (OK, NOTOK) would do. These methods are used only by
the generic GMS infrastructure when the GDMO compiler is in place.
Such a cosmetic change should be deferred at least until all
the applications use the GDMO compiler.



COORDINATION SUPPORT API
------------------------

This consists of the Coordinator/KS and Coordinator-derived classes
(ISODECoordinator, XCoordinator, TkCoordinator). This API developed
substantially during the last year within ICM (between versions 3.0 and 3.3)
to support intergrations with other mechanisms (X, TK) and to help
the introduction of co-routine mechanisms (as requested by KTAS).

All the changes are fully incremental, so the current API is fully
backwards compatible to that of version 3.0 .



THE MSAP CMIS API
-----------------

No work related to it took place in ICM but was affected by the MIDAS
security extensions (extra session key parameter to primitives).
It seems that new primitives have been devised instead of adding
to existing ones an extra parameter that could be left empty.

Is this the way to do it? This is a point to be discussed before
the security contribution is finalised.

No further work is envisaged within ICM in this area.



THE RMIB MANAGER ACCESS API
---------------------------

Version 3.0 contained only an embryonic version which supported a high-level
interface to event reporting, hiding the explicit manipulation of
discriminators if so desired. It was extended to cover all the other
primitives in a synchronous fashion first and then in
asynchronous fashion as well. The main classes of this API are
the RMIBAgent/RMIBManager ones.

The current implementation is not backwards compatible to that of version 3.0
as an additional parameter to the RMIBManager callback methods was added
to denote from which RMIBAgent the result/event is coming from.
Extensive documentation already exists and no further work is envisaged.

For information only: the design/implementation of a new MIB browser
is planned in ICM, based on the RMIB API and TCL/TK. This will offer
the full functionality of all the primitives, including scoping, filtering etc.



THE DIRECTORY SUPPORT SERVICE API
---------------------------------

This was developed after version 3.0 to provide location transparency
in a distributed systems platforms manner. The existing implementation
is embryonic but more work is envisaged within ICM this year.
Any more work will be at least aligned with GMD's work in the area
under MIDAS and PREPARE.

The current implementation is fully backwards compatible to that
of version 3.0 and actually reverts to using the isoentities file
if the DSA is not working or if it does not find the right entry.



THE GMS AGENT API
-----------------

The GMS API consists basically of the MO/MOClassInfo classes and has
basically two aspects: methods that enable one to move about and manipulate
MOs in the MIT and polymorphic (i.e. virtual) methods that may be redefined
to implement either behaviour or syntactic aspects that cannot be supported
by the GDMO compiler (e.g. initial values, defaults etc.)

This API is exactly as it was in version 3.0 with the additions
of the createRR, deleteRR and makeRdnAndSuperior methods, as dictated
by the use of the GDMO compiler. These are not yet documented but a new
ICM document will appear soon, documenting the GMS API with respect
to polymorphic methods.

It should be stated, even if obvious, that the
GMS API is mostly orthogonal to the coordination support one but
depends obviously on the MSAP and OO ASN.1 ones. Interaction with loosely
coupled real resources can be effected using KS facilities and asynchronous
models of communication or a synchronous model, possibly supported by
co-routines/threads as in the KTAS extensions.
It is only when asynchronous access to a real resource is needed as a result
of a CMIS request that the GMS API relies on the Coordination support one.

The methods that constitute the polymorphic GMS API are:

int             get (int, int);
CMISErrors      set (CMISModifyOp, int, int, void*);
CMISErrors      action (int, int, void*, void**);
int             createRR (void* = NULLVD);
int             makeRdnAndSuperior (RDN&, MO*&); // static, non virtual
int             deleteRR (void* = NULLVD);
int             buildReport (int, int, PE*);

CMISErrors      refreshSubordinates ();
CMISErrors      refreshSubordinate (RDN);

One should also consider as part of the GMS API the class table in Sma.h .

The following changes to this API are envisaged due to future work.


STANDARD EVENT REPORTING / LOG CONTROL

First, because of the conversion of event reporting and log control
to be fully standard, the buildReport primitive will be:

int             buildReport (int, int, void*&);

Note: For cosmetic but also practical reasons, the action primitive should
      also become

CMISErrors      action (int, int, void*, void*&); // use C++ reference

A more careful examination of notifications and the fact they are essentially
inherited by subclasses is enough to indicate that the current buildReport
method should completely disappear. Enhancing the triggerEvent method with
a void* optional last argument should be enough - we can keep the buildReport
interface for a few more versions for backwards compatibility.

The solution proposed is simple but may result in a few wasting CPU cycles
that fill in the report data structure if the notification function is not
active. A MO or Top method should become available to check for the latter
e.g. Bool activeNotificationFunction () or something simpler.

It should be stated here that the current MIDAS approach for mapping
notification names to specific log records and to encoding functions
in Sma.h should change: a simple text file in the OSIMIS etc directory
should do while encoding the event should be taken care of by software
produced by the GDMO compiler (not implemented now because of lack
of time for the MIDAS end-of-February deadline).


OBJECT MANAGEMENT FUNCTION

No changes to the API are needed but special additional methods
will be provided for the user to be able to trigger objectCreation,
objectDeletion, attributeValueChange and stateChange notifications
when these happen as a result of real resource activity - only
notifications from the CMIS side of things will be automated
(see design document of this function to be circulated soon).


ENHANCEMENTS / RECTIFYING IDENTIFIED PROBLEMS

First, a handle is needed to enable the user to be able to control
the specificError parameter in processing failures. Something like:

int  setSpecificError (AVA*);

Then, the createRR method's return type is int, with NOTOK resulting
in a processingFailure error being returned. A CMISErrors return type should
be more appropriate as errors such as missingAttributeValue or
invalidAttributeValue may be returned. Actually a CMISErrors type is
not entirely adequate as one needs to tell which attribute is wrong.
Enhancing that method's API to provide this functionality is under
investigation.


ASYNCHRONOUS GMS API

Realising this API will result in a major rework of the existing API.
The get, set, action, createRR and deleteRR methods return type should
be extended to include semantics "I will give this information later".
MO class callbacks will be provided to actually tell the GMS that the
information is there / the real resource was modified accordingly.
A design document will be provided soon, explaining the issues and
arising difficulties from such an approach.


LONGER TERM ADDITIONS

The only other changes envisaged for the future in terms of additional
functionality within ICM is the proper support of conditional packages
and possibly of multiple inheritance. There is already a solution for
conditional packages maintaining the current GMS class structure
and requiring only incremental additions. The multiple inheritance issue
presents a much more complex problem and it may probably affect the way
the current APIs are used.

Finally, work on providing CMIS atomicity and transaction support
is also envisaged (MIDAS?). It is unclear what impact the latter will
have on the existing APIs, if at all.

