#ifndef HEPFILEMANAGER_H
#define HEPFILEMANAGER_H


// ----------------------------------------------------------------------
//
// HepFileManager.h - header file for abstract base class providing
//   interface to any concrete histogram/Ntuple file manager
//
// HepFileManager objects are never instantiated directly.  Instead, use
// the derived class for the manager that is to be used (e.g.,
// HepHbookFileManager, HepHippoFileManager, etc.).  Refer to those
// class header files for usage.
//
// When creating a histogram/Ntuple manager or writing a wrapper for an
// existing manager, the manager class should be derived from this one.
//
//
// History:
//   ??-Jul-1994  Paul Rensing     Original draft
//   ??-Aug-1994  Bob Jacobsen     Added histogram support
//   26-Apr-1997  John Marraffino  Added directory functionality
//   20-May-1997  Walter Brown     General cleanup
//   29-May-1997  Jason Luther     Added comments
//   19-Jun-1997  Walter Brown     Restructured to handle cwd and the
//     ALists here; added findHist()s
//   27-Jun-1997  Walter Brown  Replaced HepString by standard string
//   18-Jul-1997  Philippe Canal   Added HepNtuple constructor
//   28-July-1997 Walter Brown     Added support for a list of managed
//     HepNtuple objects
//   05-Aug-1997  Walter Brown     Added writeOne()
//   08-Aug-1997  Walter Brown     Added isDirty(); granted friendship
//     to HepNtuple
//   12-Aug-1997  Walter Brown     Added root directory provisions
//   14-Aug-1997  Walter Brown     Added release()
//   21-Aug-1997  Walter Brown     Renamed newX() to makeX() and oldX()
//     to retrieveX(); changed return values from pointers to references;
//     added retrieveNtuple() prototype
//   27-Aug-1997  Walter Brown     Renamed makeX() to x() per committee
//   31-Oct-1997  Philippe Canal   Add dummy object creator for use after
//                                 an ignored exceptions
//   03-Nov-1997  Walter Brown     Added deadHepObj()
//   27-Jul-1998  Philippe Canal   Added actual object directory listing,
//                                 directory HepObj and utilities routines
//   19-Mar-2001  Mark Fischler	   Added hepFileFormat method
//
// ----------------------------------------------------------------------

#ifndef ZMENVIRONMENT_H
  #include "ZMutility/ZMenvironment.h"
#endif

#include <string>
#include <utility>

#ifndef ISOCXX__ISOCXX
  #include <STLUtility/fwd_vector.h>
#endif
#include <vector>

#include "HepTuple/Exceptions.h"
#include "HepTuple/hepTupleFileType.h"

ZM_USING_NAMESPACE( zmex )

ZM_BEGIN_NAMESPACE( zmht )	/*  namespace zmht  {  */

class HepHist;
class HepHist1D;
class HepHist2D;
class HepHistProf;
class HepHist1DArray;
class HepHist2DArray;
class HepHistProfArray;
class HepNtuple;
class HepDir;
class HepObj;
class HepID;

class HepHistCombiner;
class GatherProxy;
class HepFileSwitch;

class HepFileManager  {

  friend class HepObj;
  friend class HepHist;
  friend class HepHist1D;
  friend class HepHist2D;
  friend class HepHistProf;
  friend class HepHist1DArray;
  friend class HepHist2DArray;
  friend class HepHistProfArray;
  friend class HepNtuple;
  friend class HepDir;

public:

  // usefull constant
  static const std::string absStart; // start of an absolute path ('//')
  static const std::string dirSep;   // directory separator ('/')

  // constructor/destructor:
  HepFileManager(
    const std::string& fileName
  , const std::string& rootDirName
  );
  // Enum to request a file opening mode 
  // HEP_REFRESH means that the file is open for update
  // but (for the manager that supports it) insure that
  // each modified objects is over-written rather than 
  // versioned (see ROOT).
  // HEP_REMOVE means that any existing file with the
  // specified name will be removed.   DANGEROUS!!!
  // HEP_RENAME means that any existing file with the
  // specified name will be renamed.
  typedef enum mode_ { HEP_READONLY=1, HEP_UPDATE=2, HEP_REFRESH=4,
                       HEP_REMOVE=8,   HEP_RENAME=16 } mode;

