// FileCatalog.h

#ifndef dset__FileCatalog_H
#define dset__FileCatalog_H

// David Adams
// April 2003
// Restructured November 2005.
//
// A file catalog maintains an association between a logical
// file URL and zero, one or more physical file URLs.
//
// File catalogs are labelled by type and name. FileCatalog
// provides means to locate a concrete file catalog using
// its type and name. This location is done with a registered
// function which is normally provided by the concrete subclass.
//
// There is an XML representation that holds this type and name.
//
// XML Representation
//   type = MyFileCatalog
//   name = production

#include <iosfwd>
#include <time.h>
#include <string>
#include <vector>
#include "dataset_util/Url.h"

class Text;
class XmlElement;

namespace dset {

class FileCatalog {

public:  // typedefs

  // Name (for file, type, catalog, ...)
  typedef std::string Name;

  // List of names.
  typedef std::vector<Name> NameList;

  // List of URL's.
  typedef std::vector<Url> UrlList;

  // Function to locate a FileCatalog using the type and catalog
  // names.
  typedef FileCatalog* (*Locator) (Name type, Name catalog);

  // Time in seconds.
  typedef time_t Time;

public:  // Static functions

  // Return the XML type name.
  static const char* xml_name() { return "FileCatalog"; }

  // Return the DTD.
  static const Text& dtd();

  // Register a locator for a type.
  // Type may not be previously registered.
  // Returns zero for success.
  static int register_locator(Name type, Locator pfun);

  // Fetch a file catalog using type and catalog name.
  // Uses the (previously registered) locator for the specified type.
  // Caller is not responsible for managing the returned catalog.
  // Returns zero for failure.
  static FileCatalog* locate(Name type, Name name ="");

  // Locate a catalog using FileCatalog XML.
  static FileCatalog* locate(const XmlElement& ele);

  // Set the default file catalog.
  // Fails if the default is already set with a previous call here
  // or to default_instance().
  // If successful, a pointer to the catalog is returned.
  static FileCatalog* set_default_instance(Name type, Name name ="");

  // Return the default file catalog.
  // Choice is as follows:
  //   1. Value specified in set_default_instance.
  //   2. Value in env DIAL_FILE_CATALOG; format type:name.
  //   3. LocalFileCatalog
  static FileCatalog* default_instance();

public:  // Virtual functions

  // Destructor.
  virtual ~FileCatalog();

  // Return the type of the file catalog.
  // This should be a unique specification of the type,
  // most likely class name.
  virtual Name type() const =0;

  // Return the instance name of the file catalog.
  // This distinguishes different instances of the same type.
  virtual Name name() const =0;

  // Return whether the catalog may be modified, i.e. new entries
  // added and existing (writeable) entries modified.
  // Default is true.
  virtual bool catalog_is_writeable();

  // Return whether whether a logical URL appears in the catalog.
  virtual bool has(Url lurl) =0;

  // Return the GUID URL (if available) for the specified logical file.
  virtual Url guid(Url lurl) =0;

  // Return the LFN URL (if available) for the specified logical file.
  virtual Url lfn(Url lurl) =0;

  // Return the list of physical URL's associated with the given
  // logical URL.
  virtual UrlList replicas(Url lurl) =0;

  // Register a logical-physical association in the catalog.
  // Creates a new logical entry if needed.
  //   purl = URL for the physical file.
  //   lurl = URL for the logical file. May be omitted or partial if
  //          the physical URL is supplied and the catalog knows how
  //          to construct the logical URL from the physical file or
  //          its URL.
  //   lifetime = suggested lifetime in seconds for the logical entry
  //              the logical-physical association. Zero means forever.
  // If succesful, the logical URL is returned.
  virtual Url insert(Url purl, Url lurl =Url(), Time lifetime =0) =0;

  // Remove an entry from the catalog.
  // The logical entry is also removed if it has no more associations
  // and remlog is true.
  // Return 0 for success.
  virtual int remove(Url purl, Url lurl, bool remlog =true) =0;

  // Return status code for the last failed operation.
  // Default returns 0.
  virtual int error() const;

  // Output stream.
  // Displays catalog type and name.
  virtual void ostr(std::ostream& str) const;

public:  // Local functions

  // Write to XML.
  // Only the file catalog ID and file ID are written.
  // Do not overrride.
  const XmlElement* xml() const;

};

}  // end namespace dset

// Output stream.
// Calls FileCatlog::ostr(ostream&);
std::ostream&
operator<<(std::ostream& lhs, const dset::FileCatalog& rhs);

#endif