data.h

Go to the documentation of this file.

/**************************************************************
 **
 ** @file data/data.h
 **
 ** Copyright (C) 2012  Xpace, LLC.  All rights reserved
 **
 ** www.xpace.net
 **
 **************************************************************/

#ifndef XPACE_DATA_H
#define XPACE_DATA_H

#include "base/types.h"
#include "base/exception.h"
#include "base/config.h"
#include "base/decimalfloat.h"
#include "base/datetime.h"

namespace Xpace
{
  // ================================ DATA TYPES ==============

  class XPACE_EXPORT BaseDataType
  {
  public:
    enum type
    {
      btNone = 0,
      btInt,                 // int
      btUint,                // uint
      btFloat,               // DecimalFloat
      btString8,             // String8
      btString16,            // String16
      btBytes,               // BytesRef
      btEnd
    };

    BaseDataType
     (type t,
      size_t s = 0);         // size for int amd string types only

    explicit
    BaseDataType
      (const String& str,
       size_t s = 0);         // size for int and string types only

    #ifdef XPACE_CONFIG_H
    explicit
    BaseDataType
      (const Configuration& config);
    #endif

    type getBaseType
      ()
      const;

    size_t getSize
      ()
      const;

    virtual String getName
     ()
     const;

    template <typename STR>
    static
    BaseDataType stringType
      ();
    // { return BaseDataType(); }

  protected:
    type ty;
    size_t size;

    BaseDataType
      () :
        ty(btNone),
        size(0)
    {
    }
  };

  class XPACE_EXPORT DerivedDataType : public BaseDataType
  {
  public:
    enum type 
    {
      dtNone = 0,
      dtDateTime = BaseDataType::btEnd,
      dtIPv4,
      dtEnd
    };

    DerivedDataType
      (type,
       size_t size = 0);
    DerivedDataType
      (BaseDataType::type = btNone,
       size_t size = 0);

    explicit
    DerivedDataType
      (const String& str,
       size_t size = 0);

    #ifdef XPACE_CONFIG_H
    explicit
    DerivedDataType
      (const Configuration& config);
    #endif

    type getDerivedType
      ()
      const;

    virtual String getName
      ()
      const;

    bool operator==
      (BaseDataType::type)
      const;

  private:
    type ty;
    static BaseDataType base_type
      (type,
       size_t);
  };

  // ================================ ACCESS ==================

  // pass this when opening a table or store
  enum StoreAccess
  {
    SA_readWrite,
    SA_readOnly,
    SA_bulkWrite
  };

// ================================ SOURCE ====================

  /// A Source is an interface to an object that provides access to each field or column of
  /// a data record or row. A database or table that supports this access
  /// pattern will have a method or methods that returns a Source object or
  /// reference. Note that this class is stateful in the sense that there is a
  /// current record or row. Also note that the lifetime of a Source is bounded by the
  /// lifetime of its creating object, or possibly earlier if an action on the
  /// creator invalidates it.

  /// The non-LOC part of a Source
  /// @param RET type of the return value of moveTo()
  template<typename RET = bool>
  class XPACE_EXPORT SourceBase
  {
  public:
    /// destructor
    virtual ~SourceBase
      ()
    {
    }

    /// Move to another document/row/record
    /// @param targ the new document/row/record number
    /// @return true iff move was successful
    virtual RET moveTo
      (uint64 targ)
    = 0;
  };

  /// @param LOC type of the field or column identifier 
  /// @param RET the return value of the getters
  template<typename LOC, typename RET = bool>
  class XPACE_EXPORT Source : public virtual SourceBase<RET>
  {
  public:
    /// Get the value at a location as an int64
    /// @param location field or column identifier
    /// @retval value recipient of the data
    /// @return true iff the value exists. If false, the contents of value are undefined.
    virtual RET get
      (LOC location,
       int64* value)
      const
    = 0;

    /// Get the value at a location as a DecimalFloat
    /// @param location field or column identifier
    /// @retval value recipient of the data
    /// @return true iff the value exists; if false, the contents of value
    ///   are undefined.
    virtual RET get
      (LOC location,
       DecimalFloat* value)
      const
    = 0;

