Indication Provider Semantics Proposal Adrian Schuur Sept2002 by uqu13199

VIEWS: 3 PAGES: 7

									              Indication Provider Semantics Proposal

                                   Adrian Schuur

                                      Sept/2002


Intent of this document
The intent of this document is to describe needed facilities to enable provider writers to
produce advanced query and event providers. Emphasis is specifically on the enablement
Indication providers, though query function implementation will benefit from this as well.

Advanced event monitoring is more than just generating events and letting the CIMOM find
out whether anybody is interested or not. Often, the event provider has to inspect the filter for
domain specific validity and translate the condition into a format that is provided by
underlying support of the operating system or its subsystem, which in most case do not
understand WQL.

Since CIMOMs normally have WQL parsing facilities, the question is how we can reuse these
and eliminate the need for providers to perform WQL select statement parsing (which is not a
trivial exercise).

Furthermore, since the translated filter request might be pushed down to the OS, The provider
should also be informed that a particular filter is of no interest anymore (canceled).

For advanced monitoring providers there are the following requirements:

1) Access to the filtering condition in a normalized and WQL independent format.
2) Notification of new or additional filtering request
3) Notifications of cancellation of filtering request.

Query Normalization
Query normalization has been, and still is, a field of intense study and importance for database
query engines. The most often used technique to normalize sql like statements is the
transformation into either a canonical Disjunction of Conjunctions (Doc), or a canonical
Conjunction of Disjunctions (Cod).

In both cases the filter condition is transformed by grouping the predicates into series of sub
conditions. For Docs the predicates in each sub conditions form an AND relationship, for
Cods a OR relationship is formed. A Doc filter is satisfied when at least one of its sub
conditions evaluates to true (OR). For Cods all sub conditions have to evaluate to true (AND).

Any filter construct, be it WQL or LDAP filters can be translated in either a Doc or a Cod.
After having understood these concepts, it is much easier to handle filter statements and drive
underlying monitoring facilities.

Notification of new filters
This requirement is relatively straight forward, whenever a new filter is introduced because of
a new subscription, a provider callback should be called, with the filter expression as
parameter. It gives the provider a chance to inspect filter and (re-)drive the underlying
monitoring support.

Notifications of filter cancellations
This is opposite of the above. The provider can inform the underlying monitoring support to
cancel or re-adjust specific setting.

API proposal
The following set of pages is copied from the CMPI draft 1.00 document and describe
programming interfaces for Indication Providers. An attempt has been made not to burden
simple monitoring applications, only when access to filter specifics is needed the APIs
described here will be used.

In these sections CMPI uses the term Management Instrumentation (MI) to describe what is
also known as providers. A Management Broker (MB) equates to a CIM Object Manager.
Query and Indication Filtering
The filtering concept for indication support is based on experiences made with Sun’s WBEM
Services and SNIA’s OpenCimom implementations. In essence the filter is representing the
complete select expression as a combination of a list defining the projection and a parse tree
defining the select condition. A select expression is encapsulated by CMPISelectExp.
Similarly for query support a string containing a select condition is passed to the
execQuery() function.
Indication Filtering
For indication filtering there are two distinct reasons for having access to the select condition.
The most obvious one is for filtering indications candidates. This is probably best done by the
MB itself and presumably the filter structure is set up for effective filter processing.

The other reason is to enable an MI supporting indications to inspect and understand the filter
and instrument itself for effective monitoring of the resources it controls. For example, an MI
that monitors the availability of a critical service or daemon in a system could arbitrarily poll
all services in a system regularly, or, intelligently use instrumentation in a system that
natively monitors the availability of services by specifying which service(s) should be
monitored.
 Query
Effective query processing has similar needs, the query process might transform the query
into a native format known by the domain this MI function represents. execQuery() has
one more difficulty, it has to parse and the query string which is not necessarily WQL. In case
a WQL style language is used, a factory function is offered to transform a query string into a
CMPISelectExp.
 Normalized Select Conditions
In order to inspect a select expression MIs can requests the expression to be transformed into
either a conjunction of disjunctions (CoD), or a disjunction of conjunctions (DoC) canonical
form, encapsulated as CMPISelectCond. In both forms all parenthesis and negations are
resolved. As part of this function the projection list can be requested as well.

The CMPISelectCond is a list of CMPISubCond objects. A CMPISubCond object is a
list of CMPIPredicates. Depending on the requests (DoC or CoD) the resulting
predicates of a sub-expression list are either conjunctive (to be AND’ed) for DoC, or
disjunctive (to be OR’ed) for CoD requests. Whereas the resulting expressions of a
normalized select condition are either disjunctive (to be OR’ed) for DoC, or conjunctive (to
be AND’ed) for CoD requests.



Indication Management Instrumentation Signatures

The functions defined here are largely modeled after existing CIMOM implementations
(Sun’s WBEMServices and SNIA’s openCimom).
authorizeFilter
Returns CMPIBoolean using returnData().

   CMPIrc authorizeFilter(
            CMPIIndicationMI* thisMI,
               CMPIContext* invocationContext,
               CMPIResult* resultHandler,
               CMPISelectExp* filter,
               Char *eventType,
               CMPIObjectPath* classPath,
               char *owner);


 mustPoll
This call enables very simple MIs to support indications without providing a complete
indication support implementation. When true is returned, the MB will enumerate the
instances of this MI at regular intervals and apply indication filters.

Returns CMPIBoolean using returnData().

   CMPIrc mustPoll(
            CMPIIndicationMI* thisMI,
            CMPIContext* invocationContext,
            CMPIResult* resultHandler,
            CMPISelectExp* filter,
            char *eventType,
            CMPIObjectPath* classPath);


