// Dataset.h

#ifndef dset__Dataset_H
#define dset__Dataset_H

// David Adams
// July 2003
//
// Base class for all datasets. Defines interface to provide the following
// functionality:
//   ID
//   Pointer to parent dataset (if cloned)
//   owner (creator)
//   Cloning
//   Locking
//   Content
//   Location
//   Validity and empty check
//   XML I/O
//   Output streaming
//   Ordering
//
// Whenever a dataset is copied or cloned, it should be assigned a
// new identity and the original assigned as the parent of the copy.
// The original dataset must be locked and the new dataset is
// unlocked.  The class BaseDataset provides this functionality.
//
// Datasets should never be assigned (use clone instead). The
// assignement operator is declared private and not defined here to
// discourage this operation.
//
// Class DatasetId based on UniqueId is used as the dataset identifier.
// The plan is to replace this with a template argument when another
// type of identifier is desired:
// Dataset --> Dataset<class ID =DatasetId>

#include <iosfwd>
#include <ctime>
#include "dataset_util/Text.h"
#include "dataset_id/UniqueIdGenerator.h"
#include "dataset_id/EventIdList.h"
#include "dataset_id/DatasetId.h"
#include "dataset_id/DatasetIdList.h"
#include "dataset_base/Content.h"
#include "dataset_base/Location.h"

class XmlElement;

namespace dset {

class Dataset;

// List of datasets.
typedef std::vector<const Dataset*> DatasetList;

class Dataset {

public:  // Typedefs.

  // Time.
  typedef time_t Time;

public:  // Static methods

  // Unique ID generator to be shared by all datasets.
  // If the generator is not already defined, an attempt is made
  // to find a global generator. If this fails, a local generator
  // is created.
  static UniqueIdGenerator& id_generator();

  // Delete the unique ID generator.
  // The next call to id_generator() will open a new generator.
  static void reset_id_generator();

  // Force the unique ID generator to be local.
  static void set_local_id_generator();

  // Display memory usage.
  static std::string memory_report();

private:  // Hidden functions.

  // Assignment.
  Dataset& operator=(const Dataset& rhs);

public:  // Constructors and destructors.

  // Constructor.

  // Constructor.
  Dataset();

  // Destructor.
  virtual ~Dataset();

public:  // const virtual functions

  // Return the full dataset type name.
  virtual std::string fulltype() const;

  // Validity.
  // Default assumes dataset is valid if ID is valid.
  virtual bool is_valid() const;

  // Error status.
  // Zero if valid.
  // Default returns 0 if valid, 9999 if not;
  virtual int error() const;

  // Emptiness.
  // Default is true.
  virtual bool is_empty() const;

  // Return the ID.
  virtual DatasetId id() const =0;

  // Return the parent ID.
  // Returns invalid if there is none.
  virtual DatasetId parent_id() const =0;

  // Return the parent.
  // Returns 0 if there is none or it is not accessible.
  virtual const Dataset* parent() const =0;

  // Return the owner.
  // This is normally the person who created the dataset.
  virtual std::string owner() const =0;

  // Return the create time.
  virtual Time create_time() const =0;

  // Return the lock status.
  virtual bool is_locked() const =0;

  // Return the content of the dataset.
  // Default returns empty.
  virtual const Content& content() const;

  // Virtual. Dataset is virtual if its location is empty.
  // Might be overridden to optimize.
  virtual bool is_virtual() const;

  // Return the location of the data contained in
  // this dataset.
  // Default here is empty.
  virtual const Location& location() const;

  // Return the location of the data the specify the processing
  // interface to this dataset. Typically the same as or a subset of
  // the full location.
  // Default returns the full location.
  virtual const Location& interface_location() const;

  // Return if this an event dataset.
  // An event dataset is one that is made up of a collection of
  // records that may be processed independetly.
  virtual bool is_event_dataset() const =0;

  // Return the event count.
  // Returns 0 if this is not an event dataset.
  virtual EventIdList::size_type event_count() const =0;

  // Return the list of event_ids.
  // Returns empty if this is not an event dataset or the event
  // list is not available.
  virtual const EventIdList& event_ids() const =0;