    /// Get the value at a location as a String8
    /// @param location field or column identifier
    /// @retval value recipient of the data
    /// @return true iff the value exists; if false, the contents of value
    ///   are undefined.
    virtual RET get
      (LOC location,
       String8* value)
      const
    = 0;

    /// Get the value at a location as a String16
    /// @param location field or column identifier
    /// @retval value recipient of the data
    /// @return true iff the value exists; if false, the contents of value
    ///   are undefined.
    virtual RET get
      (LOC location,
       String16* value)
      const
    = 0;

    /// Get the value at a location as a String
    /// @param location field or column identifier
    /// @retval value recipient of the data
    /// @returns true iff the value exists; if false, the contents of value
    ///   are undefined.
    virtual RET get
      (LOC location,
       String* value)
      const
    = 0;

    /// Get the value at a location as a byte array
    /// @param location field or column identifier
    /// @retval value recipient of the data
    /// @return true iff the value exists; if false, the contents of value
    ///   are undefined.
    virtual RET get
      (LOC location,
       BytesRef* value)
      const 
    = 0;
  };

  // ================================ SINK ====================

  /// Sink is an interface to an object that receives data. 
  /// Each data object is allowed to have only one Sink.

  /// Request notification of document/row/record/count (via SinkBase::setCount())
  enum SinkNotifyCount
  {
    SNC_Never,      ///< no count (content comes immediately, retrieval stops when Sink returns false)
    SNC_Continue,   ///<< no count (content comes immediately, retrieval stops when Sink returns false) but keep state for future calls
    SNC_After,      ///< get count after content (content comes immediately; search resolution continues after Sink returns false)
    SNC_Before      ///< get count before content (retrieval is completed before Sink is called)
  };

  /// The non-LOC part of a Sink
  class XPACE_EXPORT SinkBase
  {
  public:
    // destructor
    virtual ~SinkBase
      ()
    {
    }

    /// Inform the Sink how many documents/records/rows to expect
    /// @param docs the number of documents/records/rows
    /// @return true to receive, false to stop
    virtual bool setCount
      (uint64 docs)
    {
      return true;   
    }

    /// Begin a new document/record/row, committing current one (if any)
    /// @param docNum a suggested document
    /// @return -1 to stop, otherwise a document number
    virtual int64 start
      (uint64 docNum)
    {
      return docNum;
    }
    
    /// We're finshed with this Sink
    virtual void close
      ()
    {
    }

  protected:
    SinkBase
      ()
    {
    }

  private:
    SinkBase
      (const SinkBase&);
    SinkBase& operator=
      (const SinkBase&);
  };

  /// @param LOC the location (absolute or relative) of a datum (e.g. table cell or field)
  /// @param RET type of the return value of the functions; usually a bool, true to continue, false to stop
  template<typename LOC, typename RET = bool>
  class XPACE_EXPORT Sink : public virtual SinkBase
  {
  public:
    /// Add a field by name
    /// @param name the name of the field
    /// @param type the type of the field
    /// @param location a proposed location; may be null
    /// @retval added true iff the field or column was added
    /// @returns the actual location, NULL to stop
    virtual LOC add
      (const String& name,
       DerivedDataType type,
       LOC location,
       bool* added = 0) 
    {
      if (added)
        *added = false;
      return location;
    }

    /// Add a field from a Configuration
    /// @param config the configuration of the field
    /// @param location a proposed location; may be null
    /// @retval added true iff the column was added
    /// @returns the actual location, NULL to stop
    virtual LOC add
      (const Configuration& config,
       LOC location,
       bool* added = 0) 
    {
      return add(config.getTag(), DerivedDataType(config), location, added);
    }

    /// Move without setting data
    /// @param location
    /// @returns a RET, usually a bool
    virtual RET move
      (LOC location)
    {
      // optional
      return RET(1);
    }

    /// Write an int64
    /// @param location
    /// @param value
    /// @returns a RET, usually a bool
    virtual RET set
      (LOC location,
       int64 value)
    {
      throw Unimplemented_Error(__FUNCTION__);
    }

    /// Add a DecimalFloat
    /// @param location
    /// @param value
    /// @returns a RET, usually a bool    
    virtual RET set
      (LOC location,
       const DecimalFloat& value)
    {
      throw Unimplemented_Error(__FUNCTION__);
    }

