// File.h

#ifndef hes_File_H
#define hes_File_H

// David Adams
// February 2002
//
// Abstract base for HES files.
//
// Concrete subclass must implement all the functions below, open file
// in constructor and close it in destructor.
//

#include <vector>
#include <iosfwd>

namespace hes {

class Name;
class FileType;
class FileId;
class EventId;
class EdoKey;
class EdoId;
class StreamType;
class PlacementCategoryId;
class PlacementCategory;
class EdoHandle;

class File {

public:  // typedefs

  typedef std::vector<EventId> EventIdList;
  typedef std::vector<PlacementCategoryId> PlacementCategoryIdList;

public:  // enums

  // Open status for the the file.
  //   READONLY - An existing file is opened
  enum OpenStatus { CLOSED, READONLY, NEW, APPEND };

public:  // Non-virtual functions.

  // Close the file.
  int close();

  // Is the physical file open?
  bool is_open() const;

public:  // destructor

  // Make destructor virtual.
  virtual ~File();

//**********************************************
// The following are all pure virtual functions.
//**********************************************

public:  // Validity.

  // Is this a valid file?
  // A valid file satisfies the following:
  //   1. has complete and valid header data
  //   2. has not experienced any irrecoverable read or write errors.
  virtual bool is_valid() const =0;

public:  // Access physical file. Implemented in FilePhysical.

  // For argument CLOSED, close the file.
  // The physical file is updated with all header and event data.
  // Serious error (e.g. insufficient space) if close fails.
  //
  // For any other argument, open the file in the specified mode.
  // If already opened, it should first be closed.
  // Fails if 
  //   1. file cannot be found (or created in NEW mode)
  //   2. user does not have sufficient authentication to open in
  //      the specified mode
  //   3. existing file has header data that is inconsistent with
  //      the status of this object
  // Returns 0 for success.
  virtual int open(OpenStatus stat) =0;

  // Read the open status.
  virtual OpenStatus open_status() const =0;

  // Can event data be read from the file?
  virtual bool can_be_read() const =0;

  // Can event data be written to the file?
  virtual bool can_be_written() const =0;

public:  // Return non-event file properties. Implemented in FileHeader.

  // Return the file type.
  virtual FileType type() const =0;

  // Return the physical name of the file.
  virtual Name physical_name() const =0;

  // Return the logical name of the file.
  virtual Name logical_name() const =0;

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

  // Return the type of stream implemented by this file.
  virtual const StreamType& stream_type() const =0;

  // Is the file locked?
  // If so, it cannot be written.
  virtual bool is_locked() const =0;

  // Lock the file.
  // After this call, no more data can be added to the file.
  virtual void lock() =0;

public:  // Event list and current event. Implemented in FileEvent.

  // Return the number of events.
  virtual int event_count() const =0;

  // Return the event range.
  virtual EventId min_event() const =0;
  virtual EventId max_event() const =0;

  // Return the list of event ID's included in this file.
  // The file includes one placement catgory of each of the above types
  // for each event in the file.
  virtual const EventIdList& event_ids() const =0;

  // Return the current event ID.
  virtual EventId event() const =0;

  // Set the current event.
  // No change if the event is not present.
  // Returns the current event.
  virtual EventId set_event(EventId evid) =0;

  // Set the current event to the first event.
  // The ID of that event is returned.
  virtual EventId first_event() =0;

  // Set the current event to the last event.
  // The ID of that event is returned.
  virtual EventId last_event() =0;

  // Go to the next event.
  // The ID of that event is returned.
  // An invalid ID should be returned when the list is exhausted.
  virtual EventId next_event() =0;

public:  // more

  // Has an event been opened (and not yet closed) for writing?
  // If so, EDO's may be added.
  virtual bool is_writing() const =0;

  // Return the placement category ID's for the current event.
  virtual PlacementCategoryIdList placement_categories() const =0;

  // Return a placement category for the current event.
  // Invalid is returned if the file does not hold the category by value.
  virtual PlacementCategory placement_category(PlacementCategoryId pcid) =0;

  // Return an EDO handle.
  // Invalid is returned if the file does not hold the EDO by value.
  virtual const EdoHandle& edo(EdoId edo_id) =0;

public:  // non-const functions for writing

  // Create a new event and open it for writing.
  // An empty placment category of each type is created.
  // The current event is set to this ID is successful and is set
  // invalid otherwise.
  // The current event is returned.
  virtual EventId create_event(EventId evid) =0;

  // Add a placement category by reference or value.
  // The added category replaces the empty category created when the
  // event was opened.
  // These fail if the category has already been added or if an EDO has
  // already been added to the category.
  // Return nonzero for error.
  virtual int add_placement_category_id(PlacementCategoryId pid) =0;
  virtual int add_placement_category(PlacementCategory pcat) =0;

  // Add an EDO by reference or value to the specified placement category.
  // These fail if
  //   1. the type-key is not consistent with the placement category type,
  //   2. the type-key has already been added to the placement category or
  //   3. the placement category has been added by reference or value
  // Returns nonzero for error.
  virtual int add_edo_id(Name pcname, EdoId edo_id) =0;
  virtual int add_edo(Name pcname, EdoKey key, const EdoHandle& edo_handle) =0;

  // Close the current event.
  // After this call, no more placement categories or EDO's may be added to
  // the current event.
  // The current event remains current (for reading).
  // Returns nonzero for error.
  virtual int close_event() =0;

};

}  // end namespace

// Output stream for OpenStatus.
std::ostream& operator<<(std::ostream& lhs, hes::File::OpenStatus rhs);

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

#endif