cimmethod.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_Method_h
#define Pegasus_Method_h

#include <Pegasus/Common/Config.h>
#include <Pegasus/Common/Linkage.h>
#include <Pegasus/Common/String.h>
#include <Pegasus/Common/CIMName.h>
#include <Pegasus/Common/CIMParameter.h>
#include <Pegasus/Common/CIMQualifier.h>
#include <Pegasus/Common/CIMType.h>

PEGASUS_NAMESPACE_BEGIN

class Resolver;
class CIMConstMethod;
class CIMMethodRep;

/**
    The CIMMethod class represents the DMTF standard CIM method definition.
    A CIMMethod is generally defined in the context of a CIMClass.
    A CIMMethod consists of:
    <ul>
        <li>A CIMName containing the name of the method
        <li>A CIMType defining the method return type
        <li>Zero or more CIMQualifier objects
        <li>Zero or more CIMParameter objects defining the method parameters
    </ul>
    In addition, a CIMMethod has these internal attributes:
    <ul>
        <li><b>propagated</b> - An attribute defining whether this CIMMethod
            is propagated from a superclass.  Note that this is normally set
            as part of completing the definition of objects (resolving) when
            they are created as part of a CIM schema and is NOT automatically
            set when creating a method object.  It can only be logically set
            in context of the schema in which the CIMMethod is defined.
        <li><b>classOrigin</b> - An attribute defining the class in which
            this CIMMethod was originally defined.  This is normally set
            within the context of the schema in which the CIMMethod is
            defined.  This attribute is available from objects retrieved
            from the CIM Server, for example, and provides information on
            the defintion of this method in the class hierarchy.  The
            propagated and ClassOrigin attributes can be used together to
            determine if methods originated with this object or were
            inherited from higher levels of the hiearchy.
    </ul>

    <p>The CIMMethod class uses a shared representation model, such that
    multiple CIMMethod objects may refer to the same data copy.  Assignment
    and copy operators create new references to the same data, not distinct
    copies.  An update to a CIMMethod object affects all the CIMMethod
    objects that refer to the same data copy.  The data remains valid until
    all the CIMMethod objects that refer to it are destructed.  A separate
    copy of the data may be created using the clone method.
*/
class PEGASUS_COMMON_LINKAGE CIMMethod
{
public:

    /**
        Constructs an uninitialized CIMMethod object.  A method
        invocation on an uninitialized object will result in the throwing
        of an UninitializedObjectException.  An uninitialized object may
        be converted into an initialized object only by using the assignment
        operator with an initialized object.
    */
    CIMMethod();

    /**
        Constructs a CIMMethod object from the value of a specified
        CIMMethod object, so that both objects refer to the same data copy.

        <p><b>Example:</b>
        <pre>
            CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
            const CIMMethod cm1(m1);
        </pre>

        @param x The CIMMethod object from which to construct a new
            CIMMethod object.
    */
    CIMMethod(const CIMMethod& x);

    /**
        Constructs a CIMMethod object with the specified attributes.
        <p><b>Example:</b>
        <pre>
            CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
        </pre>

        @param name A CIMName specifying the name of the method.
        @param type A CIMType defining the method return type.
        @param classOrigin A CIMName indicating the class in which the
            method is locally defined (optional).
        @param propagated A Boolean indicating whether the method definition
            is local to the CIMClass in which it appears or was propagated
            (without modification) from a superclass.
        @exception UninitializedObjectException If the method name is null.
    */
    CIMMethod(
        const CIMName& name,
        CIMType type,
        const CIMName& classOrigin = CIMName(),
        Boolean propagated = false);

    /**
        Destructs the CIMMethod object.
    */
    ~CIMMethod();

    /**
        Assigns the value of the specified CIMMethod object to this object,
        so that both objects refer to the same data copy.

        <p><b>Example:</b>
        <pre>
            CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
            CIMMethod m2;
            m2 = m1;
        </pre>

        @param x The CIMMethod object from which to assign this CIMMethod
            object.
        @return A reference to this CIMMethod object.
    */
    CIMMethod& operator=(const CIMMethod& x);

    /**
        Gets the name of the method.
        <p><b>Example:</b>
        <pre>
            CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
            assert(m1.getName() == CIMName ("getHostName"));
        </pre>
        @return A CIMName containing the name of the method.
        @exception UninitializedObjectException If the object is not
            initialized.
    */
    const CIMName& getName() const;

    /**
        Sets the method name.
        <p><b>Example:</b>
        <pre>
            CIMMethod m2(CIMName ("test"), CIMTYPE_STRING);
            m2.setName(CIMName ("getVersion"));
        </pre>
        @return A CIMName containing the new name of the method.
        @exception UninitializedObjectException If the object is not
            initialized.
    */
    void setName(const CIMName& name);

    /**
        Gets the method return type.
        <p><b>Example:</b>
        <pre>
            CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
            assert(m1.getType() == CIMTYPE_STRING);
        </pre>
        @return A CIMType containing the method return type.
        @exception UninitializedObjectException If the object is not
            initialized.
    */
    CIMType getType() const;

    /**
        Sets the method return type to the specified CIMType.
        This is the type of the CIMValue
        that is returned on a CIM method invocation.
        <p><b>Example:</b>
        <pre>
            CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
            m1.setName(CIMName ("getVersion"));
            assert(m1.getName() == CIMName ("getVersion"));
        </pre>
        @param type CIMType to be set into the CIMMethod object.
        @exception UninitializedObjectException If the object is not
            initialized.
    */
    void setType(CIMType type);

    /**
        Gets the class in which this method is locally defined.  This
        information is normally available with methods that are part of
        schema returned from a CIM Server.
        @return CIMName containing the classOrigin attribute.
        @exception UninitializedObjectException If the object is not
            initialized.
    */
    const CIMName& getClassOrigin() const;

    /**
        Sets the classOrigin attribute with the specified class name.
        Normally this method is used internally by a CIM Server when
        defining methods in the context of a schema.
        @param classOrigin A CIMName specifying the name of the class of
            origin for the method.
        @exception UninitializedObjectException If the object is not
            initialized.
    */
    void setClassOrigin(const CIMName& classOrigin);

    /**
        Tests the propagated attribute of the object.  The propagated
        attribute indicates whether this method was propagated from a
        higher-level class.  Normally this attribute is set as part of
        defining a method in the context of a schema.  It is set in
        methods retrieved from a CIM Server.
        @return True if method is propagated; otherwise, false.
        @exception UninitializedObjectException If the object is not
            initialized.
    */
    Boolean getPropagated() const;

    /**
        Sets the propagated attribute.  Normally this is used by a CIM Server
        when defining a method in the context of a schema.
        @param propagated A Boolean indicating whether the method is
            propagated from a superclass.
        @exception UninitializedObjectException If the object is not
            initialized.
    */
    void setPropagated(Boolean propagated);

    /**
        Adds a qualifier to the method.
        <p><b>Example:</b>
        <pre>
            CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
            m1.addQualifier(CIMQualifier(CIMName ("stuff"), true));
        </pre>
        @param x The CIMQualifier to be added.
        @return A reference to this CIMMethod object.
        @exception AlreadyExistsException If a qualifier with the
            same name already exists in the CIMMethod.
        @exception UninitializedObjectException If the object is not
            initialized.
    */
    CIMMethod& addQualifier(const CIMQualifier& x);

    /**
        Finds a qualifier by name.
        <p><b>Example:</b>
        <pre>
            CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);