Sun WBEM SDK Developer's Guide

Generating an Event Indication

Generating an indication for a CIM event involves:

Using the methods in the EventProvider interface to detect when to start and stop delivering indications of CIM event.
Creating an instance of one or more subclasses of the CIM_Indication class to store information about the CIM event that occurred.
Using the deliverEvent method in the ProviderCIMOMHandle interface to deliver indications to the CIM Object Manager.

Methods in the `EventProvider` Interface

An event provider must implement the EventProvider interface. This interface contains methods that the CIM Object Manager uses to notify the provider when a client has subscribed for indications of CIM events, and when a client has cancelled the subscription for CIM events. These methods also allow the provider to indicate whether or not the CIM Object Manager should poll for some event indications and whether or not the provider should authorize the return of an indication to a handler.

The following table lists the methods in the EventProvider interface that must be executed by an event provider.

Table 6–3 Methods in the EventProvider Interface


Method	Description
`activateFilter`	When a client creates a subscription, the CIM Object Manager calls this method to ask the provider to check for CIM events.
`authorizeFilter`	When a client creates a subscription, the CIM Object Manager calls this method to test if the specified filter expression is allowed.
`deActivateFilter`	When a client removes a subscription, the CIM Object Manager calls this method to ask the provider to deactivate the specified event filter.
`mustPoll`	When a client creates a subscription, the CIM Object Manager calls this method to test if the specified filter expression is allowed by the provider, and if it must be polled.

The CIM Object Manager passes values for the following arguments to all methods:

filter — SelectExp that specifies the CIM events for which indications must be generated.
eventType — String that specifies the type of CIM event, which can also be extracted from the FROM clause of the select expression.
classPath — CIMObjectPath that specifies the name of the class for which the event is required.

In addition, the activateFilter method takes the boolean firstActivation, indicating that this is the first filter for this event type. The deActivateFilter method takes the boolean lastActivation, indicating that this is the last filter for this event type.

Creating and Delivering Indications

When a client application subscribes for indications of CIM events by creating an instance of the CIM_IndicationSubscription class, the CIM Object Manager forwards the request to the appropriate provider. If the provider implements the EventProvider interface, the CIM Object Manager notifies the provider when to start sending indications for the specified events by calling the provider's activateFilter method, and it notifies the provider when to stop sending indications for the specified events by calling the provider's deActivateFilter method.

The provider responds to the CIM Object Manager's requests by creating and delivering an indication each time the provider creates, modifies, or deletes an instance. A provider typically defines a flag variable that is set when the CIM Object Manager calls the activateFilter method and cleared when the CIM Object Manager calls the deActivateFilter method. Then in each method that creates, modifies, or deletes an instance, the provider checks the status of the activate filter flag. If the flag is set, the provider creates an indication containing the created CIM instance object and uses the deliverEvent method to return the indication to the CIM Object Manager. If the flag is not set, the provider does not create and deliver an indication of the event.

Authorizations

A provider that handles sensitive data can check authorizations for requests for indications. The provider must implement the Authorizable interface to indicate that it handles authorization checking. The provider also implements the authorizeFilter method. The CIM Object Manager calls this method to test if the owner (UID) of an event handler is authorized to receive the indications that result from evaluating a filter expression. The UID for the owner of the event destination (event handler) can be different than the owner of the client application requesting the filter activation.

CIM Indication Classes

Providers generate indications of CIM events by creating instances of subclasses of the CIM_Indication class.

The following table lists the intrinsic CIM events that a provider should generate.

Table 6–4 CIM Events Indication Classes


Event Class	Description
`CIM_InstCreation`	Notifies when a new instance is created.
`CIM_InstDeletion`	Notifies when an existing instance is deleted.
`CIM_InstModification`	Notifies when an instance is modified. The indication must include a copy of the previous instance whose change generated the indication.

How to Generate an Event Indication

Implement the EventProvider interface. For example:

public class sampleEventProvider implements 
        InstanceProvider EventProvider{

    // Reference for provider to contact the CIM Object Manager
    private ProviderCIMOMHandle cimom;
   }

Execute each of the methods listed in Table 6–3 for each instance indication that the provider handles.

Create an indication listed in Table 6–4 for each create, modify, and delete instance event type. For example, in the createInstance method:

public CIMObjectPath createInstance(CIMObjectPath op, 
        CIMInstance ci)
    throws CIMException {
        CIMObjectpath newop = ip.createInstance(op, ci);
        CIMInstance indication = new CIMInstance();
        indication.setClassName("CIM_InstCreation");
        CIMProperty cp = new CIMProperty();
        cp.setName("SourceInstance");
        cp.setValue(new CIMValue(ci));
        Vector v = new Vector();
        v.addElement(cp);
        indication.setProperties(v);
        ...
    }

Deliver the event indication to the CIM Object Manager. For example:

cimom.deliverEvent(op.getNameSpace(), indication);
        return newop;