operationcontext.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.
//
//==============================================================================
//
//%/////////////////////////////////////////////////////////////////////////////

#ifndef Pegasus_OperationContext_h
#define Pegasus_OperationContext_h

#include <Pegasus/Common/Config.h>
#include <Pegasus/Common/Exception.h>
#include <Pegasus/Common/CIMInstance.h>
#include <Pegasus/Common/AcceptLanguageList.h>
#include <Pegasus/Common/ContentLanguageList.h>
#include <Pegasus/Common/Linkage.h>

PEGASUS_NAMESPACE_BEGIN

class OperationContextRep;

/**
    An OperationContext object holds information about the context of an
    operation, using various Container classes.  The Container subclasses
    define the set of information that may be available in the
    OperationContext.
*/
class PEGASUS_COMMON_LINKAGE OperationContext
{
public:

    /**
        A Container subclass object holds a piece of context information
        for an operation.
    */
    class PEGASUS_COMMON_LINKAGE Container
    {
    public:

        /**
            Destructs the Container.
        */
        virtual ~Container();

        /**
            Returns the unique name for a Container type.
            @return The String name of the Container type.
        */
        virtual String getName() const = 0;

        /**
            Makes a copy of the Container object.  The caller is responsible 
            for cleaning up the copy by calling destroy() method.
            @return A pointer to the new Container object.
        */
        virtual Container* clone() const = 0;

        /**
            Cleans up a Container object that was created by the clone()
            method.
        */
        virtual void destroy() = 0;
    };

    /**
        Constructs an empty OperationContext object.
    */
    OperationContext();

    /**
        Constructs a copy of an OperationContext object.  The newly
        constructed OperationContext object is independent from the source
        object.
        @param context The OperationContext object to copy.
    */
    OperationContext(const OperationContext& context);

    /**
        Destructs the OperationContext.
    */
    virtual ~OperationContext();

    /**
        Assigns the value of the specified OperationContext object to this
        OperationContext.  As a result, this OperationContext object will
        contain the same set of Containers as in the specified object.
        @param context The OperationContext object to copy.
    */
    OperationContext& operator=(const OperationContext& context);

    /**
        Removes all the Containers from the OperationContext.
    */
    void clear();

    /**
        Retrieves the specified Container object from the OperationContext.
        @param containerName The name of the Container type to retrieve.
        @return A reference to the specified Container object.
        @exception Exception if the OperationContext does not contain the
        specified Container type.
    */
    const Container& get(const String& containerName) const;

    /**
        Replaces an OperationContext Container with the specified Container
        object of the same type.
        @param container The Container to set in the OperationContext.
        @exception Exception if the OperationContext does not contain the
        specified Container type.
    */
    void set(const Container& container);

    /**
        Inserts a Container into the OperationContext.
        @param container The Container to insert into the OperationContext.
        @exception Exception if the OperationContext already contains a
        Container of this type.
    */
    void insert(const Container& container);

    /**
        Removes a Container from the OperationContext.
        @param containerName The name of the Container type to remove from
        the OperationContext.
        @exception Exception if the OperationContext does not contain the
        specified Container type.
    */
    void remove(const String& containerName);

protected:
    OperationContextRep* _rep;
};


class IdentityContainerRep;

/**
    An IdentityContainer object holds the identity of a user associated with
    an operation.  For example, a provider must use this Container to
    determine whether to perform an operation on the behalf of the requesting
    user.
*/
class PEGASUS_COMMON_LINKAGE IdentityContainer
    : virtual public OperationContext::Container
{
public:
    /**
        The unique name for this container type.
    */
    static const String NAME;

    /**
        Constructs an IdentityContainer object from the specified Container.
        @param container The Container object to copy.
        @exception DynamicCastFailedException If the specified Container
        object is not an IdentityContainer object.
    */
    IdentityContainer(const OperationContext::Container& container);

    /**
        Constructs a copy of the specified IdentityContainer.
        @param container The IdentityContainer object to copy.
    */
    IdentityContainer(const IdentityContainer& container);

    /**
        Constructs an IdentityContainer with a specified user name.
        @param userName A String user name for this identity.
    */
    IdentityContainer(const String& userName);

    /**
        Destructs the IdentityContainer.
    */
    virtual ~IdentityContainer();

    /**
        Assigns the value of the specified IdentityContainer object to this
        object.
        @param container The IdentityContainer object to copy.
    */
    IdentityContainer& operator=(const IdentityContainer& container);

    /**
        Returns the unique name for this Container type.
        @return The String name of the Container type.
    */
    virtual String getName() const;

    /**
        Makes a copy of this IdentityContainer object.  The caller is
        responsible for cleaning up the copy by calling destroy() method.
        @return A pointer to the new Container object.
    */
    virtual OperationContext::Container* clone() const;

    /**
        Cleans up an IdentityContainer object that was created by the
        clone() method.
    */
    virtual void destroy();

    /**
        Gets the user name from the IdentityContainer object.
        @return A String containing the user name identity.
    */
    String getUserName() const;

protected:
    IdentityContainerRep* _rep;

private:
    IdentityContainer();    // Unimplemented
};


class SubscriptionInstanceContainerRep;

/**
    A SubscriptionInstanceContainer object holds a CIMInstance associated
    with an indication subscription.
*/
class PEGASUS_COMMON_LINKAGE SubscriptionInstanceContainer
    : virtual public OperationContext::Container
{
public:
    /**
        The unique name for this container type.
    */
    static const String NAME;

    /**
        Constructs a SubscriptionInstanceContainer object from the
        specified Container.
        @param container The Container object to copy.
        @exception DynamicCastFailedException If the specified Container
        object is not a SubscriptionInstanceContainer object.
    */
    SubscriptionInstanceContainer(
        const OperationContext::Container& container);

    /**
        Constructs a copy of the specified SubscriptionInstanceContainer.
        @param container The SubscriptionInstanceContainer object to copy.
    */
    SubscriptionInstanceContainer(
        const SubscriptionInstanceContainer& container);

    /**
        Constructs a SubscriptionInstanceContainer with the specified
        subscription instance.
        @param subscriptionInstance The subscription instance to be held by
        this Container.
    */
    SubscriptionInstanceContainer(const CIMInstance& subscriptionInstance);

    /**
        Destructs the SubscriptionInstanceContainer.
    */
    virtual ~SubscriptionInstanceContainer();

    /**
        Assigns the value of the specified SubscriptionInstanceContainer
        object to this object.
        @param container The SubscriptionInstanceContainer object to copy.
    */
    SubscriptionInstanceContainer& operator=(
        const SubscriptionInstanceContainer& container);

    /**
        Returns the unique name for this Container type.
        @return The String name of the Container type.
    */
    virtual String getName() const;

    /**
        Makes a copy of this SubscriptionInstanceContainer object.  The
        caller is responsible for cleaning up the copy by calling destroy()
        method.
        @return A pointer to the new Container object.
    */
    virtual OperationContext::Container* clone() const;

    /**
        Cleans up a SubscriptionInstanceContainer object that was created
        by the clone() method.
    */
    virtual void destroy();

    /**
        Gets the subscription instance from the SubscriptionInstanceContainer.
        @return A CIMInstance representing a subscription.
    */
    CIMInstance getInstance() const;

protected:
    SubscriptionInstanceContainerRep* _rep;