    /// Add a String8
    /// @param location
    /// @param value
    /// @returns a RET, usually a bool
    virtual RET set
      (LOC location,
       const String8& value)
    {
      throw Unimplemented_Error(__FUNCTION__);
    }

    /// Add a String16
    /// @param location
    /// @param value
    /// @returns a RET, usually a bool
    virtual RET set
      (LOC location,
       const String16& value)
    {
      throw Unimplemented_Error(__FUNCTION__);
    }

    /// Add a DateTime
    /// @param location
    /// @param value
    /// @returns a RET, usually a bool
    virtual RET set 
      (LOC location,
       const DateTime& value)
    {
      throw Unimplemented_Error(__FUNCTION__);
    }

    /// Add a BytesRef
    /// @param location
    /// @param value
    /// @returns a RET, usually a bool
    virtual RET set
      (LOC location,
       const BytesRef& value)
    {
      throw Unimplemented_Error(__FUNCTION__);
    }
  };
  
  // ================================ EXCEPTIONS ==============

  /// Thrown when you ask for a type that cannot be converted
  /// E.g., asking for string data as an int64
  /// @param T the to-type
  template <typename T = void>
  class IncompatibleType : public Exception
  {
  public:
    /// @param fromType the actual type in the Table
    /// @param toType the requested type
    IncompatibleType
      (BaseDataType fromType, 
       BaseDataType toType);   
    
    /// @param fromType the actual type in the Table
    ///  NB takes toType from the template param
    IncompatibleType
      (BaseDataType fromType);   
  };

  template <>
  inline IncompatibleType<String8>::IncompatibleType
    (BaseDataType fromType)
  {
    IncompatibleType(fromType, BaseDataType::btString8);
  }

  template <>
  inline IncompatibleType<String16>::IncompatibleType
    (BaseDataType fromType)
  {
    IncompatibleType(fromType, BaseDataType::btString16);
  }

  struct XPACE_EXPORT DataFileTags
  {
    static const char* INPUT_TAG();   // input section

    static const char* MAP_TAG;       // how to map the data file (optional) (cf. DT)
    static const char* REFS_TAG;      // high-level structure (optional) (cf. DI)
    static const char* STORE_TAG;     // the actual data store (cf. DD)

    static const char* OVERWRITE_TAG;   // overwrite on re-opening for write
  };

  // ================================ TAGS ====================

  struct BaseDataTags
  {
    static const char* TYPE_TAG;
    static const char* NONE_TAG;
    static const char* SIZE_TAG;
    static const char* INT_TAG;
    static const char* UINT_TAG;
    static const char* FLOAT_TAG;
    static const char* DOUBLE_TAG;
    static const char* STRING_TAG;
    static const char* BYTES_TAG;
  };

  struct DerivedDataTags
  {
    static const char* DATETIME_TAG;
    static const char* IPv4_TAG;
  };

  // ==========================================================
  // ==========================================================
  // ==========================================================

  inline
  BaseDataType::BaseDataType
   (type t,
    size_t s) :
      ty(t),
      size(s)
  {
  }

  template <>
  inline 
  BaseDataType BaseDataType::stringType<String8>
    () 
  {
    return BaseDataType(btString8);
  }

  template <>
  inline 
  BaseDataType BaseDataType::stringType<String16>
    () 
  {
    return BaseDataType(btString16);
  }

  inline
  BaseDataType::type BaseDataType::getBaseType
    ()
    const
  {
    return ty;
  }

  inline
  size_t BaseDataType::getSize
    ()
    const
  {
    return size;
  }

  inline
  DerivedDataType::DerivedDataType
    (type t,
     size_t s) :
      BaseDataType(base_type(t, s)),
      ty(t)
  {
  }

  inline
  DerivedDataType::DerivedDataType
    (BaseDataType::type t,
     size_t s) :
      BaseDataType(t, s),
      ty(static_cast<type>(t))
  {
  }

  inline
  DerivedDataType::type DerivedDataType::getDerivedType
    ()
    const
  {
    return ty;
  }

  template<typename T>
  inline
  IncompatibleType<T>::IncompatibleType
    (BaseDataType fromType, 
     BaseDataType toType)
  {
    addParam(fromType.getName());
    addParam(toType.getName());
  }
}

#endif