(file) Return to CIMObjectPath.h CVS log (file) (dir) Up to [Pegasus] / pegasus / src / Pegasus / Common

Diff for /pegasus/src/Pegasus/Common/CIMObjectPath.h between version 1.32 and 1.33

version 1.32, 2006/01/30 16:16:47 version 1.33, 2006/02/17 19:30:37
Line 48 
Line 48 
 class CIMObjectPathRep; class CIMObjectPathRep;
 class CIMValue; class CIMValue;
  
 /** The CIMKeyBinding class associates a key name, value, and type.  /**
     It is used by the CIMObjectPath class to represent key bindings.      The CIMKeyBinding class associates a key name, value, and type.
     See the CIMObjectPath class to see how they are used.      It is used to represent a key binding in a CIMObjectPath.
 */ */
 class PEGASUS_COMMON_LINKAGE CIMKeyBinding class PEGASUS_COMMON_LINKAGE CIMKeyBinding
 { {
Line 58 
Line 58 
  
     enum Type { BOOLEAN, STRING, NUMERIC, REFERENCE };     enum Type { BOOLEAN, STRING, NUMERIC, REFERENCE };
  
     /** Constructs a CIMKeyBinding object with null values (default constructor).      /**
           Constructs a CIMKeyBinding object with null values.
      */      */
     CIMKeyBinding();     CIMKeyBinding();
  
     /** Copy constructor.      /**
     @param x Specifies the name of the CIMKeyBinding instance.          Constructs a CIMKeyBinding object from the value of a specified
           CIMKeyBinding object.
           @param x The CIMKeyBinding object from which to construct a new
               CIMKeyBinding object.
     */     */
     CIMKeyBinding(const CIMKeyBinding& x);     CIMKeyBinding(const CIMKeyBinding& x);
  
     /** Constructs a CIMKeyBinding with a name, value, and type.      /**
         @param name CIMName for the key for this binding object.          Constructs a CIMKeyBinding with a name, value, and type.
         @param value String value for this key.          @param name A CIMName containing the key name.
         @param type CIMKeyBinding::Type representing the type of this key.          @param value A String value for this key.
           @param type A CIMKeyBinding::Type specifying the type of this key.
     */     */
     CIMKeyBinding(const CIMName& name, const String& value, Type type);     CIMKeyBinding(const CIMName& name, const String& value, Type type);
  
     /** Constructs a CIMKeyBinding with a name and CIMValue, mapping from      /**
         CIMValue types to CIMKeyBinding types.          Constructs a CIMKeyBinding with a key name and CIMValue.  The key
         @param name CIMName for the key for this binding object.          value and type are taken from the CIMValue.  CIM types are converted
         @param value CIMValue from which to extract the value for this key.          to key binding types using this mapping:
         @exception TypeMismatchException True if the type of the value is not valid  
         for a key property; otherwise, false.          <pre>
           boolean - BOOLEAN
           uint8 - NUMERIC
           sint8 - NUMERIC
           uint16 - NUMERIC
           sint16 - NUMERIC
           uint32 - NUMERIC
           sint32 - NUMERIC
           uint64 - NUMERIC
           sint64 - NUMERIC
           real32 - NUMERIC
           real64 - NUMERIC
           char16 - STRING
           string - STRING
           datetime - STRING
           reference - REFERENCE
           </pre>
   
           A value of type CIMTYPE_OBJECT cannot be used in a key binding.
   
           @param name A CIMName containing the key name.
           @param value A CIMValue specifying the value and type of this key.
           @exception TypeMismatchException If the type is not a valid key type,
               false otherwise.
     */     */
     CIMKeyBinding(const CIMName& name, const CIMValue& value);     CIMKeyBinding(const CIMName& name, const CIMValue& value);
  
     /** CIMKeyBinding destructor      /**
           Destructs the CIMKeyBinding object.
     */     */
     ~CIMKeyBinding();     ~CIMKeyBinding();
  
     /** Assigns the values of the specified CIMKeyBinding instance      /**
     to the CIMKeyBinding object.          Assigns the value of the specified CIMKeyBinding object to this object.
           @param x The CIMKeyBinding object from which to assign this
               CIMKeyBinding object.
           @return A reference to this CIMKeyBinding object.
     */     */
     CIMKeyBinding& operator=(const CIMKeyBinding& x);     CIMKeyBinding& operator=(const CIMKeyBinding& x);
  
     /** REVIEWERS: Insert description here.      /**
           Gets the key name for the key binding.
           @return A CIMName containing the key name.
     */     */
     const CIMName& getName() const;     const CIMName& getName() const;
  
     /** REVIEWERS: Insert description here.      /**
     @param name Reviewers: Insert description here.          Sets the key name for the key binding.
           @param name A CIMName containing the key name.
     */     */
     void setName(const CIMName& name);     void setName(const CIMName& name);
  
     /** REVIEWERS: Insert description here.      /**
           Gets the key value for the key binding.
           @return A String containing the key value.
     */     */
     const String& getValue() const;     const String& getValue() const;
  
     /** REVIEWERS: Insert description here.      /**
     @param value Reviewers: Insert description here.          Sets the key value for the key binding.
           @param value A String containing the key value.
     */     */
     void setValue(const String& value);     void setValue(const String& value);
  
     /** REVIEWERS: Insert description here.      /**
           Gets the key type for the key binding.
           @return A CIMKeyBinding::Type containing the key type.
     */     */
     Type getType() const;     Type getType() const;
  
     /** REVIEWERS: Insert description here.      /**
     @param type Reviewers: Insert description here.          Sets the key type for the key binding.
           @param type A CIMKeyBinding::Type containing the key type.
     */     */
     void setType(Type type);     void setType(Type type);
  
     /** REVIEWERS: Insert description here.      /**
     @param value Reviewers: Insert description here.          Compares the value and type of the key binding with a specified
     @return Reviewers: Insert description here.          CIMValue.
           @param value The CIMValue to be compared.
           @return True if the value and type of the key binding are the same as
               the specified CIMValue, false otherwise.
     */     */
     Boolean equal(CIMValue value);     Boolean equal(CIMValue value);
  
Line 132 
Line 176 
     friend class CIMObjectPath;     friend class CIMObjectPath;
 }; };
  
   /**
       Compares two key bindings for equality.
       @param x The first CIMKeyBinding to be compared.
       @param y The second CIMKeyBinding to be compared.
       @return True if the names, values, and types of the two key bindings are
           equivalent, false otherwise.
   */
 PEGASUS_COMMON_LINKAGE Boolean operator==( PEGASUS_COMMON_LINKAGE Boolean operator==(
     const CIMKeyBinding& x,     const CIMKeyBinding& x,
     const CIMKeyBinding& y);     const CIMKeyBinding& y);
