indicationservice.h

Pegasus is an open-source implementationof the DMTF CIM and WBEM standards. It is designed to be por

//%2006////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
// Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
// Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
// IBM Corp.; EMC Corporation, The Open Group.
// Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
// IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
// Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
// EMC Corporation; VERITAS Software Corporation; The Open Group.
// Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
// EMC Corporation; Symantec Corporation; The Open Group.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to
// deal in the Software without restriction, including without limitation the
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
// sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
// 
// THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
// ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
// "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
// LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
// PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
// ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
//
//==============================================================================
//
// Author: Nitin Upasani, Hewlett-Packard Company ([e-mail])
//
// Modified By:  Carol Ann Krug Graves, Hewlett-Packard Company
//                   ([e-mail])
//               Ben Heilbronn, Hewlett-Packard Company ([e-mail])
//               Roger Kumpf, Hewlett-Packard Company ([e-mail])
//               Yi Zhou, Hewlett-Packard Company ([e-mail])
//
//%/////////////////////////////////////////////////////////////////////////////

#ifndef Pegasus_IndicationService_h
#define Pegasus_IndicationService_h

#include <Pegasus/Common/Config.h>
#include <Pegasus/Common/MessageQueueService.h>
#include <Pegasus/Common/CIMMessage.h>
#include <Pegasus/Common/AcceptLanguageList.h>
#include <Pegasus/Common/ContentLanguageList.h>
#include <Pegasus/Server/ProviderRegistrationManager/ProviderRegistrationManager.h>
#include <Pegasus/Server/Linkage.h>
#include <Pegasus/Query/QueryExpression/QueryExpression.h>

#include "ProviderClassList.h"
#include "IndicationOperationAggregate.h"

PEGASUS_NAMESPACE_BEGIN

class SubscriptionRepository;
class SubscriptionTable;

/**

    IndicationService class is the service that serves the
    Indication Subscription, Indication Filter, and Indication Handler
    classes, and processes indications.

    @author  Hewlett-Packard Company

 */

class PEGASUS_SERVER_LINKAGE IndicationService : public MessageQueueService
{
public:

    /**
        Constructs an IndicationSubscription instance and initializes instance
        variables.
     */
    IndicationService (
        CIMRepository * repository,
        ProviderRegistrationManager * providerRegManager);

    virtual ~IndicationService(void);

    void handleEnqueue(Message* message);

    virtual void handleEnqueue(void);

    virtual void _handle_async_request(AsyncRequest *req);

    /**
        Gets a String containing the Provider Name, for use in a log message to
        identify the provider.

        @param   provider              provider instance

        @return  String containing the Provider Name
     */
    static String getProviderLogString
        (CIMInstance & provider);

    AtomicInt dienow;

    /**
        Operation types for the NotifyProviderRegistration message
     */
    enum Operation {OP_CREATE = 1, OP_DELETE = 2, OP_MODIFY = 3};

    static Mutex _mutex;

private:

    void _initialize (void);

    void _terminate (void);

    void _handleGetInstanceRequest(const Message * message);

    void _handleEnumerateInstancesRequest(const Message * message);

    void _handleEnumerateInstanceNamesRequest(const Message * message);

    void _handleCreateInstanceRequest(const Message * message);

    void _handleModifyInstanceRequest(const Message * message);

    void _handleDeleteInstanceRequest(const Message * message);

    void _handleProcessIndicationRequest(const Message * message);

    /**
        Asynchronous callback function for _handleProcessIndicationRequest.
        The response from the Handler is checked, and if it is not success, the
        subscription's On Fatal Error Policy is implemented.

        @param  operation            shared data structure that controls message
                                         processing
        @param  destination          target queue of completion callback
        @param  userParameter        user parameter for callback processing
     */
    static void _handleIndicationCallBack (
        AsyncOpNode * operation,
        MessageQueue * destination,
        void * userParameter);

    /**
	Notifies the Indication Service that a change in provider registration
	has occurred.  The Indication Service retrieves the subscriptions
	affected by the registration change, sends the appropriate Create,
        Modify, and/or Delete requests to the provider, and sends an alert to
        handler instances of subscriptions that are no longer served by the
        provider.
    */
    void _handleNotifyProviderRegistrationRequest(const Message * message);

    /**
        Notifies the Indication Service that a provider has been disabled.
        The Indication Service retrieves the subscriptions served by the
        disabled provider, and logs a message for each subscription that is no
        longer served by the provider.
     */
    void _handleNotifyProviderTerminationRequest(const Message * message);

    /**
        Notifies the Indication Service that a provider has been enabled.
        The Indication Service retrieves the subscriptions that can be served
        by the enabled provider, sends Create Subscription and Enable
        Indications requests to the provider, and logs a message for each
        subscription that is now served by the provider.
     */
    void _handleNotifyProviderEnableRequest (const Message * message);