  // Return the constituent dataset ID's.
  // Default is empty.
  virtual const DatasetIdList& constituent_ids() const;

  // Return the constituent datasets.
  // Default is empty.
  virtual const DatasetList& constituents() const;

  // Clone the dataset.
  // Caller has ownership of the new dataset.
  // This dataset is the parent of the new dataset.
  // This dataset must be locked.
  // The new dataset is unlocked.
  // Argument is the directory to place any generated files.
  // Returns 0 for error.
  virtual Dataset* clone(std::string dir ="") const =0;

  // Return XML representation.
  // Caller has management of the returned object.
  // Dataset must be locked.
  // Return 0 for error.
  virtual const XmlElement* xml() const =0;

  // Inform the dataset that it may release any resources it has
  // allocated, e.g. release staged files.
  // The destructor should do this and more.
  // Returns nonzero for error.
  // Default does nothing and returns 0.
  virtual int release() const;

  // Return the memory allocated to this object.
  virtual size_t memsize() const =0;

  // Output stream.
  // Implementation here uses base_ostr.
  // repurl = URL for dataset repository--if nonblank, constituent ID's
  //          should be formatted as URL's, e.g.:
  //            <a href=repurl?did=123-456>123-456</a>.
  virtual std::ostream&
  ostr(std::ostream& str, std::string indent, std::string repurl ="") const;

public:  // non-const virtual functions

  // Lock the dataset.
  // Returns 0 successful.
  virtual int lock() =0;

  // Set the dataset ID with a specified value.
  // The dataset must be unlocked and the current ID must be local
  // or undefined.
  // Returns 0 if successful.
  virtual int set_id(const DatasetId& id) =0;

  // Set the dataset ID to a unique value.
  // The dataset must be unlocked and the current ID must be local
  // or undefined.
  // Returns 0 if successful.
  virtual int set_id() =0;

  // Set the parent dataset ID.
  // This dataset must be unlocked.
  // The parent must be locked.
  // Returns 0 if successful.
  virtual int set_parent_id(const DatasetId& id) =0;

  // Set the parent dataset and ID.
  // This dataset must be unlocked.
  // The parent must be locked.
  // Returns 0 if successful.
  virtual int set_parent(const Dataset& dst) =0;

  // Merge another dataset into this.
  // This dataset must be unlocked.
  // Second argument is the directory to place new files.
  // Returns 0 if successful.
  virtual int merge(const Dataset& dst, std::string dir ="") =0;

  // Select content.
  // Dataset must be valid and unlocked.
  // Returns 0 if successful.
  virtual int select(const Content& con) =0;

  // Select events.
  // Returns 0 for success.
  virtual int select_events(const EventIdList& eids) =0;

public:  // non-virtual functions

  // Output to cout.
  void display() const;

  // Is this a dataset of type T?
  template<class T> bool is() const {
    return dynamic_cast<const T*>(this) != 0;
  }

  // Cast to type T.
  // Check first with is() to avoid exception.
  template<class T> T& cast() {
    return dynamic_cast<T&>(*this);
  }

  // Cast to type const T.
  // Check first with is() to avoid exception.
  template<class T> const T& cast() const {
    return dynamic_cast<const T&>(*this);
  }

  // Output the base status.
  // If the last argument is not null, then constituent ID's
  // are written as HTML links using that location as base, e.g.::
  // baseurl?did=123-456
  virtual std::ostream&
  base_ostr(std::ostream& str, std::string indent,
            std::string repurl ="") const;

  // Web page.
  // baseurl = URL for this dataset
  // repurl = URL for the repository holding constituents
  // entry:
  //   blank to show entire dataset
  virtual Text web_page(std::string baseurl, std::string repurl,
                        std::string entry) const;

};

// Ordering.
// Uses the ID.
bool operator<(const dset::Dataset& lhs, const dset::Dataset& rhs);

// List validity.
// All entries must be non-null and valid.
bool is_valid(const dset::DatasetList& rhs);

}  // end namespace dset

// Output stream.
std::ostream& operator<<(std::ostream& lhs, const dset::Dataset& rhs);

// List output stream.
std::ostream&
operator<<(std::ostream& lhs, const dset::DatasetList& rhs);

#endif