cimobjectpath.h

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

    sint32 - NUMERIC
    uint64 - NUMERIC
    sint64 - NUMERIC
    char16 - NUMERIC
    string - STRING
    datetime - STRING
    </pre>

    Notice that real32 and real64 are missing. Properties of these types
    cannot be used as keys.

    Notice that the keys in the object name may appear in any order.
    That is the following object names refer to the same object:

    <pre>
    TennisPlayer.first="Patrick",last="Rafter"
    TennisPlayer.last="Rafter",first="Patrick"
    </pre>

    And since CIM is not case sensitive, the following refer to the same
    object:

    <pre>
    TennisPlayer.first="Patrick",last="Rafter"
    tennisplayer.FIRST="Patrick",Last="Rafter"
    </pre>

    Therefore, the CIMObjectPaths::operator==() would return true for the last
    two examples.

    The CIM standard leaves it an open question whether model paths may have
    spaces around delimiters (like '.', '=', and ','). We assume they cannot.
    So the following is an invalid model path:

    <pre>
    TennisPlayer . first = "Patrick", last="Rafter"
    </pre>

    We require that the '.', '=', and ',' have no spaces around them.

    For reasons of efficiency, the key bindings are internally sorted
    during initialization. This allows the key bindings to be compared
    more easily. This means that when the string is converted back to
    string (by calling toString()) that the keys may have been rearranged.

    There are two forms an object name can take:

    <pre>
    &lt;namespace-path&gt;:&lt;model-path&gt;
    &lt;model-path&gt;
    </pre>

    In other words, the namespace-path is optional. Here is an example of
    each:

    <pre>
    //atp:9999/root/cimv25:TennisPlayer.first="Patrick",last="Rafter"
    TennisPlayer.first="Patrick",last="Rafter"
    </pre>

    If it begins with "//" then we assume the namespace-path is present and
    process it that way.

    It should also be noted that an object name may refer to an instance or
    a class. Here is an example of each:

    <pre>
    TennisPlayer.first="Patrick",last="Rafter"
    TennisPlayer
    </pre>

    In the second case--when it refers to a class--the key bindings are
    omitted.
*/
class PEGASUS_COMMON_LINKAGE CIMObjectPath
{
public:

    /** Default constructor. */
    CIMObjectPath();

    /** Copy constructor. */
    CIMObjectPath(const CIMObjectPath& x);

    /** Initializes a CIMObjectPath object from a CIM object name.
        @param objectName String representing the object name.
        @return Returns the initialized CIMObjectPath
        @exception MalformedObjectNameException if the name is not parsable.
        <PRE>
            CIMObjectPath r1 = "MyClass.z=true,y=1234,x=\"Hello World\"";
        </PRE>
    */
    CIMObjectPath(const String& objectName);

    /** Constructs a CIMObjectPath from constituent elements.
        @param host Name of host (e.g., "nemesis-5988").
        @param nameSpace Namespace (e.g., "root/cimv2").
        @param className Name of a class (e.g., "MyClass").
        @param keyBindings An array of CIMKeyBinding objects.
        @return Returns the constructed CIMObjectPath
    */
    CIMObjectPath(
        const String& host,
        const CIMNamespaceName& nameSpace,
        const CIMName& className,
        //
        //  NOTE: Due to a bug in MSVC 5, the following will not work on MSVC 5
        //
        const Array<CIMKeyBinding>& keyBindings = Array<CIMKeyBinding>());

    /** Destructor. */
    ~CIMObjectPath();

    /** Assignment operator. */
    CIMObjectPath& operator=(const CIMObjectPath& x);

    /** Clears out the internal fields of this object making it an empty
        (or uninitialized) reference. The effect is the same as if the object
        was initialized with the default constructor.
    */
    void clear();

