pegasus/src/Pegasus/Common/CIMInstance.h - diff

Return to CIMInstance.h CVS log

Up to [Pegasus] / pegasus / src / Pegasus / Common

Diff for /pegasus/src/Pegasus/Common/CIMInstance.h between version 1.70 and 1.71

version 1.70, 2006/01/30 16:16:46

version 1.71, 2006/02/17 19:30:37

Line 52

class CIMInstanceRep;

class Resolver;

/** This class represents the instance of a CIM class. It is used manipulate

/**

instances and their members.

The CIMInstance class represents the DMTF standard CIM instance definition.

The CIMInstance class uses a shared representation model, such that

multiple CIMInstance 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 CIMInstance object affects all the CIMInstance

objects that refer to the same data copy. The data remains valid until

all the CIMInstance objects that refer to it are destructed. A separate

copy of the data may be created using the clone method.

class PEGASUS_COMMON_LINKAGE CIMInstance

{

public:

/** Creates a CIMInstance object.

/**

Constructs an uninitialized CIMInstance 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.

CIMInstance();

/** Creates a CIMInstance object from another CIMInstance object.

/**

@param x - CIMInstance object from which the new instance is created.

Constructs a CIMInstance object from the value of a specified

CIMInstance object, so that both objects refer to the same data copy.

@param x The CIMInstance object from which to construct a new

CIMInstance object.

CIMInstance(const CIMInstance& x);

/** Creates a CIMInstance object from the given CIMObject.

/**

@param x - CIMObject from which to create the CIMInstance.

Constructs a CIMInstance object from the value of a specified

CIMObject object, so that both objects refer to the same data copy.

@param x The CIMObject object from which to construct the

CIMInstance object.

@exception DynamicCastFailedException If a CIMInstance can not be

created from the given CIMObject.

PEGASUS_EXPLICIT CIMInstance(const CIMObject& x);

/** Creates a CIMInstance object of the class specified by

/**

the input parameter.

Constructs a CIMInstance object with the specified class name.

@param className - CIMName to be used with new instance object.

@param className A CIMName specifying the class name of the instance.

CIMInstance(const CIMName& className);

/** Copy Constructor. */

/**

Assigns the value of the specified CIMInstance object to this object,

so that both objects refer to the same data copy.

@param x The CIMInstance object from which to assign this CIMInstance

object.

@return A reference to this CIMInstance object.

CIMInstance& operator=(const CIMInstance& x);

/** Destructor. */