activateFilter
Returns nothing.

   CMPIrc activateFilter(
            CMPIIndicationMI* thisMI,
            CMPIContext* invocationContext,
            CMPIResult* resultHandler,
            CMPISelectExp* filter,
            char *eventType,
            CMPIObjectPath* classPath,
            int firstActivation);



deActivateFilter
Returns nothing.

   CMPIrc deActivateFilter(
            CMPIIndicationMI* thisMI,
            CMPIContext* invocationContext,
            CMPIResult* resultHandler,
            CMPISelectExp* filter,
            char *eventType,
            CMPIObjectPath* classPath,
            int lastActivation);




CMPIBrokerFT.deliverIndication
Acutal deliverIndication support is optional. Availability of this support is indicated by the
CMPI_MB_Supports_Indication flag in CMPIBrokerFT.classification.
If not supported, CMPI will simulate deliverIndication(), by returning
CMPI_RC_ERR_NOT_SUPPORTED.

   CMPIrc CMPIBrokerFT.deliverIndication(
            CMPIBroker* mbThis,
            CMPIContext *context,
            char *nameSpace,
               CMPIInstance* indication);




Data Type Manipulation Functions

Data Type Manipulation support is used to encapsulate MB specific implementation details.
Support is provided for the following data types: CMPISelectExp, CMPISelectCond,
CMPISubCond , CMPIPredicate .

CMPISelectExp support
CMPIBrokerEncFT.createSelectExp
This call can be issued in to request a select expression string to be converted to a
CMPISellectExp. Optionally the projection will be returned when projection not set to NULL.

   CMPISelectExp*       CMPIBrokerEncFT.createSelectExp(
                       CMPIBroker* mbThis,
                       char* queryString,
                       char* language,
                       CMPIArray* *projection,
                       CMPIrc* rc);



CMPISelectExpFT.evaluate
The filter is applied against an indication instance, true or false is returned depending on
whether the indication meets the conditions or not.

  CMPIBoolean CMPISelectExpFT.evaluate(
                  CMPISelectExp* filterThis,
                  CIMPIInstance indication,
                  CMPIrc* rc);


 CMPISelectExpFT.getDOC
CMPISelecteExp.getDOC support is optional. Availability of this support is indicated by the
CMPI_MB_Supports_QueryNormalization flag in CMPIBrokerFT.classification.
Transforms the filter’s where clause into a canonical Disjunction of Conjunctions form. (OR
of ANDed comparison expressions). This enables handling of the where expression in an
easier manner than going thru a tree form.

  CMPISelectCond* CMPISelectExpFT.getDOC(
                      CMPISelectExp* filterThis,
                      CMPIrc* rc);


CMPISelectExpFT.getCOD
CMPISelecteExp.getCOD support is optional. Availability of this support is indicated by the
CMPI_MB_Supports_QueryNormalization flag in CMPIBrokerFT.classification.

Transforms the filter’s where clause into a canonical Conjunction of Disjunctions form. (AND
of ORed comparison expressions). This enables handling of the where expression in an easier
manner than going thru a tree form.

  CMPISelectCond* CMPISelectExpFT.getCOD(
                  CMPISelectExp* filterThis,
                  CMPIrc* rc);




CMPISelectCond support
CMPISelecteCond support is optional. Availability of this support is indicated by the
CMPI_MB_Supports_QueryNormalization flag in CMPIBrokerFT.classification.

CMPISelectCondFT.getCountAndType
This function returns the number normalized sub-expressions this normalized filter consists
of. In addition when type not equals NULL, it will return the filter type (0: DOC, 1 COD).

   CMPICount CMPISelectCondFT.getCountAndType(
                  CMPISelectCond* condThis,
                  int *type,
                  CMPIrc* rc);


 CMPISelectCondFT.getExpAt
This function treats the list of normalized sub-expressions as an array and enables getting a
particular expressing by index.

  CMPISubCond* CMPISelectCondFT.getExpAt(
                  CMPISelectCond* condThis,
                  int index,
                  CMPIrc* rc);



CMPISubCond support
CMPISubCond support is optional. Availability of this support is indicated by the
CMPI_MB_Supports_QueryNormalization flag in CMPIBrokerFT.classification.

CMPISubCondFT.getCount
This function returns the number predicates this normalized expression consists of.

 CMPICount CMPISubCondFT.getCount(
                       CMPISelectCond* condThis,
                       CMPIrc* rc);


 CMPINormalizeExpFT.getPredicateAt
This function treats the list of predicates as an array and enables getting a particular predicate
by index.

 CMPIPredicate* CMPISubCondFT.getPredicateAt(
                  CMPISubCond* expThis,
                  int index,
                  CMPIrc* rc);


CMPISubCondFT.getPredicate
This function treats the list of predicates as list of named entries and enables getting a
particular predicate by name. The name is the left-hand side of the predicate.

 CMPIPredicate* CMPISubCondFT.getPredicate(
                  CMPISubCond* expThis,
                  Char* name,
                  CMPIrc* rc);




CMPIPredicate support
CMPIPredicate support is optional. Availability of this support is indicated by the
CMPI_MB_Supports_QueryNormalization flag in CMPIBrokerFT.classification.

CMPIPredicate.getValueOpAndNamePtrs
This function returns the details of a predicate. Both type and name parameters can be NULL.

   CMPIrc CMPISubCondFT.getData(
                  CMPIPredicate* predicateThis,
                  CMPType *valueType,
                  CMPIPredOp *op,
                  CMPIString *name,
                  CMPIString *value);


CMPIPredicate.evaluate
This function evaluates a single predicate. It returns either 1: true, 0: maybe true or -1: false.

   int CMPISubCondFT.evaluate(
                  CMPIPredicate* predicateThis,
                  CMPIValue *value,
                  CMPIType valueType,
                  CMPIrc* rc);

								
To top