    /** Sets this reference from constituent elements. The effect is same
        as if the object was initialized using the constructor above that
        has the same arguments.
        @exception MalformedObjectNameException if host name is illformed.
    */
    void set(
        const String& host,
        const CIMNamespaceName& nameSpace,
        const CIMName& className,
        //
        //  NOTE: Due to a bug in MSVC 5, the following will not work on MSVC 5
        //
        const Array<CIMKeyBinding>& keyBindings = Array<CIMKeyBinding>());

    /** Set the reference from an object name . */
    void set(const String& objectName);

    /** Same as set() above except that it is an assignment operator. */
    CIMObjectPath& operator=(const String& objectName);

    /** Gets the hostname component of the CIMObjectPath.
        @return String containing hostname.
    */
    const String& getHost() const;

    /** Sets the hostname component of the CIMObjectPath
        object to the input parameter.
        @param host String parameter with the hostname
        <PRE>
        CIMObjectPath r1;
        r1.setHost("fred:5988");
        </PRE>
        Note that Pegasus does no checking on valid host names.
    */
    void setHost(const String& host);

    /** Gets the namespace component of the
        CIMObjectPath as a CIMNamespaceName.
    */
    const CIMNamespaceName& getNameSpace() const;

    /** Sets the namespace component.
        @param nameSpace CIMNamespaceName representing the namespace.
    */
    void setNameSpace(const CIMNamespaceName& nameSpace);

    /** Gets the className component of the CIMObjectPath.
        @return CIMName containing the classname.
     */
    const CIMName& getClassName() const;

    /** Sets the classname component of the CIMObjectPath object to 
        the input parameter.
        @param className CIMName containing the className.
    */
    void setClassName(const CIMName& className);

    /** Returns an Array of keybindings from the
        CIMObjectPath representing all of the key/value pairs defined 
        in the ObjectPath.
        @return Array of CIMKeyBinding objects from the CIMObjectPath.
    */
    const Array<CIMKeyBinding>& getKeyBindings() const;

    /** Sets the key/value pairs in the CIMObjectPath
        from an array of keybindings defined by the input parameter.
        @param keyBindings Array of keybindings to set into the CIMObjectPath
        object.
    */
    void setKeyBindings(const Array<CIMKeyBinding>& keyBindings);


    /** Returns the object name represented by this reference. The returned
        string is formed from the hostname, namespace, classname
        and keybindings defined for this CIMObjectPath object.
        The form of the name is:

        <PRE>
            "//" + hostname + "/" + namespace + ":" + classname +"." +
            (keyname) + "=" (keyvalue) +"," ...
        </PRE>

        The building includes the escaping of special characters.
    */
    String toString() const;

    /** Returns true if this reference is identical to the one given
        by the x argument. Since CIMObjectPaths are normalized when they
        are created, any differences in the ordering of keybindings is accounted
        for as are the case insensitivity characteristics defined by
        the specification.
        @param x CIMObjectPath for comparison.
        @return true if the objects have identical components, false otherwise.
    */
    Boolean identical(const CIMObjectPath& x) const;

    /** Generates hash code for the given reference. Two identical references
        generate the same hash code (despite any subtle differences such as
        the case of the classname and key names as well as the order of the
        keys).
    */
    Uint32 makeHashCode() const;


private:

    /** Stringizes object into canonical form (in which all keys are sorted
        into ascending order and classnames and keynames are shifted to
        lower case.
    */
    String _toStringCanonical() const;

    CIMObjectPathRep* _rep;
};

PEGASUS_COMMON_LINKAGE Boolean operator==(
    const CIMObjectPath& x,
    const CIMObjectPath& y);

PEGASUS_COMMON_LINKAGE Boolean operator!=(
    const CIMObjectPath& x,
    const CIMObjectPath& y);

#define PEGASUS_ARRAY_T CIMObjectPath
# include <Pegasus/Common/ArrayInter.h>
#undef PEGASUS_ARRAY_T

PEGASUS_NAMESPACE_END

#endif /* Pegasus_ObjectPath_h */