table.h

Go to the documentation of this file.

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


#if !defined XPACE_TABLE_H
#define XPACE_TABLE_H

#include <memory>
#include <functional>

#include "data/data.h"

#include "base/sharedimpl.h"

namespace Xpace
{
  class XPACE_EXPORT Table 
  {
  public : 
    static const char* TAG();       ///< Configuration tag for a Table
    static const char* NAME_TAG;    ///< Configuration tag for a Table's Name

    /// @param config the Table's Configuration; must include TAG, dd, di, and dt
    /// @param access how the Table will be opened
    /// @throw File_Cant_Open
    /// @throw File_Cant_Read
    explicit Table
      (const String& config,
       StoreAccess access = SA_readOnly);  

    /// @param store the Table's store file
    /// @param refs the Table's refs file (if any)
    /// @param map the Table's map file (if any)
    /// @param access how the Table will be opened
    /// @param overwrite start fresh if true; append if false
    /// @param test compare on read if true; append on read if false
    /// @param name if overwrite, name the table this
    Table
      (const String& store,
       const String& refs,
       const String& map,
       StoreAccess access = SA_readOnly,
       bool overwrite = false,
       bool test = false,
       const String& name = String());  

    /// @return true if the table is empty or does not exist
    bool operator!
      ()
      const;

    ///@ close the table, including its Sink (if any)
    void close
      ();
    
    /// @return the table's name
    String getName
      ()
      const;

    ///@ return the table's configuration
    String getConfig
      ()
      const;

    /// Get a column's configuration
    /// @param col the column number
    /// @return the column's Configuration
    String getColumnConfig
      (uint col)
      const;

    /// Get a column name from a column number
    /// @param the column number
    /// @return the column number, String() if not found
    String getColumnName
      (uint col)
      const;

    /// Get a column type from a column number
    /// @param the column number
    /// @return the column type, none if not found
    DerivedDataType getColumnType
      (uint col)
      const;

    /// Get a column from a column name
    /// @param the column name
    /// @return the column number, ~0 if not found
    uint getColumnNumber
      (const String& name)
      const;

    /// @return the number of rows in the table
    uint64 getRowCount
      ()
      const;
    /// @for compatibility with Store
    uint64 getDocCount
      ()
      const
    {
      return getRowCount();
    }

    /// @return the number of columns in the table
    uint getColumnCount
      ()
      const;

    // ------------------------------ Source ------------------

    /// @A read-only cursor into a table, parameterized on column
    typedef Xpace::Source<uint> Source;

    /// @Memory management for a Source
    struct XPACE_EXPORT SourceDeleter
    {
      void operator()
        (Source*);
    };
    typedef std::unique_ptr<Source, SourceDeleter> SourcePtr;

    /// create a Source
    /// @param row start at this row
    /// @return the Source
    SourcePtr createSource
      (uint64 row = 0)
      const;

    // ------------------------------ Sink --------------------

    /// A write-only, forward cursor into a table
    class XPACE_EXPORT Sink : public Xpace::Sink<uint>
    {
    public:
      /// Add a column by name
      /// @param name the name of the column
      /// @param type the type of the column
      /// @param columnNum a proposed column number
      /// @retval added true iff the field or column was added
      /// @returns the actual column number, ~0 to stop
      virtual uint add
        (const String& name,
         DerivedDataType type,
         uint columnNum,
         bool* added = 0) override
      = 0;

      using Xpace::Sink<uint>::add;
    };

    /// @return the (only) Sink to this table
    Sink* getSink
      ();

    /// Call a Sink for each column in this table
    /// @param sink called for each cell
    /// @param columns if not empty, return these columns in this order
    /// @return true iff act always returned true, false otherwise
    bool forEachColumn
      (Sink* sink, 
       const std::vector<uint>& columns = std::vector<uint>())
    const;

    /// Call a Sink for each cell in row/column order
    /// @param sink called for each cell
    /// @param columns if not empty, return these columns in this order
    /// @param status called for each row, return interval before next call
    /// @return true iff sink always returned true, false otherwise
    bool forEach
      (Sink* sink, 
       const std::vector<uint>& columns = std::vector<uint>(),
       StatusCallback status = defaultStatus)
    const;

    /// Can't open a Table
    class cantOpen : public Exception
    {
    public:
      /// @param config the configuration of the table
      /// @param reason why it couldn't be opened (e.g., File_Cant_Open)
      cantOpen
        (const String name,  
         const String& config,
         const Exception reason = Exception());
    };

    /// Can't create a Source
    class cantCreateSource : public Exception
    {
    public:
      /// @param row the row at which the creation failed
      cantCreateSource
        (uint64 row);
    };

    DECLARE_CACHED_IMPL(Table)
  };
};

#endif