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

Return to CIMMethod.h CVS log

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

Diff for /pegasus/src/Pegasus/Common/CIMMethod.h between version 1.40 and 1.41

version 1.40, 2003/11/20 14:50:46

version 1.41, 2003/11/28 18:35:09

Line 48

class CIMConstMethod;

class CIMMethodRep;

/** The CIMMethod class is used to represent CIM methods in Pegasus. A CIMMethod

/** The CIMMethod class is used to represent CIM methods in Pegasus. A Pegasus CIMMethod

consists of the following entities:

<ul>

<li>Name of the method, a CIMName. Functions are provided to manipulate the name.

<li>Name of the method, a CIMName. The name must be a legal name for a

The name must be a legal name for a CIMProperty or Method \Ref{CIMName}.

CIMProperty or Method \Ref{CIMName}.

<li>CIM type of the return value of the method, a \Ref{CIMType}. This is any

of the predefined CIM types (for example: Boolean);

of the predefined CIM types (for example: Boolean).

<li>Optional qualifiers (see \Ref{CIMQualifier}) for the method. A method

can contain zero or more CIMQualifiers and functions are provided to

can contain zero or more CIMQualifiers and methods are provided to

manipulate the list of CIMQualifiers.

manipulate the set of qualifiers attached to a CIMMethod object.

<li>Optional parameters (see \Ref{CIMParameter} for the method which are

the parameters to be placed on a CIM Method operation. A CIMMethod can

contain zero or more CIMParameters and functions are provided in CIMMethod

contain zero or more CIMParameters and methods are provided in CIMMethod

to manipulate the list of CIMParameters.

to manipulate the set of CIMParameters attached to a CIMMethod object.

</ul>

In addition, internally, there are the following additional attributes

In addition a CIMMethod contains the following internal attributes:

that are part of a CIMMethod including:

<ul>

<li>propagated - An attribute defining whether this CIMMethod is

propagated from a superclass. Note that this is normally set as part of

Line 74

Line 76

logically be set in context of the superclass of which this CIMMethod is

defined.

<li>ClassOrigin - An attribute defining the superclass in which this

CIMMethod was originally defined. This is normally set as part of

CIMMethod was originally defined. This is normally set within the context

resolving Class and instances in the context of other objects (for example, a

of the CIM Server context of other CIM objects (for example, a

repository). This attribute is available from objects retrieved from the

repository, for example and indicates the Class/Instance in the hiearchy

CIM Server, for example and provides information on the defintion of this method in the class hiearchy

(this object or a superclass or instance of a superclass)was originally

defined. Together the propagated and ClassOrigin attributes can be used

to determine if methods originated with the current object or were

inherited from higher levels in the hiearchy.

</ul>

Normally CIMMethods are defined in the context of CIMClasses. A CIMClass can include

CIMMethods are generally in the context of a CIMClass.

zero or more CIMMethods

CIMMethod is a shared class so that assignment and copy operators do not

CIMMethod is a shared class that uses shared representations, meaning that multiple

create new copies of the data representing a CIMMethod object but point

CIMMethods objects may refer to the came copy of data. Assignment and copy

back to the original object and the lifecycle of the original object is

operators create new references to the same data, not distinct copies. A distinct copy

controlled by the accumulative lifecycle of any copies and assigned

may be created using teh clone method.

objects.

{@link Shared Classes}

@see CIMConstMethod

@see CIMParameters

@see CIMQualifiers

@see CIMType

@see CIMClass

class PEGASUS_COMMON_LINKAGE CIMMethod

{

public:

/** Creates a new default CIMMethod object. The object created is

/** Creates a new unitialized CIMMethod object.

empty. The only thing that can be done with this constructor

The only thing that can be done with this object is to copy another object

is to copy another object into it. Other methods such as setName, etc.

into it. Other methods such as setName, etc. will fail with an

will fail. The object has the state unitialized which can be tested with

UnitializedObjectException. The object has the state unitialized which

the Unitialized method.

can be tested with the isUnitialized() method.

@exception throws UninitializedObjectException() if any method except the copy

@see isUnitialized()

function is executed against.

@see UnitializedObjectException

@see CIMConstMethod()

@see Unitialized()

CIMMethod();

/** Creates a new CIMMethod object from another CIMmethod instance. This method

/** Creates a new CIMMethod object from another CIMMethod object.

assigns the new object to the representation in the parameter and increments the

The new CIMMethodObject references the same copy of data as the

representation count. It does NOT create a new independent object but creates

specified object; no copy is made.

a reference from the assigned object to the representation of the object being

@param x CIMMethod object from which to create the new CIMMethod object.

assigned.

@param x CIMMethod object from which to create CIMMethod object.

<pre>

CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

const CIMMethod cm1(m1);

</pre>

{@link Shared Classes}

CIMMethod(const CIMMethod& x);

/** Creates a CIMMethod object with the specified name and other input parameters.

/** Creates a CIMMethod object with the specified name and other input attributes.

@param name CIMName defining the name for the method.

@param type CIMType defining data type of the method to be created.

@param type CIMType defining method return data type.

@param classOrigin (optional) CIMName representing the class origin. Note

that this should normally not be used. If not provided set to

Line 136

Line 135

@param propagated Optional flag indicating whether the definition of the

CIM Method is local to the CIM Class (respectively, Instance) in which

it appears, or was propagated without modification from the a

Superclass. Default is false.

Superclass. Default is false. Note that this attribute is normally

not set by CIM Clients but is used internally within the CIM

Server.

Example:

<pre>

CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

Line 148

Line 149

const CIMName& classOrigin = CIMName(),

Boolean propagated = false);

/** Destructor for the CIMMethod. Since this is a shared class, the destructor

/** Destructor for the CIMMethod. The shared data copy remains valid until

only releases when there are no more objects pointing to the representation

all referring objects are destructed

of this object.

{@link Shared Classes}

~CIMMethod();

/** The assignment operator assigns one CIM method to another. This method performs

/** The assignment operator assigns one CIM method to another.

the assignment by incrementing the reference count for the representation of

After the assignment, both CIMMethod objects refer to the same

the CIMMethod, not by creating a deep copy of the object.

data copy; a distinct copy is not created.

Example:

<pre>

CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

CIMMethod m2 = m1;

CIMMethod m2;

m2 = m1;

</pre>

CIMMethod& operator=(const CIMMethod& x);

Line 176

Line 179

const CIMName& getName() const;

/** Sets the method name.

@param name - CIMName for the method name. Replaces any

@param name CIMName for the method name. Replaces any

previously defined name for this method object.

Example:

<pre>

Line 186

Line 189

void setName(const CIMName& name);

/** Gets the method type.

/** Gets the method return data type.

@return The CIMType containing the method type for this method.

@return CIMType containing the method return data type for this

This is the type returned as the return value of a method operation.

method.

@exception Throws UnitializedObjectException if object is not

initialized.

Example:

<pre>

CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

Line 197

Line 202

CIMType getType() const;

/** Sets the method type to the specified CIM method type

/** Sets the method return data type to the specified CIMtype.

as defined in CIMType. This is the type of the CIMValue

This is the type of the CIMValue

that is returned on a CIMMethod operation

that is returned on a CIM method invocation

@param type CIMType to be set into the method object.

@param type CIMType to be set into the CIMMethod object.

@exception Throws UnitializedObjectException if object is not

initialized.

Example:

<pre>

CIMMethod m1();

Line 211

Line 218

void setType(CIMType type);

/** Gets the class in which this method was defined. This information

is available after the class containing the method has been

is normally available with methods that are part of classes and

resolved and is part of the class repository.

instances returned from a CIM Server.

@return CIMName containing the classOrigin field.

const CIMName& getClassOrigin() const;

/** Sets the ClassOrigin attribute with the classname defined on

the input parameter. Normally this function is used internally

the input parameter. Normally this method is used internally

as part of the use objects containing methods (classes

and instances) in a context such as a repository.

and instances) in the context of the CIM Server.

@param classOrigin - CIMName parameter defining the name

@param classOrigin CIMName parameter defining the name

of the class origin.

@exception Throws UnitializedObjectException if object is not

initialized.

void setClassOrigin(const CIMName& classOrigin);

/** Tests the propagated qualifier. The propagated attribute

/** Tests the propagated attribute of the object. The propagated attribute

indicates if this method was propagated from a higher level

class. Normally this attribute is set as part of putting

classes into the repository (resolving the class). It is

Line 236

Line 245

Boolean getPropagated() const;

/** Sets the Propagaged Qualifier. Normally this is used by the functions

/** Sets the Propagated qualifier. Normally this is used by the functions

that resolve classes and instances as part of the installation into

a repository.

@param propagated Flag indicating method is propagated from superclass propagation.

True means that the method was propagated from superclass.

@exception Throws UnitializedObjectException if object is not

initialized.

void setPropagated(Boolean propagated);

/** Adds the specified qualifier to the method and increments the

/** Adds the specified qualifier to the CIMmethod object.

qualifier count.

@param x CIMQualifier object representing the qualifier

to be added.

@return the CIMMethod object after adding the specified qualifier.

@return The CIMMethod object after adding the specified qualifier.

@exception AlreadyExistsException if the qualifier already exists.

@exception Throws AlreadyExistsException if the qualifier already exists.

Example:

<pre>

CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

Line 260

Line 270

/** Searches for a qualifier with the specified input name.

@param name CIMName of the qualifier to be found.

@return Index of the qualifier found or PEG_NOT_FOUND

@return Zero origin index of the qualifier found or PEG_NOT_FOUND

if not found.

@exception Throws UnitializedObjectException if object is not

initialized.

Example:

<pre>

CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

Line 272

Line 284

Uint32 findQualifier(const CIMName& name) const;

/** Gets the CIMQualifier defined by the input parameter.

@param index Index of the qualifier requested.

@param index Zero origin index of the qualifier requested.

@return CIMQualifier object representing the qualifier found.

@exception IndexOutOfBoundsException exception if the index is

@exception Throws IndexOutOfBoundsException exception if the index is

outside the range of parameters available from the CIMMethod.

Example:

<pre>

Line 290

Line 302

/** Gets the CIMQualifier defined by the input parameter.

@param index Index of the qualifier requested.

@return CIMConstQualifier object representing the qualifier found.

@exception IndexOutOfBoundsException exception if the index is

@exception Throws IndexOutOfBoundsException exception if the index is

outside the range of parameters available from the CIMMethod.

Example:

<pre>

Line 306

Line 318

/** Removes the specified CIMQualifier from this method.

@param index Index of the qualifier to remove.

@exception IndexOutOfBoundsException exception if the index is

@exception Throws IndexOutOfBoundsException exception if the index is

outside the range of parameters available from the CIMMethod.

Example:

<pre>

// remove all qualifiers from a class

Uint32 count = 0;

while((count = cimClass.getQualifierCount()) > 0)

cimClass.removeQualifier(count - 1);

</pre>

void removeQualifier(Uint32 index);

/** Returns the number of Qualifiers attached to this CIMMethod object.

@return the number of qualifiers in the CIM Method.

@return The number of qualifiers attached to the CIM Method.

Example:

<pre>

CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

Line 327

Line 346

@param x CIMParameter to be added to the CIM Method.

@return CIMMethod object after the specified parameter is added.

Example:

@exception Throws UnitializedObjectException if object is not

initialized.

<pre>

CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

m1.addParameter(CIMParameter(CIMName ("ipaddress"), CIMTYPE_STRING));

Line 351

Line 372

/** Gets the parameter defined by the specified index.

@param index Index for the parameter to be returned.

@return CIMParameter object requested.

@exception IndexOutOfBoundsException if the index is outside

@exception Throws IndexOutOfBoundsException if the index is outside

the range of available parameters.

Example:

<pre>

Line 363

Line 384

/** Gets the parameter defined for the specified index.

@param index Index for the parameter to be returned.

@return CIMConstParameter object requested.

@exception IndexOutOfBoundsException if the index is outside

@exception Throws IndexOutOfBoundsException if the index is outside

the range of available parameters

CIMConstParameter getParameter(Uint32 index) const;

/** Removes the CIMParameter defined by the specified index.

@param index Index of the parameter to be removed.

@exception IndexOutOfBoundsException if the index is outside the

@exception Throws IndexOutOfBoundsException if the index is outside the

range of parameters available from the CIMMethod.

void removeParameter (Uint32 index);

Line 381

Line 402

Uint32 getParameterCount() const;

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

@return True if the object has not been initialized,

@return True if the object has not been initialized;

false otherwise false.

otherwise false.

Example:

<pre>

CIMMethod m1;

assert(m1.isUnitialized());

</pre>

Boolean isUninitialized() const;

/** Compares with another CIMConstMethod.

/** Compares with a CIMConstMethod.

@param x CIMConstMethod object for the method to be compared.

@return true if this method is identical to the one specified.

@return True if this method is identical to the one specified.

Example:

<pre>

CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

CIMMethod m2(CIMName ("test"), CIMTYPE_STRING);

CIMConstMethod m2(CIMName ("test"), CIMTYPE_STRING);

assert(!m1.identical(m2));

</pre>

Line 401

Line 427

/** Makes a clone (deep copy) of this method. This creates

a new copy of all of the components of the method including

parameters and qualifiers.

@return copy of the CIMMethod object.

@return Independent copy of the CIMMethod object.

CIMMethod clone() const;

Line 427

Line 453

constructors, (for example: getter methods) and the destructor.

REVIEWERS: ATTN: Complete the explanation of why.

@see CIMMethod()

class PEGASUS_COMMON_LINKAGE CIMConstMethod

{

public:

/** Creates a new default CIMConstMethod object.

/** Creates a new empty CIMConstMethod object.

@see CIMMethod()

CIMConstMethod();

/// @see CIMMethod()

/** Creates a new CIMConstMethod object from another CIMConstMethod object.

The new CIMMethodObject references the same copy of data as teh specified object,

no copy is made.

@param x CIMMethod object from which to create the newCIMMethod object.

<pre>

CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

const CIMMethod cm1(m1);

</pre>

{@link Shared Classes}

CIMConstMethod(const CIMConstMethod& x);

/** Creates a new CIMConstMethod object from an

Line 448

Line 484

CIMConstMethod(const CIMMethod& x);

///

/** Creates a CIMConstMethod object with the specified name and other input attributes.

@param name CIMName defining the name for the method.

@param type CIMType defining method return data type.

@param classOrigin (optional) CIMName representing the class origin. Note

that this should normally not be used. If not provided set to

CIMName() (Null name).

@param propagated Optional flag indicating whether the definition of the

CIM Method is local to the CIM Class (respectively, Instance) in which

it appears, or was propagated without modification from the a

Superclass. Default is false. Note that this attribute is normally

not set by CIM Clients but is used internally within the CIM

Server.

Example:

<pre>

CIMConstMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

</pre>

CIMConstMethod(

const CIMName& name,

CIMType type,

const CIMName& classOrigin = CIMName(),

Boolean propagated = false);

/// destructor. CIMMethod objects are destroyed when

/** Destructor for the CIMConstMethod. The shared data copy remains valid until

all referring objects are destructed

{@link Shared Classes}

~CIMConstMethod();

/** assigns one CIMMethod object to another. Because this

/** The assignment operator assigns one CIMConstMethod object to another.

is a shared class, an assignment does not create a copy to

After the assignment, both CIMMethod objects refer to the same

the assigned object but sets a refernce in the assigned object

data copy; a distinct copy is not created.

to the same object as the CIMMethod object that was assigned.

Note that the return is really CIMConstMethod, not CIMMethod to

prevent unplanned modification of the object

@param x CIMMethod object that is to be assigned to another

CIMMethod object.

Example:

<pre>

CIMMethod cm1("putthing");

CIMConstMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

CIMConstMethod m2;

m2 = m1;

</pre>

CIMConstMethod& operator=(const CIMConstMethod& x);

/// assignment operator.

/** The assignment operator assigns a CIMMethod object to a

CIMConstMethod.

After the assignment, both objects refer to the same

data copy; a distinct copy is not created.

Example:

<pre>

CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

CIMConstMethod m2;

m2 = m1;

</pre>

CIMConstMethod& operator=(const CIMMethod& x);

/** gets CIMMethod name. Operation is the same as

/** Gets the name of the method.

CIMMethod getName().

@return CIMName with the name of the method.

@see CIMMethod

Example:

<pre>

CIMConstMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

assert(m1.getName() == CIMName ("getHostName"));

</pre>

const CIMName& getName() const;

/** gets CIMMethod CIMType. Functions the same as

/** Gets the method return data type.

CIMMethod getType();

@return CIMType containing the method return data type for this

@see CIMMethod

method.

Example:

<pre>

CIMConstMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

assert(m1.getType() == CIMTYPE_STRING);

</pre>

CIMType getType() const;

/** gets ClassOrigin attribute. Functions the same

/** Gets the class in which this method was defined. This information

as CIMMethod getClassOrigin()

is normally available with methods that are part of classes and

@see CIMMethod

instances returned from a CIM Server.

@return CIMName containing the classOrigin field.

const CIMName& getClassOrigin() const;

/** gets Propagated attribute. Functions the same

/** Tests the propagated attribute of the object. The propagated attribute

as CIMMethod getPropagated()

indicates if this method was propagated from a higher level

@see CIMMethod

class. Normally this attribute is set as part of putting

classes into the repository (resolving the class). It is

available on methods in classes read from the repository and

on instances that are read from the instance repository.

@return True if method is propagated; otherwise,false.

Boolean getPropagated() const;

/** finds qualifier based on name. Functions the

/** Searches for a qualifier with the specified input name.

same as the CIMMethod findQualifier() method.

@param name CIMName of the qualifier to be found.

@return Index of the qualifier found or PEG_NOT_FOUND

@see CIMMethod

if not found.

Example:

<pre>

CIMConstMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

m1.addQualifier(CIMQualifier(CIMName ("stuff"), true));

assert(m1.findQualifier(CIMName ("stuff")) != PEG_NOT_FOUND);

</pre>

Uint32 findQualifier(const CIMName& name) const;

/** gets qualifier based on index. Functions the

/** Gets the CIMQualifier defined by the input parameter.

same as the CIMMethod getQualifier() method.

@param index Index of the qualifier requested.

@see CIMMethod

@return CIMQualifier object representing the qualifier found.

@exception Throws IndexOutOfBoundsException exception if the index is

outside the range of parameters available from the CIMMethod.

Example:

<pre>

CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

m1.addQualifier(CIMQualifier(CIMName ("stuff"), true));

Uint32 posQualifier;

posQualifier = m1.findQualifier(CIMName ("stuff"));

CIMQualifier q = m1.getQualifier(posQualifier);

</pre>

CIMConstQualifier getQualifier(Uint32 index) const;

/** gets qualifier count based on name. Functions the

/** Returns the number of Qualifiers attached to this CIMMethod object.

same as the CIMMethod getQualifierCount() method.

@return The number of qualifiers in the CIM Method.

@see CIMMethod

Example:

<pre>

CIMConstMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

assert(m1.getQualifierCount() == 0);

</pre>

Uint32 getQualifierCount() const;

/** finds method parameter based on name. Functions the

/** Finds the parameter with the specified name.

same as the CIMMethod findParameter() method.

@param name CIMName of parameter to be found.

@see CIMMethod

@return Index of the parameter object found or PEG_NOT_FOUND

if the property is not found.

Example:

<pre>

Uint32 posParameter;

posParameter = m1.findParameter(CIMName ("ipaddress"));

if (posParameter != PEG_NOT_FOUND)

...

</pre>

Uint32 findParameter(const CIMName& name) const;

/** gets method parameter based on index. Functions the

/** Gets the parameter defined by the specified index.

same as the CIMMethod getParameter() method.

@param index Index for the parameter to be returned.

@see CIMMethod

@return CIMParameter object requested.

@exception Throws IndexOutOfBoundsException if the index is outside

the range of available parameters.

Example:

<pre>

CIMConstParameter cp = m1.getParameter(m1.findParameter(CIMName ("ipaddress")));

</pre>

CIMConstParameter getParameter(Uint32 index) const;

/** finds method parameter count based on name. Functions the

/** Gets the count of Parameters defined in the CIMMethod.

same as the CIMMethod getParameterCount() method.

@return Count of the number of parameters attached to the CIMMethod.

@see CIMMethod

Uint32 getParameterCount() const;

/** Determines if CIMMethod is unitinitialized. Functions the

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

same as corresponding funtion in CIMMethod class.

@return True if the object has not been initialized;

@see CIMMethod

otherwise false.

Boolean isUninitialized() const;

/** Determines if CIMMethod is identical to object define in parameter.

/** Compares with a CIMConstMethod.

Functions the same as corresponding funtion in CIMMethod class.

@param x CIMConstMethod object for the method to be compared.

@see CIMMethod

@return True if this method is identical to the one specified.

Example:

<pre>

CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);

CIMConstMethod m2(CIMName ("test"), CIMTYPE_STRING);

assert(!m1.identical(m2));

</pre>

Boolean identical(const CIMConstMethod& x) const;

/** clones a CIMMethod object by making a deep copy. Functions the

/** Makes a clone (deep copy) of this CIMConstmethod. This creates

same as corresponding funtion in CIMMethod class.

a new copy of all of the components of the method including

@see CIMMethod

parameters and qualifiers.

@return Independent copy of the CIMConstMethod object. Note that

it is returned as a CIMMethod, not const.

CIMMethod clone() const;

Legend:

Removed from v.1.40
changed lines
	Added in v.1.41

No CVS admin address has been configured