A MODEL FOR REALISING OBJECT AND STATE MANAGEMENT IN OSIMIS
-----------------------------------------------------------

This is a short document describing additions in OSIMIS to support
Object and State management. It is noted that those two systems
management functions, together with the qosAlarm and securityViolation
notifications of Alarm/Security Alarm Reporting, are the most fundamental
ones to provide the OSI management power through event reporting.


A General Note on Systems Management Functions first
----------------------------------------------------

Putting the Systems Management Functions into perspective, there exist
three types:

* those that provide generic definitions of MOs or simply attributes,
  actions and notifications - these constitute the majority

* those that provide system definitions i.e. necessary for systems
  management: Event Reporting and Log Control

* those that provide miscellaneous definitions to help realise
  managing and managed systems: Access Control, Security Alarm Reporting
  and Security Audit Trail

In terms of importance, systems ones (Event Report and Log Control) come
first, followed by Object/State management plus the qosAlarm and then
by Metric/Summarisation Objects. These are adequate to do configuration
and performance monitoring. To add intrusive control functions, Access
Control and Security Alarm Reporting/Audit Trial are paramount.

From the rest, Relationship Management is important to allow model
complex relationships that result in lattice structures of managed
object instances and the Scheduling Function to allow schedule generically
the activities of other managed objects. Of course, all the rest are
important in standardising ways of doing common things rather than
leaving specific applications to devise their own model.

In general, the use of standard systems management functions can result
in a surprisingly large number of generic applications i.e. independent
of the specific MIB semantics.


Realising Object and State Management
-------------------------------------

The Object Management function essentially provides a pass-through service
to CMISE from SMASE: this is defined simply for architectural purity
as the typical application layering should be:

                     ------------------------
                     |                      |
                     |      MGMT APPL       |
                     |                      |
                     ------------------------
                     |                      |
                     |        SMASE         |
                     |                      |
                     ------------------------
                     |                      |
                     |        CMISE         |
                     |                      |
                     ------------------------
                     |          |           |
                     |   ACSE   |    ROSE   |
                     |          |           |
                     ------------------------

These are not of importance as the SMASE layer does not really exist
in OSIMIS. What may exist are higher level access APIs which do not
necessarily implement the various SMASE "directives". As an example,
the RMIB Object-Oriented access API provides facilities to manipulate
event reporting which hide the underlying handling of discriminators.

In addition to those pass-through services, Object Management defines
three notifications of fundamental importance:

* objectCreation
* objectDeletion
* attributeValueChange

State management defines a few generic state attributes, provides a model
for transitions between those states and also provides an important
notification:

* stateChange

The latter has the same syntax as attributeValueChange but more specific
semantics.

OSIMIS already implements syntaxes for those notifications and also
the most important of the state attributes:

* operationalState
* administrativeState
* usageState
* availabilityStatus

The proposed realisation intends to automate the emission of those
notifications as explained below.


The Realisation Model
---------------------

The rest of this discussion will assume the current model for notification
handling, with a triggerEvent method called to trigger a notification and
a buildReport method supplied by the MO implementor. The model is
general enough so that when in the future a different notification mechanism
is implemented (see THE OSIMIS APIs document), the proposed API will not
change.

The general idea behind this model is to take automatic control of the
notifications when a MO is being created/deleted modified through the
CMIS interface and provide a friendly handle to trigger those notifications
when the same happens due to activity in the underlying resource.

Realising those notifications when something is modified from the CMIS side
is fairly easy as the GMS needs only to know two things:

1. if the particular instance supports that notification
2. if the modified attribute is a state one

Finding out about the first is pretty easy as the GMS has access to all
the meta-class information for that particular instance (pointers to
MOClassInfo instances). Regarding the type of the modified attribute,
it is still easy as the generic ASN.1 type class Attr offers a polymorphic
getSyntax() method which returns an ASCII string. If the last part of
that string is "State" or "Status" and the attribute supports the stateChange
notification, the latter will be emitted. Though obvious, it should be stated
that those notifications will be emitted only after the MO is properly
created/deleted/modified without any error.
This mechanism will be totally transparent to MO implementors.


Regarding realisation from the real-resource part, special handles
i.e. methods will be given to the implementor to trigger:

int  triggerObjectCreation ();
int  triggerObjectDeletion ();
int  triggerAttrValueChange (int classLevel, int attrId,
						void* prevValue = NULLVD);
int  triggerStateChange (int classLevel, int attrId,
						void* prevValue = NULLVD);

Regarding the realisation, those methods will use the
triggerEvent as follows (an example):

    // set some protected IVs of the Top class to tell it
    // which attribute changed
    // ...

    // trigger the notification through the current GMS I/F
    triggerEvent(I_attributeValueChange, Top::_level)

The Top class buildReport() will implement code to cope
with those generic notifications. Later on, when buildReport will
be abolished, the current interface will stay exactly as is.

It is reminded that the proposal for the future GMS event reporting
API (when not specialised as above) is:

    if (activeNotificationFunction())
        triggerEvent( I_myNotif, prepareNotifStruct(...) )

This means that the future handle will be implemented through the methods:

Bool  activeNotificationFunction();
int   triggerEvent (int notifId, void* notifInfo);



APPENDIX: AUTOMATING THE QOS ALARM EMISSION

It would also be possible to automate the qosAlarm emission from threshold
attributes and the attributeValueChange emission from tide-marks as a result
of the real resource operation. All that needs to be done is to pass
information on the containing object instance when a threshold or tide-mark
attribute is created, e.g.

    _attrs[I_nUsers]          = Gauge;
    _attrs[I_nUsersThreshold] = GaugeThreshold(this);
    _attrs[I_nUsersTideMark]  = TideMark(this);

Note that the above code will be produced by the GDMO compiler. When later
the gauge is updated by the behavioural part of the code supplied by the
MO implementor, the notifications will be emitted automatically.

Though this is possible, the implementation of attributes and managed objects
will become convoluted as they both need to know of each other. In programmatic
terms this is not a problem as forward referencing can be used.

The issue though is that there is no real gain in this work since the
existence of the metric objects obviates the use of thresholds and
tide-marks in the information model and the metric objects are
implemented once and re-used.