  virtual ~HepFileManager();

  // Optional protections
  bool forReadOnly();      // Set the manager as read only
  bool forUpdate();        // Verify that the file can be updated

  // accessors:
  inline std::string  fileName() const;
  inline std::string  rootDir() const;
  std::string         pwd() const;
  inline bool         isReadOnly() const;
  virtual HepTupleFileFormat hepFileFormat() const = 0;

  // directory manipulation functions:
  virtual void cd( const std::string & path = "" );

  virtual void mkdir( const std::string & path );

  virtual std::string ls(const std::string & path = "", 
			 const std::string & opts = "" )  const;

  class Item {
  public:
    HepFileManager * mgr;         // pointer to desired manager
    std::string      title;       // object's title
    int              id;          // optional unique object ident
    std::string      dir;         // object's directory
    char             type;        // object type identification
    Item(const HepObj&);
    Item();                     
  };
  friend class HepFileManager::Item;
  typedef std::STL_VECTOR(Item) ItemList;
  virtual ItemList list( const std::string & path = "", 
			 const std::string & opts = ""  )  const;

  virtual void rm( int hid = 0 );
  virtual void rm( const std::string & title );

  virtual void rmdir( const std::string & path, bool recursive = false );
  //  virtual void rmdir( const HepDir & dir, bool recursive = false );

  // create histograms and Ntuples:
  static HepObj * deadHepObj();      // for erroneous situations

  virtual HepHist1D & hist1D(        // 1-D
    const std::string& title,
    const int nBins, const float low, const float high,
    const int hid = 0
  );
  virtual HepHist1DArray& hist1DArray(   // Array of 1-D Histograms 
    const int size,
    const std::string& title_prefix,
    const int nBins, const float low, const float high,
    const int hid = 0
  );
  virtual HepHist2D & hist2D(        // 2-D
    const std::string& title,
    const int nBinsX, const float lowX, const float highX,
    const int nBinsY, const float lowY, const float highY,
    const int hid = 0
  );
  virtual HepHist2DArray& hist2DArray(   // Array of 2-D Histograms 
    const int size,
    const std::string& title_prefix,
    const int nBinsX, const float lowX, const float highX,
    const int nBinsY, const float lowY, const float highY,
    const int hid = 0
  );
  virtual HepHistProf & histProf(    // profile plot
    const std::string& title,
    const int nBinsX, const float lowX, const float highX,
    const float lowY, const float highY,
    const std::string& chopt,
    const int hid = 0
  );
  virtual HepHistProf & histProf(    // profile plot
    const std::string& title,
    const int nBinsX, const float lowX, const float highX,
    const float lowY, const float highY,
    const int hid = 0
  );
  virtual HepHistProfArray & histProfArray(    // Array of profile plot
    const int size,
    const std::string& title_prefix,
    const int nBinsX, const float lowX, const float highX,
    const float lowY, const float highY,
    const std::string& chopt,
    const int hid = 0
  );
  virtual HepHistProfArray & histProfArray(    // Array of profile plot
    const int size,
    const std::string& title_prefix,
    const int nBinsX, const float lowX, const float highX,
    const float lowY, const float highY,
    const int hid = 0
  );
  virtual HepNtuple & ntuple(        // Ntuple
    const std::string& title,
    const int hid = 0
  );


  // attach to existing histograms and Ntuples:
  HepObj * retrieveHepObj(                   // generic retrieval logic:
    const std::string& title
  , const int hid
  , const char objType
  ) const;

  HepObj * retrieveHepObj(                   // generic retrieval logic:
    const std::string& title
  , const int hid
  , const char objType
  , const std::string& path
  ) const;

