NdbQueryOperation.hpp

/*
   Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; version 2 of the License.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA */

#ifndef NdbQueryOperation_H
#define NdbQueryOperation_H

#include <ndb_types.h>

// this file is currently not located in include/ndbapi
// which means that we need to use <> to include instead of ""
// for files located in include/ndbapi

// this file is currently not located in include/ndbapi
// skip includes...and require them to be included first
// BUH!

/* There is no way to forward declare nested class NdbDictionary::Column,
 * so this header file must be included.*/
// #include <NdbDictionary.hpp>

// Needed to get NdbQueryOptions::ScanOrdering.
// #include "NdbQueryBuilder.hpp"
// #include <NdbIndexScanOperation.hpp>


class Ndb;
struct NdbError;
class NdbParamOperand;
class NdbQueryOperation;
class NdbQueryOperationDef;
class NdbRecAttr;
class NdbTransaction;
class NdbRecord;
class NdbInterpretedCode;

class NdbQueryImpl;
class NdbQueryOperationImpl;


/**********************  OVERVIEW    ***********************
 *
 * a NdbQuery is created when a NdbQueryDefinition is added to a
 * NdbTransaction for execution with NdbTransaction::creatQuery().
 *
 * A NdbQuery is associated with a collection of NdbQueryOperation which 
 * are instantiated (1::1) to reflect the NdbQueryOperationDef objects
 * which the NdbQueryDef consists of. The same NdbQueryDef may be used to
 * instantiate multiple NdbQuery obejects.
 *
 * When we have an instantiated NdbQuery, we should either bind result buffers
 * for retrieving entire rows from each operation, 
 * (aka NdbRecord interface,::setResultRowRef(), ::setResultRowBuf())
 * or set up retrieval operations for each attribute values, (::getValue()).
 * 
 * Optionally we may also:
 *  - Specify a scan ordering for the result set (parent only)
 *  - Add multiple bounds to a range scan, (::setBound()) (parent only)
 *  - Append a filter condition for each operation (aka mysqlds pushed condition)  
 *
 * The NdbQuery is then executed together with other pending operations 
 * in the next NdbTransaction::execute().
 * The resultset available from a NdbQuery is natively a 'left outer join'
 * between the parent / child operations. If an application is not interested
 * in the 'outer part' of the resultset, it is its own responsibility to
 * filter these rows. Same is valid for any filter condition which has
 * not been appended to the NdbQuery.
 *
 *
 * We provide two different interfaces for iterating the result set:
 *
 * The 'local cursor' (NdbQueryOperation::firstResult(), ::nextResult())
 *   Will navigate the resultset, and fetch results, from this specific operation.
 *   It will only be possible to navigate within those rows which depends
 *   on the current row(s) from any ancestor of the operation.
 *   The local cursor will only retrieve the results, or a NULL row, 
 *   resulting from its own operation. -> All child operations of a 
 *   renavigated local cursor should be navigated to ::firstResult() 
 *   to ensure that they contain results related to the renavigated parent. 
 *   
 * The 'global cursor' (NdbQuery::nextResult())
 *   Will present the result set as a scan on the root operation
 *   with rows from its child operations appearing in an unpredictable 
 *   order. A new set of results, or NULL rows, from *all* operations 
 *   in the query tree are retrieved for each ::nextResult().
 *   NULL rows resulting from the outer joins may appear anywhere 
 *   inside the resultset.
 *
 * As the global cursor is implemented on top of the local cursors, it is
 * possible to mix the usage of global and local cursors.
 *
 ************************************************************************/
class NdbQuery
{
private:
  // Only constructable through ::buildQuery() 
  friend class NdbQueryImpl;
  explicit NdbQuery(NdbQueryImpl& impl);
  ~NdbQuery();

public:
  enum NextResultOutcome{
    NextResult_error = -1,
    NextResult_gotRow = 0,
    NextResult_scanComplete = 1,
    NextResult_bufferEmpty = 2
  };

  Uint32 getNoOfOperations() const;

  // Get a specific NdbQueryOperation by ident specified
  // when the NdbQueryOperationDef was created.
  NdbQueryOperation* getQueryOperation(const char* ident) const;
  NdbQueryOperation* getQueryOperation(Uint32 index) const;
//NdbQueryOperation* getQueryOperation(const NdbQueryOperationDef* def) const;

  Uint32 getNoOfParameters() const;
  const NdbParamOperand* getParameter(const char* name) const;
  const NdbParamOperand* getParameter(Uint32 num) const;