/**

Destructs the CIMInstance object.

~CIMInstance();

/** Gets the class name of the instance.

/**

@return CIMName with the class name.

Gets the class name of the instance.

@return A CIMName containing the class name.

@exception UninitializedObjectException If the object is not

initialized.

const CIMName& getClassName() const;

///

/**

Gets the object path for the instance.

@return A CIMObjectPath containing the object path.

@exception UninitializedObjectException If the object is not

initialized.

const CIMObjectPath& getPath() const;

/** Sets the object path for the instance.

/**

@param path - CIMObjectPath containing the object path.

Sets the object path for the instance.

@param path A CIMObjectPath containing the object path.

@exception UninitializedObjectException If the object is not

initialized.

void setPath (const CIMObjectPath & path);

/** Adds the CIMQualifier object to the instance.

/**

@param qualifier - CIMQualifier object to add to instance.

Adds a qualifier to the instance.

@return the resulting CIMInstance.

@param qualifier The CIMQualifier to be added.

@exception AlreadyExistsException if the CIMQualifier

@return A reference to this CIMInstance object.

already exists in the instance.

@exception AlreadyExistsException If a qualifier with the

same name already exists in the CIMInstance.

@exception UninitializedObjectException If the object is not

initialized.

CIMInstance& addQualifier(const CIMQualifier& qualifier);

/** Searches the instance for the qualifier object defined by

/**

the input parameter.

Finds a qualifier by name.

@param name - CIMName defining the qualifier object to be found.

@param name A CIMName specifying the name of the qualifier to be found.

@return Position of the qualifier to be used in subsequent

@return Index of the qualifier if found or PEG_NOT_FOUND if not found.

operations or PEG_NOT_FOUND if the qualifier is not found.

@exception UninitializedObjectException If the object is not

initialized.

Uint32 findQualifier(const CIMName& name) const;

/** Retrieves the qualifier object defined by the input parameter.

/**

The index to qualifier objects is zero-origin and continuous

Gets the qualifier at the specified index.

so that incrementing loops can be used to get all qualifier

@param index The index of the qualifier to be retrieved.

objects in a CIMInstance.

@return The CIMQualifier at the specified index.

@param index - Index for the qualifier object.

@exception IndexOutOfBoundsException If the index is outside

@return Qualifier object defined by index.

the range of qualifiers available for the CIMInstance.

@exception IndexOutOfBoundsException exception if the index

@exception UninitializedObjectException If the object is not

is out of bounds.

initialized.

CIMQualifier getQualifier(Uint32 index);

/** Retrieves the qualifier object defined by the input parameter.

/**

The index to qualifier objects is zero-origin and continuous

Gets the qualifier at the specified index.

so that incrementing loops can be used to get all qualifier

@param index The index of the qualifier to be retrieved.

objects in a CIMInstance.

@return The CIMConstQualifier at the specified index.

@param index - Index for the qualifier object.

@exception IndexOutOfBoundsException If the index is outside

@return Qualifier object defined by index.

the range of qualifiers available for the CIMInstance.

@exception IndexOutOfBoundsException exception if the index

@exception UninitializedObjectException If the object is not

is out of bounds.

initialized.

CIMConstQualifier getQualifier(Uint32 index) const;

/** Removes the qualifier defined by the index parameter.

/**

@param index Defines the index of the qualifier to be removed.

Removes a qualifier from the instance.

@exception IndexOutOfBoundsException if the index is outside

@param index The index of the qualifier to remove.

the range of existing qualifier objects for this instance.

@exception IndexOutOfBoundsException If the index is

outside the range of qualifiers available for the CIMInstance.

@exception UninitializedObjectException If the object is not

initialized.

void removeQualifier(Uint32 index);

/** Gets the count of the CIMQualifier objects defined

/**

for this CIMInstance.

Gets the number of qualifiers in the instance.

@return Count of the number of CIMQalifier objects in the

@return An integer count of the qualifiers in the CIMInstance.

CIMInstance.

@exception UninitializedObjectException If the object is not

initialized.

Uint32 getQualifierCount() const;

/** Adds a property object defined by the input parameter to

/**

the CIMInstance.

Adds a property to the instance.

@param x - Property Object to be added. See the CIMProperty

@param x The CIMProperty to be added.

class for definition of the property object.

@return A reference to this CIMInstance object.

@return the resulting CIMInstance.

@exception AlreadyExistsException If a property with the

@exception AlreadyExistsException if the property already exists.

same name already exists in the CIMInstance.

@exception UninitializedObjectException If the object is not

initialized.

CIMInstance& addProperty(const CIMProperty& x);

/** Searches the CIMProperty objects in the CIMInstance for

/**

property object with the name defined by the input parameter.

Finds a property by name.

@param name - CIMName with the name of the property object to be found.

@param name A CIMName specifying the name of the property to be found.

@return Position in the CIM Instance to the property object if found or

@return Index of the property if found or PEG_NOT_FOUND if not found.

PEG_NOT_FOUND if no property object found with the name defined by the

@exception UninitializedObjectException If the object is not

input parameter.

initialized.

Uint32 findProperty(const CIMName& name) const;

/** Gets the CIMProperty object in the CIMInstance defined

/**

by the input parameter.

Gets the property at the specified index.

The index to qualifier objects is zero-origin and continuous

@param index The index of the property to be retrieved.

so that incrementing loops can be used to get all qualifier

@return The CIMProperty at the specified index.

objects in a CIMInstance.

@exception IndexOutOfBoundsException If the index is outside

@param index - Index to the property object in the CIMInstance.

the range of properties available for the CIMInstance.

@return CIMProperty object corresponding to the index.

@exception UninitializedObjectException If the object is not

@exception IndexOutOfBoundsException if index is outside the range of

initialized.

properties in this instance.

CIMProperty getProperty(Uint32 index);

/** Gets the CIMproperty object in the CIMInstance defined

/**

by the input parameter.

Gets the property at the specified index.

The index to qualifier objects is zero-origin and continuous

@param index The index of the property to be retrieved.

so that incrementing loops can be used to get all qualifier

@return The CIMConstProperty at the specified index.

objects in a CIMInstance.

@exception IndexOutOfBoundsException If the index is outside

@param index - Index to the property object in the CIMInstance.

the range of properties available for the CIMInstance.

@return CIMProperty object corresponding to the index.

@exception UninitializedObjectException If the object is not

@exception IndexOutOfBoundsException if index is outside the range of

initialized.

properties in this instance.

CIMConstProperty getProperty(Uint32 index) const;

/** Removes the property defined by the input parameter

/**

from the instance.

Removes a property from the instance.

@param index - Index to the property to be removed from the

@param index The index of the property to remove.

instance. Normally this is obtained by getProperty().

@exception IndexOutOfBoundsException If the index is

@exception IndexOutOfBoundsException if index is outside the range of

outside the range of properties available for the CIMInstance.

properties in this instance.

@exception UninitializedObjectException If the object is not

initialized.

void removeProperty(Uint32 index);

/** Gets the count of CIMProperty objects defined for

/**

this CIMInstance.

Gets the number of properties in the instance.

@return Count of the number of CIMProperty objects in the

@return An integer count of the properties in the CIMInstance.

CIMInstance. Zero indicates that no CIMProperty objects

@exception UninitializedObjectException If the object is not

are contained in the CIMInstance.

initialized.

Uint32 getPropertyCount() const;

/** Builds the CIM object path for this instance. The class

/**

argument is used to determine which fields are keys. The instance

Builds the object path for this instance, based on the class name

name has this form:

and property values in the instance and the Key qualifiers on the

properties in the class definition. The returned object path does

<PRE>

not include hostname and namespace attributes.

ClassName.key1=value1,...,keyN=valueN

Note that this method does not update the path attribute of the

</PRE>

CIMInstance.

@return A CIMObjectPath containing the object path for the instance.

The object path is in standard form (the class name and key name

@exception UninitializedObjectException If the object is not

are all lowercase; the key-value pairs appear in sorted order by

initialized.

key name).

Note that the path attribute of the CIMInstanceRep object is not

modified.

CIMObjectPath buildPath(const CIMConstClass& cimClass) const;

/** Makes a deep copy (clone) of the CIMInstance object. */