  virtual HepHist1D & retrieveHist1D(        // 1-D
    const std::string& title,
    const int hid = 0
  );
  virtual HepHist2D & retrieveHist2D(        // 2-D
    const std::string& title,
    const int hid = 0
  );
  virtual HepHistProf & retrieveHistProf(    // profile plot
    const std::string& title,
    const int hid = 0
  );
  virtual HepHist1DArray & retrieveHist1DArray(        // Array of 1-D
    const int size,
    const std::string& title,
    const int hid = 0
  );
  virtual HepHist2DArray & retrieveHist2DArray(        // Array of 2-D
    const int size,
    const std::string& title,
    const int hid = 0
  );
  virtual HepHistProfArray & retrieveHistProfArray(    // Array of profile plot
    const int size,
    const std::string& title,
    const int hid = 0
  );
  virtual HepNtuple & retrieveNtuple(        // Ntuple
    const std::string& title,
    const int hid = 0
  );

  // user is finished with the indicated object
  virtual void release( HepObj & me );

  // write the Ntuples/histograms into the file, returning success status:
  // non-0 otherwise.
  virtual int write() = 0;

  // write this directory's Ntuples/histograms into the file
  virtual void writeDirectory() = 0;

  // Call dumpData() or clearData() for all managed tuples
  virtual void dumpAllData();
  virtual void clearAllData();

  // Create a object of that a clone or copy of the argument in the current
  // directory. A Copy in an exact replication of the argument. A clone is an
  // object of the same type and characteristic (e.g number of bins) but
  // without any data entered.

  virtual HepObj& makeClone( const HepObj& original, const std::string& new_title, int new_id = 0 ); 
  virtual HepObj& makeEmpty( const HepObj& original, const std::string& new_title, int new_id = 0 ); 

  // Clone all the objects in the current (specified) directory of the original manager.
  // options are the same as for list and ls.  Cloned items have the same title and id
  // as the originals.
  virtual bool copyClone( HepFileManager* original, const std::string& options = "" );
  virtual bool copyClone( HepFileManager* original, const std::string& path,
			  const std::string& options);
  virtual bool copyEmpty( HepFileManager* original, const std::string& options = "" );
  virtual bool copyEmpty( HepFileManager* original, const std::string& path,
			  const std::string& options);

  // Merge, except for ntuples, all the objects in this and sourceManager
  HepFileManager & combine( HepFileManager* sourceManager );

  // Merge, except for ntuples, all the objects in this and sourceManager
  // according to the recipe provided by the user in his/her
  // HepHistCombiner::usercomb object.
  HepFileManager & combine( HepFileManager* sourceManager,
                            HepHistCombiner & usercomb );

  // Same operation as combine except expressed as an operator overload.
  HepFileManager & operator+= ( HepFileManager& b );

  // Transparently switch output from current file to newFileName with
  // optional resetting of all histogram objects.  Root manager only.
  virtual bool switchFile( const std::string& newFileName,
                           const bool resetHists );

  // Transparently switch output from current file to newFileName with
  // optional resetting of all histogram objects.  Root manager only.
  virtual bool switchFile( const std::string& newFileName,
                           const bool resetHists,
                           HepFileSwitch& userHandler );

#ifdef BABAR

// ************************************************************************* //
// define accessor that return pointers instead of reference to ease         //
// babar's transition                                                        //

  HepHist1D* newHist1D ( 
    const char title[],
    const int nBins, const float low, const float high,
    const int hid = 0
    );
  HepHist2D* newHist2D(        // 2-D
    const char title[],
    const int nBinsX, const float lowX, const float highX,
    const int nBinsY, const float lowY, const float highY,
    const int hid = 0
  );
  HepHistProf* newHistProf(    // profile plot
    const char title[],
    const int nBinsX, const float lowX, const float highX,
    const float lowY, const float highY,
    const char chopt[],
    const int hid = 0
  );
  HepHistProf* newHistProf(    // profile plot
    const char title[],
    const int nBinsX, const float lowX, const float highX,
    const float lowY, const float highY,
    const int hid = 0
  );
  HepNtuple* newNtuple(        // Ntuple
    const char title[],
    const int hid = 0
  );

#endif

protected:
  // Function check what is the actual mode of a file
  typedef enum filemode_ { HEP_ABSENT, HEP_NONE, 
			   HEP_READ, HEP_WRITE, HEP_ALL } filemode;
  static filemode checkFile ( const std::string & filename );

