cqlselectstatement.h

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

//%2006////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
// Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
// Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
// IBM Corp.; EMC Corporation, The Open Group.
// Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
// IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
// Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
// EMC Corporation; VERITAS Software Corporation; The Open Group.
// Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
// EMC Corporation; Symantec Corporation; The Open Group.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to
// deal in the Software without restriction, including without limitation the
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
// sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
// 
// THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
// ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
// "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
// LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
// PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
// ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
//
//==============================================================================
//
// Authors: David Rosckes ([e-mail])
//          Bert Rivero ([e-mail])
//          Chuck Carmack ([e-mail])
//          Brian Lucier ([e-mail])
//
// Modified By: David Dillard, VERITAS Software Corp.
//                  ([e-mail])
//
//%/////////////////////////////////////////////////////////////////////////////

#ifndef Pegasus_CQLSelectStatement_h
#define Pegasus_CQLSelectStatement_h

#include <Pegasus/CQL/Linkage.h>
#include <Pegasus/Common/AutoPtr.h>
#include <Pegasus/Query/QueryCommon/SelectStatement.h>
#include <Pegasus/CQL/CQLChainedIdentifier.h>
#include <Pegasus/CQL/CQLPredicate.h>
#include <Pegasus/CQL/CQLIdentifier.h>


#ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES

PEGASUS_NAMESPACE_BEGIN

class CQLSelectStatementRep;

/**
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).
*/
class PEGASUS_CQL_LINKAGE CQLSelectStatement : public SelectStatement
{
  public:

    /**
      Constructs a CQLSelectStatement default object.

      @param  - None.
      @return - None.
      @throw  - None.

      <I><B>Experimental Interface</B></I><BR>
    */
    CQLSelectStatement();

    /**
      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.

      <I><B>Experimental Interface</B></I><BR>
    */
    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.

      <I><B>Experimental Interface</B></I><BR>
    */
    CQLSelectStatement(String& inQLang, String& inQuery);

    /**
      Copy constructs a CQLSelectStatement object.

      @param  statement - CQLSelectStatement to be copied.
      @return - None.
      @throw  - None.

      <I><B>Experimental Interface</B></I><BR>
    */
    CQLSelectStatement(const CQLSelectStatement& statement);

    /**
      Destructs a CQLSelectStatement object.

      @param  - None.
      @return - None.
      @throw  - None.

      <I><B>Experimental Interface</B></I><BR>
    */
    ~CQLSelectStatement();

    /**
      Assigns a CQLSelectStatement to this object.

      @param rhs - CQLSelectStatement to be assigned to this object.
      @return - Updated this object.
      @throw  - None.

      <I><B>Experimental Interface</B></I><BR>
    */
    CQLSelectStatement& operator=(const CQLSelectStatement& rhs);

    /**
      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.

      <I><B>Experimental Interface</B></I><BR>
     */
    void applyContext();

    /**
      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.

      <I><B>Experimental Interface</B></I><BR>
    */
    Boolean evaluate(const CIMInstance& inCI);

    /**
      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.
      @param allowMissing indicates whether missing project properties are
                          allowed
      @return None
      @throw  CQLRuntimeException if the instance cannot be projected
      @throw CQLValidationException for applyContext error.
      @throw CQLSyntaxErrorException for applyContext error.

      <I><B>Experimental Interface</B></I><BR>
    */
    void applyProjection(CIMInstance& inCI, Boolean allowMissing);

    /**
      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.

      <I><B>Experimental Interface</B></I><BR>
    */
    void validate();

    /**
      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

      <I><B>Experimental Interface</B></I><BR>
     */
    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.