Line 142 
Line 193 
  
 class XmlWriter; class XmlWriter;
  
 /** The CIMObjectPath class represents the value of a reference. A reference  /**
     is one of the property types that an association may contain. Consider the      The CIMObjectPath class represents the DMTF standard CIM object name or
     following MOF for example:      reference.  A reference is a property type that is used in an association.
       Consider this MOF example:
  
     <pre>     <pre>
     [Association]     [Association]
Line 155 
Line 207 
     };     };
     </pre>     </pre>
  
     The value of the from and to properties are internally represented using      The value of the "from" and "to" properties are represented using a
     the CIMObjectPath class.      CIMObjectPath.
  
     A CIM reference is used to uniquely identify a CIM class or CIM instance     A CIM reference is used to uniquely identify a CIM class or CIM instance
     object. CIMObjectPath objects contain the following parts:      object.  A CIMObjectPath consists of:
  
     <ul>     <ul>
     <li>Host - name of host that contains the object</li>     <li>Host - name of host that contains the object</li>
Line 259 
Line 311 
     keyBindings.append(CIMKeyBinding("last", "Rafter", CIMKeyBinding::STRING));     keyBindings.append(CIMKeyBinding("last", "Rafter", CIMKeyBinding::STRING));
     </pre>     </pre>
  
     The key binding types that are supported are:  
   
     <ul>  
     <li>CIMKeyBinding::BOOLEAN</li>  
     <li>CIMKeyBinding::STRING</li>  
     <li>CIMKeyBinding::NUMERIC</li>  
     <li>CIMKeyBinding::REFERENCE</li>  
     </ul>  
   
     The CIM types are encoded as one of the key binding types in the  
     following way  
   
     <pre>  
     boolean - BOOLEAN (the value must be "true" or "false")  
     uint8 - NUMERIC  
     sint8 - NUMERIC  
     uint16 - NUMERIC  
     sint16 - NUMERIC  
     uint32 - NUMERIC  
     sint32 - NUMERIC  
     uint64 - NUMERIC  
     sint64 - NUMERIC  
     char16 - STRING  
     string - STRING  
     datetime - STRING  
     reference - REFERENCE  
     </pre>  
   
     Notice that real32 and real64 are missing. Properties of these types  
     cannot be used as keys.  
   
     Also, properties of CIMTYPE_OBJECT cannot be used as keys.  
   
     Notice that the keys in the object name may appear in any order.     Notice that the keys in the object name may appear in any order.
     That is the following object names refer to the same object:     That is the following object names refer to the same object:
  
Line 359 
Line 378 
 { {
 public: public:
  
     /** Constructs a CIMObjectPath object with null values (default constructor).      /**
           Constructs a CIMObjectPath object with null values.
     */     */
     CIMObjectPath();     CIMObjectPath();
  
     /** Copies the values of the specified CIMObjectPath instance to the      /**
           Constructs a CIMObjectPath object from the value of a specified
           CIMObjectPath object.
           @param x The CIMObjectPath object from which to construct a new
     CIMObjectPath object.     CIMObjectPath object.
     @param x Specifies the name of the CIMObjectPath instance.  
     */     */
     CIMObjectPath(const CIMObjectPath& x);     CIMObjectPath(const CIMObjectPath& x);
  
     /** Initializes a CIMObjectPath object from a CIM object name.      /**
         @param objectName String representing the object name.          Constructs a CIMObjectPath from a CIM object name in String form.
         @return Returns the initialized CIMObjectPath          <p><b>Example:</b>
         @exception MalformedObjectNameException True if the name is not parsable;          <pre>
         otherwise, false.  
         <PRE>  
             CIMObjectPath r1 = "MyClass.z=true,y=1234,x=\"Hello World\"";             CIMObjectPath r1 = "MyClass.z=true,y=1234,x=\"Hello World\"";
         </PRE>          </pre>
           @param objectName A String representation of the object name.
           @exception MalformedObjectNameException If the String does not contain
               a properly formed object name.
     */     */
     CIMObjectPath(const String& objectName);     CIMObjectPath(const String& objectName);
  
     /** Constructs a CIMObjectPath from constituent elements.      /**
         @param host Name of host (e.g., "nemesis-5988").          Constructs a CIMObjectPath object with the specified attributes.
         @param nameSpace Namespace (e.g., "root/cimv2").          @param host A String containing the host name (e.g., "nemesis:5988").
         @param className Name of a class (e.g., "MyClass").              An empty String indicates that the object path does not contain
         @param keyBindings An array of CIMKeyBinding objects.              a host name attribute.
         @return Returns the constructed CIMObjectPath          @param nameSpace A CIMNamespaceName specifying the namespace name.
               A null name indicates that the object path does not contain
               a namespace attribute.
           @param nameSpace A CIMName specifying the class name.
           @param keyBindings An Array of CIMKeyBinding objects specifying the
               key bindings.
           @exception MalformedObjectNameException If the host name String
               contains an improperly formed host name.
     */     */
     CIMObjectPath(     CIMObjectPath(
         const String& host,         const String& host,
         const CIMNamespaceName& nameSpace,         const CIMNamespaceName& nameSpace,
         const CIMName& className,         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>());         const Array<CIMKeyBinding>& keyBindings = Array<CIMKeyBinding>());
  
     /** Destroys CIMObjectPath object.      /**
           Destructs the CIMObjectPath object.
     */     */
     ~CIMObjectPath();     ~CIMObjectPath();
  
     /** Assigns the values of the CIMObjectPath instance to the CIMObjectPath object.      /**
     @param x Specifies the name of the CIMObjectPath instance.          Assigns the value of the specified CIMObjectPath object to this object.
           @param x The CIMObjectPath object from which to assign this
               CIMObjectPath object.
           @return A reference to this CIMObjectPath object.
      */      */
     CIMObjectPath& operator=(const CIMObjectPath& x);     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          Resets the attributes of the object path to null values.
         was initialized with the default constructor.          The result is equivalent to using the default constructor.
     */     */
     void clear();     void clear();
  
     /** Sets this reference from constituent elements. The effect is same      /**
         as if the object was initialized using the constructor above that          Sets the CIMObjectPath with the specified attributes.
         has the same arguments.          @param host A String containing the host name (e.g., "nemesis:5988").
         @exception MalformedObjectNameException True if host name is not specified              An empty String indicates that the object path does not contain
                 correctly otherwise, false.              a host name attribute.
         @param host REVIEWERS: Insert description here.          @param nameSpace A CIMNamespaceName specifying the namespace name.
         @param nameSpace REVIEWERS: Insert description here.              A null name indicates that the object path does not contain
         @param className REVIEWERS: Insert description here.              a namespace attribute.
         @param keyBindings REVIEWERS: Insert description here.          @param nameSpace A CIMName specifying the class name.
           @param keyBindings An Array of CIMKeyBinding objects specifying the
               key bindings.
           @exception MalformedObjectNameException If the host name String
               contains an improperly formed host name.
     */     */
     void set(     void set(
         const String& host,         const String& host,
         const CIMNamespaceName& nameSpace,         const CIMNamespaceName& nameSpace,
         const CIMName& className,         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>());         const Array<CIMKeyBinding>& keyBindings = Array<CIMKeyBinding>());
  
     /** Set the reference from an object name.      /**
     @param objectName Specifies the name of the String instance.          Sets the CIMObjectPath from a CIM object name in String form.
           @param objectName A String representation of the object name.
           @exception MalformedObjectNameException If the String does not contain
               a properly formed object name.
     */     */
     void set(const String& objectName);     void set(const String& objectName);
  
     /** Set the reference from an object name using an assignment operator.      /**
     @param objectName Specifies the name of the String instance.          Sets the CIMObjectPath from a CIM object name in String form.
           @param objectName A String representation of the object name.
           @exception MalformedObjectNameException If the String does not contain
               a properly formed object name.
     */     */
     CIMObjectPath& operator=(const String& objectName);     CIMObjectPath& operator=(const String& objectName);
  
     /** Gets the hostname component of the CIMObjectPath.      /**
         @return String containing hostname.          Gets the host name for the object path.
           @return A String containing the host name.
     */     */
     const String& getHost() const;     const String& getHost() const;
  
     /** Sets the hostname component of the CIMObjectPath      /**
         object to the input parameter.          Sets the host name for the object path.
         @param host String parameter with the hostname          <p><b>Example:</b>
         <PRE>          <pre>
         CIMObjectPath r1;         CIMObjectPath r1;
         r1.setHost("fred:5988");         r1.setHost("fred:5988");
         </PRE>          </pre>
         Note that Pegasus does not check whether or not the host names are valid.          @param host A String containing the host name.
           @exception MalformedObjectNameException If the host name String
               contains an improperly formed host name.
     */     */
     void setHost(const String& host);     void setHost(const String& host);
  
     /** Gets the namespace component of the      /**
         CIMObjectPath as a CIMNamespaceName.          Gets the namespace name for the object path.
           @return A CIMNamespaceName containing the namespace name.
     */     */
     const CIMNamespaceName& getNameSpace() const;     const CIMNamespaceName& getNameSpace() const;
  
     /** Sets the namespace component.      /**
         @param nameSpace CIMNamespaceName representing the namespace.          Sets the namespace name for the object path.
           @param nameSpace A CIMNamespaceName containing the namespace name.
     */     */
     void setNameSpace(const CIMNamespaceName& nameSpace);     void setNameSpace(const CIMNamespaceName& nameSpace);
  
     /** Gets the className component of the CIMObjectPath.      /**
         @return CIMName containing the classname.          Gets the class name for the object path.
           @return A CIMName containing the class name.
      */      */
     const CIMName& getClassName() const;     const CIMName& getClassName() const;
  
     /** Sets the classname component of the CIMObjectPath object to      /**
         the input parameter.          Sets the class name for the object path.
         @param className CIMName containing the className.          @param className A CIMName containing the class name.
     */     */
     void setClassName(const CIMName& className);     void setClassName(const CIMName& className);
  
     /** Returns an Array of keybindings from the      /**
         CIMObjectPath representing all of the key/value pairs defined          Gets the key bindings for the object path.
         in the ObjectPath.          @return An Array of CIMKeyBinding objects containing the key bindings.
         @return Array of CIMKeyBinding objects from the CIMObjectPath.  
     */     */
     const Array<CIMKeyBinding>& getKeyBindings() const;     const Array<CIMKeyBinding>& getKeyBindings() const;
  
     /** Sets the key/value pairs in the CIMObjectPath      /**
         from an array of keybindings defined by the input parameter.          Sets the key bindings for the object path.
         @param keyBindings Array of keybindings to set into the CIMObjectPath          @param keyBindings An Array of CIMKeyBinding objects containing the
         object.              key bindings.
     */     */
     void setKeyBindings(const Array<CIMKeyBinding>& keyBindings);     void setKeyBindings(const Array<CIMKeyBinding>& keyBindings);
  
       /**
           Generates a String form of the object path.
           The format is:
  
     /** Returns the object name represented by this reference. The returned          <pre>
         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 +"." +             "//" + hostname + "/" + namespace + ":" + classname +"." +
             (keyname) + "=" (keyvalue) +"," ...             (keyname) + "=" (keyvalue) +"," ...
         </PRE>          </pre>
   
           Special characters are escaped in the resulting String.
  
         The building includes the escaping of special characters.          @return A String form of the object path.
           @exception UninitializedObjectException If the class name attribute
               of the object path is null.
     */     */
     String toString() const;     String toString() const;
  
     /** Returns true if this reference is identical to the one given      /**
         by the x argument. Since CIMObjectPaths are normalized when they          Compares the CIMObjectPath with a specified CIMObjectPath.
         are created, any differences in the ordering of keybindings is accounted          Comparisons of CIM names are case-insensitive, per the CIM
         for as are the case insensitivity characteristics defined by          specification.
         the specification.          @param x The CIMObjectPath to be compared.
         @param x CIMObjectPath for comparison.          @return True if this object is identical to the one specified,
         @return True if the objects have identical components; otherwise, false.              false otherwise.
     */     */
     Boolean identical(const CIMObjectPath& x) const;     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          Generates a hash code for the object path.  Identical references
         the case of the classname and key names as well as the order of the          generate the same hash code (despite insignificant differences such as
         keys).          the case of names and the order of the key bindings).
     */     */
     Uint32 makeHashCode() const;     Uint32 makeHashCode() const;
  
   
 private: private:
  
     /** String object into canonical form (in which all keys are sorted      /**
         into ascending order and classnames and keynames are shifted to          Generates a canonical String form of the object path (in which key
         lower case.          bindings are sorted and classnames and keynames are converted to
           lower case).
           @return A canonical String form of the object path.
           @exception UninitializedObjectException If the class name attribute
               of the object path is null.
     */     */
     String _toStringCanonical() const;     String _toStringCanonical() const;
  
     CIMObjectPathRep* _rep;     CIMObjectPathRep* _rep;
 }; };
  
   /**
       Compares two object paths for equality.
       @param x The first CIMObjectPath to be compared.
       @param y The second CIMObjectPath to be compared.
       @return True if the object paths are identical, false otherwise.
   */
 PEGASUS_COMMON_LINKAGE Boolean operator==( PEGASUS_COMMON_LINKAGE Boolean operator==(
     const CIMObjectPath& x,     const CIMObjectPath& x,
     const CIMObjectPath& y);     const CIMObjectPath& y);
  
   /**
       Compares two object paths for inequality.
       @param x The first CIMObjectPath to be compared.
       @param y The second CIMObjectPath to be compared.
       @return False if the object paths are identical, true otherwise.
   */
 PEGASUS_COMMON_LINKAGE Boolean operator!=( PEGASUS_COMMON_LINKAGE Boolean operator!=(
     const CIMObjectPath& x,     const CIMObjectPath& x,
     const CIMObjectPath& y);     const CIMObjectPath& y);

Legend:
Removed from v.1.32  
changed lines
  Added in v.1.33
No CVS admin address has been configured
 Powered by
ViewCVS 0.9.2