  int setBound(const NdbRecord *keyRecord,
               const struct NdbIndexScanOperation::IndexBound *bound);

  NextResultOutcome nextResult(bool fetchAllowed = true, 
                               bool forceSend = false);

  NdbTransaction* getNdbTransaction() const;

  void close(bool forceSend = false);

  const NdbError& getNdbError() const;

  NdbQueryImpl& getImpl() const
  { return m_impl; }

  int isPrunable(bool& pruned) const;

private:
  NdbQueryImpl& m_impl;

}; // class NdbQuery




class NdbQueryOperation
{
private:
  // Only constructable through executing a NdbQueryDef
  friend class NdbQueryOperationImpl;
  explicit NdbQueryOperation(NdbQueryOperationImpl& impl);
  ~NdbQueryOperation();

public:
  // Collection of get'ers to navigate in root, parent/child hierarchy

  Uint32 getNoOfParentOperations() const;
  NdbQueryOperation* getParentOperation(Uint32 parentNo) const;

  Uint32 getNoOfChildOperations() const;
  NdbQueryOperation* getChildOperation(Uint32 childNo) const;

  const NdbQueryOperationDef& getQueryOperationDef() const;

  // Get the entire query object which this operation is part of
  NdbQuery& getQuery() const;



  NdbRecAttr* getValue(const char* anAttrName, char* resultBuffer = 0);
  NdbRecAttr* getValue(Uint32 anAttrId, char* resultBuffer = 0);
  NdbRecAttr* getValue(const NdbDictionary::Column* column, 
                       char* resultBuffer = 0);

  int setResultRowBuf (const NdbRecord *rec,
                       char* resBuffer,
                       const unsigned char* result_mask = 0);

  int setResultRowRef (const NdbRecord* rec,
                       const char* & bufRef,
                       const unsigned char* result_mask = 0);

  // TODO: define how BLOB/CLOB should be retrieved.
  // ... Replicate ::getBlobHandle() from NdbOperation class?

  NdbQueryOperationImpl& getImpl() const
  { return m_impl; }

  int setOrdering(NdbQueryOptions::ScanOrdering ordering);

  NdbQueryOptions::ScanOrdering getOrdering() const;

  int setParallelism(Uint32 parallelism);

  int setMaxParallelism();

  int setAdaptiveParallelism();

  int setBatchSize(Uint32 batchSize);

  int setInterpretedCode(const NdbInterpretedCode& code) const;

  NdbQuery::NextResultOutcome firstResult();

  NdbQuery::NextResultOutcome nextResult(
                               bool fetchAllowed = true, 
                               bool forceSend = false);

  // Result handling for this NdbQueryOperation
  bool isRowNULL() const;    // Row associated with Operation is NULL value?

  bool isRowChanged() const; // Prev ::nextResult() on NdbQuery retrived a new
                             // value for this NdbQueryOperation


private:
  // Opaque implementation class instance.
  NdbQueryOperationImpl& m_impl;

}; // class NdbQueryOperation

 
class NdbQueryParamValue
{
public:

  // Raw data formated according to bound Column format.
  // NOTE: This is how mysqld prepare parameter values!
  NdbQueryParamValue(const void* val, bool shrinkVarChar= false);

  // C-type string, terminated by '\0'
  NdbQueryParamValue(const char* val);

  // NULL-value, also used as optional end marker 
  NdbQueryParamValue();
  NdbQueryParamValue(Uint16 val);
  NdbQueryParamValue(Uint32 val);
  NdbQueryParamValue(Uint64 val);
  NdbQueryParamValue(double val);

  // More parameter C'tor to be added when required:
//NdbQueryParamValue(Uint8 val);
//NdbQueryParamValue(Int8 val);
//NdbQueryParamValue(Int16 val);
//NdbQueryParamValue(Int32 val);
//NdbQueryParamValue(Int64 val);

  int serializeValue(const class NdbColumnImpl& column,
                     class Uint32Buffer& dst,
                     Uint32& len,
                     bool& isNull) const;

private:
  int m_type;

  union
  {
    Uint8     uint8;
    Int8      int8;
    Uint16    uint16;
    Int16     int16;
    Uint32    uint32;
    Int32     int32;
    Uint64    uint64;
    Int64     int64;
    double    dbl;
    const char* string;
    const void* raw;
  } m_value;
};

#endif