    /**
        Notifies the Indication Service that failure of a provider module that
        included at least one indication provider has been detected.
        The Indication Service retrieves the subscriptions served by providers
        in the failed module.  The Indication Service returns in the response
        the number of affected subscriptions, so the sender of the request
        knows if any subscriptions were affected.
     */
    void _handleNotifyProviderFailRequest (Message * message);

    /**
        Determines if it is legal to create an instance.
        Checks for existence of all key and required properties.  Checks that
        properties that MUST NOT exist (based on values of other properties),
        do not exist.  For any property that has a default value, if it does
        not exist, adds the property with the default value.

        @param   instance              instance to be created
        @param   nameSpace             namespace for instance to be created

        @exception   CIM_ERR_INVALID_PARAMETER  if instance is invalid
        @exception   CIM_ERR_NOT_SUPPORTED      if the specified class is not
                                                supported

        @return  True, if the instance can be created;
                 Otherwise throws an exception
     */
    Boolean _canCreate (
        CIMInstance & instance,
        const CIMNamespaceName & nameSpace);

    /**
        Validates the specified required property in the instance.
        If the property does not exist, or has a null value, or is not of the
        expected type, an exception is thrown, using the specified message.

        This function is called by the _canCreate function, and is used to
        validate the  Filter and Handler properties in Subscription instances,
        the Name, Query and Query Language properties in
        Filter instances, the Name and Destination
        properties in CIMXML Handler instances, and the Name,
        Trap Destination, and SNMP Version properties in SNMP Mapper instances.

        @param   instance              instance to be validated
        @param   propertyName          name of property to be validated
        @param   expectedType          expected CIMType of property value
        @param   message               message to be used in exception
	@param   isArray               indicates whether the validated
				       property is array

        @exception   CIM_ERR_INVALID_PARAMETER  if required property is missing
                                                or null
     */
    void _checkRequiredProperty (
        CIMInstance & instance,
        const CIMName & propertyName,
        const CIMType expectedType,
        const String & message,
	const Boolean isArray = false);

    /**
        Validates the specified Uint16 (non-array) property and its
        corresponding String (non-array) Other___ property in the instance.
        If the property does not exist, it is added with the default value.
        If the property exists, but its value is NULL, its value is set to
        the default value.
        If the value of the property is Other, but the corresponding Other___
        property either does not exist, has a value of NULL, or is not of the
        correct type, an exception is thrown.
        If the value of the property is not Other, but the corresponding
        Other___ property exists and has a non-NULL value, an exception is
        thrown.
        If the value of the property is not a supported value, an exception is
        thrown.
        This function is called by the _canCreate function, and is used to
        validate the following pairs of properties in Subscription or Handler
        instances: Subscription State, Other Subscription State, Repeat
        Notification Policy, Other Repeat Notification Policy, On Fatal Error
        Policy, Other On Fatal Error Policy, Persistence Type, Other
        Persistence Type.

        @param   instance              instance to be validated
        @param   propertyName          name of property to be validated
        @param   otherPropertyName     name of Other___ property to be validated
        @param   defaultValue          default value for property
        @param   otherValue            "Other" value for property
        @param   validValues           set of valid values for property
        @param   supportedValues       set of supported values for property

        @exception   CIM_ERR_INVALID_PARAMETER  if value of property or Other___
                                                property is invalid
     */
    void _checkPropertyWithOther (
        CIMInstance & instance,
        const CIMName & propertyName,
        const CIMName & otherPropertyName,
        const Uint16 defaultValue,
        const Uint16 otherValue,
        const Array <Uint16> & validValues,
        const Array <Uint16> & supportedValues);

    /**
        Validates the specified property in the instance.
        If the property does not exist, it is added with the default value.
        If the property exists, but its value is NULL, its value is set to
        the default value.
        This function is called by the _canCreate function, and is used to
        validate the Source Namespace property in Filter instances.
        This function is also called by the _initOrValidateStringProperty
        function to validate the CreationClassName, SystemName, and
        SystemCreationClassName key properties in Filter and Handler instances.

        Note: currently all properties validated by this function are of type
        String.  To use this function in the future with properties of other
        types, a type parameter would need to be added, and the default value
        would need to be passed as a CIMValue instead of a String.

        Note: currently all properties validated by this function are non-array
        properties.  To use this function in the future with both array and
        non-array properties, a Boolean isArray parameter would need to be
        added.

        @param   instance              instance to be validated
        @param   propertyName          name of property to be validated
        @param   defaultValue          default value for property

        @return  the value of the property
     */
    String _checkPropertyWithDefault (
        CIMInstance & instance,
        const CIMName & propertyName,
        const String & defaultValue);

    /**
        Validates the specified property in the instance.
        If the property does not exist, it is added with the default value.
        If the property exists, but its value is NULL, its value is set to
        the default value.
        If the property exists and has a non-NULL value, its value is validated
        against the default (expected) value.  If the value is invalid, an
        exception is thrown.