pegasus/src/Pegasus/Provider/CIMIndicationProvider.h - diff

Return to CIMIndicationProvider.h CVS log

Up to [Pegasus] / pegasus / src / Pegasus / Provider

Diff for /pegasus/src/Pegasus/Provider/CIMIndicationProvider.h between version 1.2 and 1.3

version 1.2, 2002/01/07 19:40:57

version 1.3, 2002/01/07 19:57:07

Line 40

PEGASUS_NAMESPACE_BEGIN

/**

REVIEW: In CIMClient interfaces, we fully specify a class name using two

This class defines the set of methods implemented by an indication provider. A providers that derives

arguments:

from this class must implement all methods. The minimal method implementation simply throw the

NotSupported exception.

const String& nameSpace

const String& className

In general, the CIMOM classifies the provider as asynchronous or synchronous depending on the methods

implemented by the provider. An asynchronous indication provider supports provideIndication,

In the provideIndication() method below, these two are represented like

updateIndication, and cancelIndication. A synchronous provider supports checkIndication. A provider

this:

can support both interfaces.

const CIMReference& classReference

The CIMOM first attempts to call provideIndication, given at least once subscription exists.

If the provider does not support the method, the CIMOM assumes the provider generates indications

The goal is to represent these:

synchronously using checkIndication. If the provider does not support any of the methods of this

interface, is not considered an indication provider and an error is generated.

namespace name

class name.

But using this type leaves open the possibility (ambiguity) of specifying

these components of CIMReference as well:

host name

keybinding pairs

I think there should be consistency between the CIMClient and

CIMProvider interfaces? Further, I don't think using CIMReference is an

option for the client, since it would allow the client to pass host names

and keybinding pairs (which could be detected until run time). Further,

it is incomptible with the specification.

REVIEW: WITHIN clauses not supported by WQL.

REVIEW: Get clarification on use of handler.complete() method.

REVIEW: How do handlers get cleaned up?

REVIEW: What do you do with the old handler (you may have cached) when

you are passed a new handler by any of the methods. Why not just

have one handler for the whole class rather than passing a new

handler each time one of the methods of this class is called?

REVIEW: Why does cancelIndication() need a handler? Why do any of the

methods except for provideIndication() need a handler?

REVIEW: Note that Microsoft's WMI only passes the handler (sink) to the

provideEvents() method.

REVIEW: Should we split this class into two distinct interfaces (since

it would appear that polled v.s. non-polled is a development time

decision and therefore a compile time decission). It may be cleaner

to resolve polled v.s. non-polled via provider registration.

REVIEW: Is an asynchronous indication provider asynchronous with respect

to all indications it might generate or can it be synchronous for some

and aysynchronous for others? Does synchronicity pertain to the each

class or just to the provider?

class PEGASUS_PROVIDER_LINKAGE CIMIndicationProvider : public virtual CIMBaseProvider

{

public:

CIMIndicationProvider(void);

virtual ~CIMIndicationProvider(void);

/**

This class defines the set of methods implemented by an indication

Instructs the provider to begin generating indications of the type specified in

provider.

the classReference parameter.

A provider that derives from this class must implement all methods. The

This method is invoked when the CIMOM has at least one active subscription that

minimal method implementation simply throws the NotSupported exception.

links the indication type with a handler. Once this method has been invoked, changes

to the active subscriptions are communicated via the updateIndication method. The

cancelIndication method is invoked when all active subscriptions have been removed.

In general, the CIMOM classifies the provider as asynchronous or

For example, assume that two subscriptions exist that point to the following filters.

synchronous depending on the methods implemented by the provider. An

asynchronous indication provider supports these methods:

<pre>

provideIndication()

<code>"SELECT Property1 FROM Sample_Indication WHERE Property1="foo" WITHIN 30000"</code>

updateIndication()

<code>"SELECT Property2 FROM Sample_Indication WHERE Property1="bar" WITHIN 60000"</code>

cancelIndication()

</pre>

Whereas, a synchronous provider supports this method:

The contents of the paramters (in string form) to this method might look like the following.

<pre>

checkIndication()

<code>classReference = "localhost/root/cimv2:Sample_Indication"</code>

<code>minimumInterval = "00000000003000.000000:000" (30 minutes)</code>

<code>maximumInterval = "00000000006000.000000:000" (60 minutes)</code>

<code>propertyList = "Property1", "Property2"</code>

</pre>

The CIMOM first attempts to call provideIndication(), given at least once

NOTE: The WHERE clause is not evaluated by the provider. Providers generate indications according

subscription exists. If the provider does not support this method, the

to predefined events and are not specified by indication filters. The existence of a filter simply

CIMOM assumes the provider generates indications synchronously using

notifies a provider that some client is interested in indications of a specified type. The filters

checkIndication(). If the provider does not support any of the methods of

specify the criteria for indication delivery, not creation.

this interface, it is not considered an indication provider and an error

is generated.

class PEGASUS_PROVIDER_LINKAGE CIMIndicationProvider

: public virtual CIMBaseProvider

{

public:

CIMIndicationProvider(void);

virtual ~CIMIndicationProvider(void);

Assuming the above parameters, the provider should attach to some resource and begin monitoring

every 30 seconds (optimally). When some predefined event occurs (a circumstance that merits an

indication), the provider should create and indication containing the properties listed in the

propertyList parameter. The provider then delivers the indication to the handler associated with the

indication type and continues monitoring. A call to updateIndication means that the indication

generation information (minimumInterval, maximumInterval, and propertyList) has changed, and a call

to cancelIndication notifies the provider to discontinue monitoring (no subscriptions exist).

/**

NOTE: Under normal circumstances the provider should not call handler.complete() in this method;

Instructs the provider to begin generating indications of the type

it should be called in cancelIndication. Calling this method implies no more results are available

specified in the classReference parameter.

and will effectively disable result forwarding for the handler.

This method is invoked when the CIMOM has at least one active

@param contex contains security and locale information relevant for the lifetime

subscription that links the indication type with a handler. Once

of this operation.

this method has been invoked, changes to the active subscriptions

are communicated via the updateIndication() method. The

cancelIndication() method is invoked when all active subscriptions

have been removed.

For example, assume that two subscriptions exist that point to the

following filters.

<pre>

SELECT Property1 FROM Sample_Indication

WHERE Property1="foo" WITHIN 30000"

SELECT Property2 FROM Sample_Indication

WHERE Property1="bar" WITHIN 60000"

</pre>

The contents of the paramters (in string form) to this method might

@param classReference provides a fully qualified reference of the indication

look like the following.

class of interest.

<pre>

@param minimumInterval specifies the minimum requested indication delivery frequency. This is an

classReference = "localhost/root/cimv2:Sample_Indication"

optional parameter where an interval of zero ("0000000000.000000:000") implies not specified.

minimumInterval = "00000000003000.000000:000" (30 minutes)

maximumInterval = "00000000006000.000000:000" (60 minutes)

propertyList = "Property1", "Property2"

</pre>

NOTE: The WHERE clause is not evaluated by the provider. Providers

@param maximumInterval specifies the maximum requested indication delivery frequency. This is an

generate indications according to predefined events and are not

optional parameter where an interval of zero ("0000000000.000000:000") implies not specified.

specified by indication filters. The existence of a filter simply

notifies a provider that some client is interested in indications

of a specified type. The filters specify the criteria for indication

delivery, not creation. In other words, the filter is resolved by

CIMOM, not the provider.

Assuming the above parameters, the provider should attach to some

resource and begin monitoring every 30 seconds (optimally). When

some predefined event occurs (a circumstance that merits an

indication), the provider should create an indication containing

the properties listed in the propertyList parameter. The provider

then delivers the indication to the handler associated with the

indication type and continues monitoring. A call to

updateIndication() means that the indication generation information

(minimumInterval, maximumInterval, and propertyList) has changed,

and a call to cancelIndication() notifies the provider to

discontinue monitoring (no subscriptions exist).

NOTE: Under normal circumstances the provider should not call

handler.complete() in this method; it should be called in

cancelIndication(). Calling this method implies no more results are

available and will effectively disable result forwarding for the

handler.

@param contex contains security and locale information relevant

for the lifetime of this operation.

@param classReference provides a fully qualified reference of the

indication class of interest.

@param minimumInterval specifies the minimum requested indication

delivery frequency. This is an optional parameter where an

interval of zero ("0000000000.000000:000") implies not

specified.

@param maximumInterval specifies the maximum requested indication

delivery frequency. This is an optional parameter where an

interval of zero ("0000000000.000000:000") implies not

specified.

@param propertyList specifies the properties of interest within the

@param propertyList specifies the properties of interest within the class

class identified by the classReference parameter.

identified by the classReference parameter.

@param handler asynchronusly processes the results of this

@param handler asynchronusly processes the results of this operation.

operation.

@exception NotImplemented

@exception InvalidArgument

Line 228

Line 132

ResponseHandler<CIMIndication> & handler) = 0;

/**

Instructs the provider to update the information regarding the

Instructs the provider update the information regarding the indication of the type specified

indication of the type specified in the classReference parameter.

in the classReference parameter.

Once the provideIndication method has been called, the CIMOM

Once the provideIndication method has been called, the CIMOM communicated significant changes

communicates significant changes about the indication generatation

to the indication generatation information (minimumInterval, maximumInterval, and propertyList)

information (minimumInterval, maximumInterval, and propertyList)

via this method.

Assuming provideIndications() was called with the parameters in the

Assuming provideIndications was called with the parameters in the sample above, and a new

sample above, and a new subscription is created for the following

subscription is created for the following filter.

filter.

<pre>

SELECT Property1, Property3 FROM Sample_Indication

<code>"SELECT Property1, Property3 FROM Sample_Indication WHERE Property1="bar" WITHIN 60000"</code>

WHERE Property1="bar" WITHIN 60000

</pre>

The contents of the paramters (in string form) to this method might

The contents of the paramters (in string form) to this method might look like the following.

look like the following.

<pre>

classReference = "localhost/root/cimv2:Sample_Indication"

<code>classReference = "localhost/root/cimv2:Sample_Indication"</code>

minimumInterval = "00000000003000.000000:000" (30 minutes)

<code>minimumInterval = "00000000003000.000000:000" (30 minutes)</code>

maximumInterval = "00000000006000.000000:000" (60 minutes)

<code>maximumInterval = "00000000006000.000000:000" (60 minutes)</code>

propertyList = "Property1", "Property2", "Property3"

<code>propertyList = "Property1", "Property2", "Property3"</code>

</pre>

NOTE: The WHERE clause is not evaluated by the provider. Providers

NOTE: The WHERE clause is not evaluated by the provider. Providers generate indications according

generate indications according to predefined events and are not

to predefined events and are not specified by indication filters. The existence of a filter simply

specified by indication filters. The existence of a filter simply

notifies a provider that some client is interested in indications of a specified type. The filters

notifies a provider that some client is interested in indications

specify the criteria for indication delivery, not creation.

of a specified type. The filters specify the criteria for

indication delivery, not creation. In other words, indications may

Assuming the above parameters, the provider should adjust add Property3 to any indications

be created by this provider and later discarded by the CIMOM

generated from this point forward.

(while evaluating the filter).

New subscriptions associated to existing filters do not result in calls to the provider.

Assuming the above parameters, the provider should adjust add

Property3 to any indications generated from this point forward.

NOTE: Under normal circumstances the provider should not call handler.complete() in this method;

it should be called in cancelIndication. Calling this method implies no more results are available

Subsequent subscriptions associated with existing filters do not

and will effectively disable result forwarding for the handler.

result in calls to the provider.

NOTE: Under normal circumstances the provider should not call

handler.complete() in this method; it should be called in

cancelIndication(). Calling the handler.complete() method

implies no more results are available and will effectively

disable result forwarding for the handler.

@param context contains security and locale information

relevant for the lifetime of this operation.

@param classReference provides a fully qualified reference of the

@param classReference provides a fully qualified reference of the indication

indication class of interest.

class of interest.

@param minimumInterval specifies the minimum requested indication delivery frequency. This is an

optional parameter where an interval of zero ("0000000000.000000:000") implies not specified.

@param minimumInterval specifies the minimum requested indication

@param maximumInterval specifies the maximum requested indication delivery frequency. This is an

delivery frequency. This is an optional parameter where an

optional parameter where an interval of zero ("0000000000.000000:000") implies not specified.

interval of zero ("0000000000.000000:000") implies not

specified.

@param maximumInterval specifies the maximum requested indication

delivery frequency. This is an optional parameter where an

interval of zero ("0000000000.000000:000") implies not

specified.

@param propertyList specifies the properties of interest within

@param propertyList specifies the properties of interest within the class

the class identified by the classReference parameter.

identified by the classReference parameter.

@param handler asynchronusly processes the results of this

@param handler asynchronusly processes the results of this operation.

operation.

@exception NotImplemented

@exception InvalidArgument

Line 310

Line 198

ResponseHandler<CIMIndication> & handler) = 0;

/**

Instructs the provider to stop providing indications of the type

Instructs the provider to stop providing indications of the type specified in the

specified in the classReference parameter.

classReference parameter.

This method is called after provideIndication() and implies that

This method is called after provideIndication and implies that either no

either no subscriptions exist or that the CIMOM is shutting down.

subscriptions exist or that the CIMOM is shutting down. The provider should release

The provider should release resources associated with generating

resources associated with generating indications of the type specified in

indications of the type specified in classReference. If a

classReference. If a subscription is later created, provideIndications will be

subscription is later created, provideIndications will be called

called again.

again.

Upon completion of this method, the provider should call handler.complete (the CIMOM

Upon completion of this method, the provider should call

will call it, if necessary) at which point the handle is no longer guaranteed to be

handler.complete (the CIMOM will call it, if necessary) at which

valid. Usage of the handle after complete is undefined.

point the handle is no longer guaranteed to be valid. Usage of the

handle after complete is undefined.

@param context contains security and locale information relevant

@param context contains security and locale information relevant for the lifetime

for the lifetime of this operation.

of this operation.

@param classReference provides a fully qualified reference of the

@param classReference provides a fully qualified reference of the indication

indication class of interest.

class of interest.

@param handler asynchronusly processes the results of this

@param handler asynchronusly processes the results of this operation.

operation.

@exception NotImplemented

@exception InvalidArgument

Line 343

Line 228

ResponseHandler<CIMIndication> & handler) = 0;

/**

Instructs the provider to check the managed resource and

Instructs the provider to check the managed resource and immediately generate indications,

immediately generate indications, if necessary, and complete.

if necessary, and complete.

Note that this method is used (to the exclusion of the others) for

This method is called periodically by the CIMOM to allow the provider to create indications

synchronous ("polled") indications.

without actively monitoring a resource. Because the method executes on the CIMOM's thread,

the provider should attempt to complete the method prompty to allow the CIMOM to service

This method is called periodically by the CIMOM to allow the

other providers.

provider to create indications without actively monitoring a

resource.

Note the CIMOM frequency wherewith the CIMOM invokes this method

is related to the "intervals" defined by the filter.

Because the method executes on the CIMOM's thread, the provider

should attempt to complete the method prompty to allow the CIMOM

to service other providers.

REVIEW: the above statement we hope is in error. This method

must not be invoked on the CIMOM's thread.

@param context contains security and locale information

relevant for the lifetime of this operation.

@param classReference provides a fully qualified reference of the

@param classReference provides a fully qualified reference of the indication

indication class of interest.

class of interest.

@param The propertyList specifies the properties of interest

@param The propertyList specifies the properties of interest within the class

within the class identified by the classReference parameter.

identified by the classReference parameter.

@param handler asynchronusly processes the results of this

@param handler asynchronusly processes the results of this operation.

operation.

@exception NotImplemented

@exception InvalidArgument

Note the absense of interval parameters as these are processed by

the CIMOM itself.

virtual void checkIndication(

const OperationContext & context,

Line 390

Line 259

PEGASUS_NAMESPACE_END

#endif /* Pegasus_CIMIndicationProvider_h */

#endif

Legend:

Removed from v.1.2
changed lines
	Added in v.1.3

No CVS admin address has been configured