/**

Makes a deep copy of the instance. This creates a new copy of all

the instance attributes including qualifiers and properties.

@return A new copy of the CIMInstance object.

@exception UninitializedObjectException If the object is not

initialized.

CIMInstance clone() const;

/** Compares the CIMInstance with another CIMInstance

/**

defined by the input parameter for equality of all components.

Compares the CIMInstance with a specified CIMConstInstance.

@param x - CIMInstance to be compared.

@param x The CIMConstInstance to be compared.

@return true if they are identical, false otherwise.

@return True if this instance is identical to the one specified,

false otherwise.

@exception UninitializedObjectException If the object is not

initialized.

Boolean identical(const CIMConstInstance& x) const;

/** Determines if the object has not been initialized.

/**

@return true if the object has not been initialized,

Determines whether the object has been initialized.

false otherwise.

@return True if the object has not been initialized, false otherwise.

Boolean isUninitialized() const;

#ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES

/** Experimental Interface

Filter the properties, qualifiers and class origin attributes from this

Filter the properties, qualifiers and class origin attributes from the

instance based on filtering criteria defined in the input parameters.

instance based on specified filtering criteria. Information is not

Note that this function does not add anything that was not in the instance

added by this method, it is only removed. This method is specifically

at the beginning of the call. This function does NOT clone the instance

designed to allow providers to filter instances based on CIM operation

but modifies the existing instance. The function was defined specifically

parameters.

for providers to allow creating instances for a specific instance

operation response corresponding to the parameters provided with the

@param includeQualifiers A Boolean indicating whether qualifiers are

operation call (includeQualifiers, etc.) from a more general instance

preserved in the instance and its properties. If false, existing

template.

qualifiers are removed; otherwise, qualifiers are not removed.

Because the CIM specification is unclear on the meaning of this

@param includeQualifiers If false, qualifiers are removed from the

parameter and its relationship to instance operations, the

instance and any properties included in the instance; otherwise no

behavior when this parameter is true MAY change in the future

qualifiers are removed. Because there is still confusion over the exact

based on clarifications of the CIM specification.

operation of this parameter in the CIM specifications and the concept of

instance level qualifiers, the behavior of this function when the

@param includeClassOrigin A Boolean indicating whether ClassOrigin

parameter is true MAY change in the future to match any future

attributes are preserved in the properties. If false, ClassOrigin

clarifications of interoperable behavior in the CIM specifications.

attributes are removed from all properties; otherwise, ClassOrigin

attributes are not removed.

@param includeClassOrigin If false, ClassOrigin attributes are removed from

all properties. Otherwise, ClassOrigin attributes are not filtered.

@param propertyList A CIMPropertyList defining the properties that

are preserved in the instance. If the propertyList is not NULL,

@param propertyList This CIMPropertyList defines the list of properties that should be on the

properties absent from this list are removed from the instance.

instance after completion of the call. If not NULL, properties absent from this list will

If the propertyList is NULL, no properties are removed from the

be removed from the list. If NULL, no properties will be removed from the instance.

instance.

If empty, all properties will be removed from the instance.

@return The CIMInstance with properties and qualifiers from this

instance based on the filtering criteria.

Example:

<pre>

CIMClass myClass .. a defined and complete CIMClass.

// create instance with qualifiers, class origin and all properties

CIMInstance myInstance =

myClass.buildInstance(true, true, CIMPropertyList());

// filter qualifiers off of the instance.

myInstance.filterInstance(false, true, CIMPropertyList());

</pre>

void filter(Boolean includeQualifiers,

@exception UninitializedObjectException If the object is not

initialized.

void filter(

Boolean includeQualifiers,

Boolean includeClassOrigin,

const CIMPropertyList & propertyList);

#endif

Line 313

Line 355

////////////////////////////////////////////////////////////////////////////////

///

/**

The CIMConstInstance class provides a const interface to a CIMInstance

object. This class is needed because the shared representation model

used by CIMInstance does not prevent modification to a const CIMInstance

object. Note that the value of a CIMConstInstance object could still be

modified by a CIMInstance object that refers to the same data copy.

class PEGASUS_COMMON_LINKAGE CIMConstInstance

{

public:

///

/**

Constructs an uninitialized CIMConstInstance 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.

CIMConstInstance();

///

/**

Constructs a CIMConstInstance object from the value of a specified

CIMConstInstance object, so that both objects refer to the same data

copy.

@param x The CIMConstInstance object from which to construct a new

CIMConstInstance object.

CIMConstInstance(const CIMConstInstance& x);

///

/**

Constructs a CIMConstInstance object from the value of a specified

CIMInstance object, so that both objects refer to the same data

copy.

@param x The CIMInstance object from which to construct a new

CIMConstInstance object.

CIMConstInstance(const CIMInstance& x);

///

/**

Constructs a CIMConstInstance object from the value of a specified

CIMObject object, so that both objects refer to the same data copy.

@param x The CIMObject object from which to construct the

CIMConstInstance object.

@exception DynamicCastFailedException If a CIMConstInstance can not be

created from the given CIMObject.

PEGASUS_EXPLICIT CIMConstInstance(const CIMObject& x);

///

/**

Constructs a CIMConstInstance object from the value of a specified

CIMConstObject object, so that both objects refer to the same data

copy.

@param x The CIMConstObject object from which to construct the

CIMConstInstance object.

@exception DynamicCastFailedException If a CIMConstInstance can not be

created from the given CIMConstObject.

PEGASUS_EXPLICIT CIMConstInstance(const CIMConstObject& x);

///

/**

Constructs a CIMConstInstance object with the specified class name.

@param className A CIMName specifying the class name of the instance.

CIMConstInstance(const CIMName& className);

///

/**

Assigns the value of the specified CIMConstInstance object to this

object, so that both objects refer to the same data copy.

@param x The CIMConstInstance object from which to assign this

CIMConstInstance object.

@return A reference to this CIMConstInstance object.

CIMConstInstance& operator=(const CIMConstInstance& x);

///

/**

Assigns the value of the specified CIMInstance object to this

object, so that both objects refer to the same data copy.

@param x The CIMInstance object from which to assign this

CIMConstInstance object.

@return A reference to this CIMConstInstance object.

CIMConstInstance& operator=(const CIMInstance& x);

///

/**

Destructs the CIMConstInstance object.

~CIMConstInstance();

///

/**

Gets the class name of the instance.

@return A CIMName containing the class name.

@exception UninitializedObjectException If the object is not

initialized.

const CIMName& getClassName() const;

///

/**

Gets the object path for the instance.

@return A CIMObjectPath containing the object path.

@exception UninitializedObjectException If the object is not

initialized.

const CIMObjectPath& getPath() const;

///

/**

Finds a qualifier by name.

@param name A CIMName specifying the name of the qualifier to be found.

@return Index of the qualifier if found or PEG_NOT_FOUND if not found.

@exception UninitializedObjectException If the object is not

initialized.

Uint32 findQualifier(const CIMName& name) const;

///

/**

Gets the qualifier at the specified index.

@param index The index of the qualifier to be retrieved.

@return The CIMConstQualifier at the specified index.

@exception IndexOutOfBoundsException If the index is outside

the range of qualifiers available for the CIMConstInstance.

@exception UninitializedObjectException If the object is not

initialized.

CIMConstQualifier getQualifier(Uint32 index) const;

///

/**

Gets the number of qualifiers in the instance.

@return An integer count of the qualifiers in the CIMInstance.

@exception UninitializedObjectException If the object is not

initialized.

Uint32 getQualifierCount() const;

///

/**

Finds a property by name.

@param name A CIMName specifying the name of the property to be found.

@return Index of the property if found or PEG_NOT_FOUND if not found.

@exception UninitializedObjectException If the object is not

initialized.

Uint32 findProperty(const CIMName& name) const;

///

/**

Gets the property at the specified index.

@param index The index of the property to be retrieved.

@return The CIMConstProperty at the specified index.

@exception IndexOutOfBoundsException If the index is outside

the range of properties available for the CIMConstInstance.

@exception UninitializedObjectException If the object is not

initialized.

CIMConstProperty getProperty(Uint32 index) const;

///

/**

Gets the number of properties in the instance.

@return An integer count of the properties in the CIMConstInstance.

@exception UninitializedObjectException If the object is not

initialized.

Uint32 getPropertyCount() const;

///

/**

Builds the object path for this instance, based on the class name

and property values in the instance and the Key qualifiers on the

properties in the class definition. The returned object path does

not include hostname and namespace attributes.

Note that this method does not update the path attribute of the

CIMInstance.

@return A CIMObjectPath containing the object path for the instance.

@exception UninitializedObjectException If the object is not

initialized.

CIMObjectPath buildPath(const CIMConstClass& cimClass) const;

///

/**

Makes a deep copy of the instance. This creates a new copy of all

the instance attributes including qualifiers and properties.

@return A CIMInstance object with a separate copy of the

CIMConstInstance object.

@exception UninitializedObjectException If the object is not

initialized.

CIMInstance clone() const;

///

/**

Compares the CIMConstInstance with a specified CIMConstInstance.

@param x The CIMConstInstance to be compared.

@return True if this instance is identical to the one specified,

false otherwise.

@exception UninitializedObjectException If the object is not

initialized.

Boolean identical(const CIMConstInstance& x) const;

///

/**

Determines whether the object has been initialized.

@return True if the object has not been initialized, false otherwise.

Boolean isUninitialized() const;

private:

Legend:

Removed from v.1.70
changed lines
	Added in v.1.71

No CVS admin address has been configured