  // Check if the title is valid (at least not '/' in it)
  virtual bool checkTitle( const std::string& title) const;

  // set the read only flag and return the old value.  NO CHECK is performed.
  // use forReadOnly() and forUpdate() for checked operations.
  bool setReadOnly ( bool );

  // Return the highest id in the current directory.
  int GetHighestId(const std::string& path = "") const;

  // Created the internal representation of the directory.
  // It will NOT create it in the actual manager.
  HepDir* mkdir_( const std::string & path );

  // Return the HepDir node corresponding to the path
  HepDir* getdir(const std::string& path) const;

  HepObj * retrieveHepObj(         // generic retrieval logic
    const std::string& title       // called by other retrieve functions
    , const int hid
    , const char objType
    , const HepDir* dir 
  ) const;

  // update the list with the content of dir.  Do dir's sub-directory
  // it opts containt the letter 'r'
  void list_(const HepDir&,HepFileManager::ItemList&,const std::string& opts) const;

  // Actual copyClone and copyEmpty member functions.

  virtual bool copyClone_( const HepDir& original, const std::string& options );
  virtual bool copyEmpty_( const HepDir& original, const std::string& options );

  // id generator: Provide the next available ID, or honor the req
  HepID nextID( const int req = 0 ); 
     // call next one with empty string (emulate default 1st argument.)
  virtual HepID nextID( const std::string& s = "", const int req = 0 ); 

  // save individual histograms and Ntuples:
  virtual void writeOne( HepObj * thisObj  );

  typedef std::vector<HepObj *> HepObjList;
  HepObjList   objList_;      // list of (ptrs to) all HepObj's in this file
  HepObjList   deadObjList_;  // list of deleted HepObj's in this file
                              // (an object makes it to this list if it is
                              // delete while the users MAY have a reference 
                              // to it.  It will be actually delete when 
                              // the manager is deleted.

  // list inspection & maintenance:
  HepObjList::const_iterator  findObj( const std::string & title ) const;
  HepObjList::const_iterator  findObj( const int id ) const;
  void signIn( HepObj * thisObj );

  void isInUse( HepObj * h, const bool isIt );
  void isDirty( HepObj * h, const bool isIt );
  void isCreated( HepObj * h, const bool isIt );

  // Dead Object creator
  virtual HepNtuple& deadNtuple() const;
  virtual HepHist1D& deadHist1D() const;
  virtual HepHist2D& deadHist2D() const;
  virtual HepHistProf& deadHistProf() const;

  static HepHist1DArray& deadHist1DArray();
  static HepHist2DArray& deadHist2DArray();
  static HepHistProfArray& deadHistProfArray();

  static void copyToItem(const HepObj&,Item&); 
  // used by Item constructor to read HepObj eventhough Item is not a friend
  // of HepObj and HepObj data members are not available publicly when the
  // user does not have the object.  

  // Helper functions for the public HepFileManager::combine function

typedef std::vector<std::string>		svector;

  void reconcileDirs( HepFileManager* sourceManager, 
                      GatherProxy& satchel );

  void gatherHists( HepFileManager* sourceManager, 
                    GatherProxy& satchel );

  void scanTree( HepFileManager* Manager, svector& Dirs, svector& Keys );

private:

  std::string fileName_;	// the file name
  const std::string rootDir_;   // the name of this file's root directory
  HepDir*      topDir_;         // The upmost directory
  HepDir*      cwd_;            // the current working directory
  int          lastID_;         // the last largest id number used
  bool         isReadOnly_;     // Fist set as the opening status of the file
                                // which may be later changed by the user
                                // see forReadOnly()

  HepFileManager( const HepFileManager & );              // forbidden
  HepFileManager & operator=( const HepFileManager & );  // forbidden

};  // HepFileManager


typedef HepFileManager HepTupleManager;	// preserve classname compatibility


ZM_END_NAMESPACE( zmht )	/*  }  // namespace zmht  */


#include "HepFileManager.icc"


#endif  // HEPFILEMANAGER_H