pegasus/src/Pegasus/CQL/CQLSelectStatement.h - diff

Return to CQLSelectStatement.h CVS log

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

Diff for /pegasus/src/Pegasus/CQL/CQLSelectStatement.h between version 1.2 and 1.3

version 1.2, 2004/11/21 12:13:07

version 1.3, 2004/11/29 20:06:57

Line 54

This class is derived from the SelectStatement base class.

The purpose of this class is to perform the select statement operations for

CIM Query Language (CQL).

Notes on CQLSelectStatement class:

(A) Contains a CQLPredicate for the WHERE clause

(B) Contains an array of CQLIdentifiers for the SELECT projection

class PEGASUS_CQL_LINKAGE CQLSelectStatement : public SelectStatement

{

public:

CQLSelectStatement();

/** This is the constructor for the CQLSelectStatement object.

/**

The ctor requires 3 parameters:

Constructs a CQLSelectStatement default object.

query language (qlang) which is CQL,

the query itself,

@param - None.

and the name of the CIM namespace.

@return - None.

@throw - None.

CQLSelectStatement(

/** The query language is needed so the

Experimental Interface

base class can retrieve the query language.

The class member variable where this data

is stored is located in the base SelectStatement

class.

String& inQlang,

CQLSelectStatement();

/** input parameter containing the query string.

/**

Constructs a CQLSelectStatement object.

@param inQlang - String containing the language of the query.

@param inQuery - String containing the query.

@param inCtx - Context in which the select statement is running.

@return - None.

@throw - None.

Experimental Interface

CQLSelectStatement(String& inQlang,

String& inQuery,

QueryContext& inCtx);

/**

Constructs a CQLSelectStatement object.

@param inQlang - String containing the language of the query.

@param inQuery - String containing the query.

@return - None.

@throw - None.

Experimental Interface

CQLSelectStatement(String& inQLang, String& inQuery);

/**

Copy constructs a CQLSelectStatement object.

@param statement - CQLSelectStatement to be copied.

@return - None.

@throw - None.

Experimental Interface

CQLSelectStatement(const CQLSelectStatement& statement);

~CQLSelectStatement();

/**

Destructs a CQLSelectStatement object.

CQLSelectStatement& operator=(const CQLSelectStatement& rhs);

@param - None.

@return - None.

@throw - None.

Experimental Interface

~CQLSelectStatement();

void setQueryContext(QueryContext& inCtx);

/**

Assigns a CQLSelectStatement to this object.

/** Implements the evaluate method from the

@param rhs - CQLSelectStatement to be assigned to this object.

base SelectStatement class.

@return - Updated this object.

@throw - None.

Experimental Interface

Boolean evaluate(

CQLSelectStatement& operator=(const CQLSelectStatement& rhs);

/** The CIM instance that will be evaluated.

The CIMInstance object is not modified by this method.

/**

Applies the class contexts from the FROM list to the

chained identifiers in the statement. This will transform

each chained identifier into a normalized form. The FROM

classname is prepended if needed, and all class aliases are resolved.

Note: there are cases where the FROM classname is not prepended.

This can occur for the classname on the right side of ISA,

or the classname at the beginning of a symbolic constant chained

identifier. Neither of these classnames need to be the FROM class.

This function also validates that each chained identifier

is well-formed. It is possible for a chained identifier

to be syntactically correct in the CQL language, but

cannot be processed by the CQL engine.

Pre-condition: QueryContext has been set into this object.

Post-condition: Chained identifiers have been normalized.

@param None.

@return None

@throw CQLRuntimeException if the QueryContext had not been set.

@throw CQLValidationException if a chained identifier is not well formed.

@throw CQLSyntaxErrorException if a chained identifier is not well formed.

Experimental Interface

const CIMInstance& inCI);

void applyContext();

/** Implements the applyProjection method from the

/**

base SelectStatement class.

Evaluates the WHERE clause of the select statement using

a CIM instance as the source of properties.

Pre-condition: QueryContext has been set into this object.

Post-condition: Chained identifiers have been normalized

ie.applyContext has been called. See the applyContext function.

@param inCI - The instance to be evaluated.

@return True, if the WHERE clause evaluates to true based on

the type of the instance and its properties.

@throw CQLRuntimeException if the instance cannot be evaluated

@throw CQLValidationException for applyContext error.

@throw CQLSyntaxErrorException for applyContext error.

Experimental Interface

void applyProjection(

Boolean evaluate(const CIMInstance& inCI);

/** Input the CIMInstance object in which to apply the

projection.

/**

Projects the properties in the SELECT list of the select

statement onto the instance. This involves checking that

all required properties exist on the instance passed in,

and removing any unneeded properties from that instance.

Pre-condition: QueryContext has been set into this object.

Post-condition: Chained identifiers have been normalized

ie.applyContext has been called. See the applyContext function.

@param inCI - The instance to be projected.

@return None

@throw CQLRuntimeException if the instance cannot be projected

@throw CQLValidationException for applyContext error.

@throw CQLSyntaxErrorException for applyContext error.

Experimental Interface

CIMInstance& inCI) throw(Exception);

void applyProjection(CIMInstance& inCI) throw(Exception);

/** Implements the validatedProperties method from the

/**

base SelectStatement class.

Validates the classes and properties used in the select statement

against the class schema. The existence of classes and properties

are checked, along with class relationships defined in the CQL

specification.

Pre-condition: QueryContext has been set into this object.

Post-condition: Chained identifiers have been normalized

ie.applyContext has been called. See the applyContext function.

@param None

@return None

@throw CQLValidationException for applyContext error, the select

statement is invalid against the schema, or the QueryContext has

not been set.

@throw CQLSyntaxErrorException for applyContext error.

Experimental Interface

void validate() throw(Exception);

/** Returns an array of CIMObjectPath objects that are the

/**

class paths from the select statement in the FROM list.

Normalizes the predicates in the WHERE clause to a

disjunction of conjunctions.

Post-condition: Chained identifiers have been normalized

ie.applyContext has been called. See the applyContext function.

@param None

@return None

@throw None

Experimental Interface

void normalizeToDOC();

/**

Returns an array of CIMObjectPath objects that are the

class paths in the FROM list of the select statement.

Note: Currently CQL only supports one class path in the

FROM list. This class path does not support WBEM-URI, so that

only the namespace and classname parts are filled in.

Pre-condition: QueryContext has been set into this object.

@param None

@return Array of FROM list class paths.

@throw CQLRuntimeException if the QueryContext had not been set.

Experimental Interface

Array<CIMObjectPath> getClassPathList();

/** Returns the required properties from the combined SELECT and WHERE

/**

clauses for the classname passed in.

Returns the required properties from the combined SELECT and WHERE

clauses for the classname passed in. The classname parameter is

needed in case scoping operators are used in the select statement.

This function does not return properties for the classname if they

are required on embedded objects. This function does not return

required array indices.

Pre-condition: QueryContext has been set into this object.

Post-condition: Chained identifiers have been normalized

ie.applyContext has been called. See the applyContext function.

@param inClassName - class to determine the required properties. Defaults

to the FROM class.

@return CIMPropertyList containing the required properties for the class.

If all the properties are required, a null CIMPropertyList is returned.

If no properties are required, an empty CIMPropertyList is returned.

@throw CQLRuntimeException if the QueryContext had not been set.

@throw CQLValidationException for applyContext error.

@throw CQLSyntaxErrorException for applyContext error.

If all the properties for the input classname are required, a null

Experimental Interface

CIMPropertyList is returned.

CIMPropertyList getPropertyList(

CIMPropertyList getPropertyList(const CIMObjectPath& inClassName = CIMObjectPath());

/** The input parameter className is one of the

classes from the FROM list.

/**

Returns the required properties from the SELECT clause for the

classname passed in. The classname parameter is needed in case

scoping operators are used in the select statement. This function

does not return properties for the classname if they are required

on embedded objects. This function does not return required array indices.

Pre-condition: QueryContext has been set into this object.

Post-condition: Chained identifiers have been normalized

ie.applyContext has been called. See the applyContext function.

@param inClassName - class to determine the required properties. Defaults

to the FROM class.

@return CIMPropertyList containing the required properties for the class.

If all the properties are required, a null CIMPropertyList is returned.

If no properties are required, an empty CIMPropertyList is returned.

@throw CQLRuntimeException if the QueryContext had not been set.

@throw CQLValidationException for applyContext error.

@throw CQLSyntaxErrorException for applyContext error.

Experimental Interface

const CIMObjectPath& inClassName = CIMObjectPath());

CIMPropertyList getSelectPropertyList(const CIMObjectPath& inClassName = CIMObjectPath());

CIMPropertyList getSelectPropertyList(

/**

const CIMObjectPath& inClassName = CIMObjectPath());

Returns the required properties from the WHERE clause for the

classname passed in. The classname parameter is needed in case

scoping operators are used in the select statement. This function

does not return properties for the classname if they are required

on embedded objects. This function does not return required array indices.

Pre-condition: QueryContext has been set into this object.

Post-condition: Chained identifiers have been normalized

ie.applyContext has been called. See the applyContext function.

@param inClassName - class to determine the required properties. Defaults

to the FROM class.

@return CIMPropertyList containing the required properties for the class.

If all the properties are required, a null CIMPropertyList is returned.

If no properties are required, an empty CIMPropertyList is returned.

@throw CQLRuntimeException if the QueryContext had not been set.

@throw CQLValidationException for applyContext error.

@throw CQLSyntaxErrorException for applyContext error.

Experimental Interface

CIMPropertyList getWherePropertyList(const CIMObjectPath& inClassName = CIMObjectPath());

CIMPropertyList getWherePropertyList(

/**

const CIMObjectPath& inClassName = CIMObjectPath());

Returns the chained identifiers from the SELECT clause. These chained

identifiers contain the fully qualified property names, including embedded

objects, array indices, scoping operators, and symbolic constants.

Post-condition: Chained identifiers have been normalized

ie.applyContext has been called. See the applyContext function.

@param None

@return Array of chained identifiers.

@throw CQLValidationException for applyContext error.

@throw CQLSyntaxErrorException for applyContext error.

Experimental Interface

Array<CQLChainedIdentifier> getSelectChainedIdentifiers();

Array<CQLChainedIdentifier> getWhereChainedIdentifiers();

/**

Returns the chained identifiers from the WHERE clause. These chained

identifiers contain the fully qualified property names, including embedded

objects, array indices, scoping operators, and symbolic constants.

Pre-condition: QueryContext has been set into this object.

Post-condition: Chained identifiers have been normalized

ie.applyContext has been called. See the applyContext function.

@param None

@return Array of chained identifiers.

@throw CQLRuntimeException if the QueryContext had not been set.

@throw CQLValidationException for applyContext error.

@throw CQLSyntaxErrorException for applyContext error.

/** Modifier. This method should not be called by the user (only by the

Experimental Interface

parser).

Appends a CQLIdentifier to an array of CIMObjectPaths from the FROM

statement.

void appendClassPath(

Array<CQLChainedIdentifier> getWhereChainedIdentifiers();

/**

Gets the top-level CQLPredicate of this object.

const CQLIdentifier& inIdentifier);

This is the predicate that contains the top-level

of any nested boolean operations in the WHERE clause.

@param None.

@return Top-level predicate

@throw None.

/** Sets a predicate into this object. This method should only

Experimental Interface

be called by Bison.

void setPredicate(const CQLPredicate& inPredicate);

/** Gets the top-level predicate contained by this object */

CQLPredicate getPredicate() const;

/** This method calls QueryContext::insertClassPathAlias() to insert a

/**

classpath-alias pair

Determines whether the select statement has a WHERE clause.

into the hash table. The record is keyed by the class alias.

This method is used by Bison.

@param None

@return True if there is a WHERE clause.

@throw None

TODO: think about exceptions such as duplicate key.

Experimental Interface

void insertClassPathAlias(

Boolean hasWhereClause();

/** The CQLIdentifier object that contains the class path.

/**

Returns the select statement in string form.

Note that this can be different than the original

statement after it has been parsed, and applyContext

has been called.

Pre-condition: QueryContext has been set into this object.

@param None

@return String containing the select statement.

@throw

Experimental Interface

String toString();

ATTN - the following methods should only be set by CQLParser.

These should be made private, and CQLParser made a friend.

const CQLIdentifier& inIdentifier,

/** The alias for the class.

/**

Appends a CQLIdentifier/alias combination into the FROM list of the

statement. This method should only be called by the CQL parser.

@param inIdentifier - CQLIdentifier to append.

@param inAlias - Alias of the identifier.

@return None

@throw QueryException if the identifier/alias cannot be appended.

Experimental Interface

void insertClassPathAlias(const CQLIdentifier& inIdentifier,

String inAlias);

/** Appends a CQL chained identifier to the CQL identifier list. The user

/**

should

Appends a CQLIdentifier into the FROM list of the statement.

not call this method; it should only be called by the Bison.

This method should only be called by the CQL parser.

@param inIdentifier - CQLIdentifier to append.

@return None

@throw QueryException if the identifier cannot be appended.

Experimental Interface

void appendSelectIdentifier(const CQLChainedIdentifier& x);

void appendClassPath(const CQLIdentifier& inIdentifier);

/**

Applies the class contexts from the FROM list to the identifiers

Appends a CQLChainedIdentifier to the select list.

in the statement.

This method should only be called by the CQL parser.

@param x - CQLChainedIdentifier to append.

@return None

@throw None

Experimental Interface

void applyContext();

void appendSelectIdentifier(const CQLChainedIdentifier& x);

/** Sets a predicate into this object. This method should only

be called by Bison.

/**

Normalizes the WHERE clause to disjunction of conjunctions.

Sets the top-level CQLPredicate into this object.

This method should only be called by the CQL parser.

@param Predicate to set into this object.

@return None

@throw None.

Experimental Interface

void normalizeToDOC();

void setPredicate(const CQLPredicate& inPredicate);

/**

Sets the select statement to have a WHERE clause.

This method should only be called by the CQL parser.

@param None

@return None

@throw None

Experimental Interface

void setHasWhereClause();

Boolean hasWhereClause();

/**

Clears the internal data structures.

This method should only be called by the CQL parser.

String toString();

Pre-condition: QueryContext has been set into this object.

@param None

@return None.

@throw CQLRuntimeException if the QueryContext had not been set.

Experimental Interface

void clear();

private:

Legend:

Removed from v.1.2
changed lines
	Added in v.1.3

No CVS admin address has been configured