// JobPreferences.h

#ifndef dial__JobPreferences_H
#define dial__JobPreferences_H

// David Adams
// May 2004
//
// This class holds job preferences to be communicated to a job
// scheduler. These are part of the job provenance but typically
// not part of the dataset provenance.
//
// Each entry has a unique name and a string value.
//
// XML represenation:
//
// JobPreferences
//   xml_version = "1.20"
//   JobPreferencesId
//   JobPreferencesEntry
//     name = splitter
//     value = 123
//   JobPreferencesEntry
//     name = splitter
//     value = <MyXmlType name="david">
//   ...

#include <string>
#include <vector>
#include <map>
#include <iosfwd>
#include "dataset_util/Text.h"
#include "dial_job/JobPreferencesId.h"

class XmlElement;

namespace dial {

class JobPreferences {

public:  // typedefs

  typedef std::string Name;
  typedef std::vector<Name> NameList;
  typedef NameList::size_type size_type;
  typedef std::string Value;
  typedef std::map<Name, Value> ValueMap;

private:  // data

  // ID.
  JobPreferencesId m_id;

  // Lock status.
  bool m_lock;

  // Error status. Zero for a valid object.
  int m_error;

  // List of entry names.
  NameList m_names;

  // Map of XML elements.
  // Entries are managed here.
  ValueMap m_vals;

public:  // static methods

  // XML name.
  static const char* xml_name();

  // Context for UniqueId generator.
  static const char* id_context();

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

  // Empty and locked instance of this class.
  static const JobPreferences& default_instance();

public:  // Constructors, destructor and assignment.

  // Default constructor.
  // Object is in the unlocked state.
  JobPreferences();

  // XML constructor.
  explicit JobPreferences(const XmlElement& ele);

  // Copy.
  JobPreferences(const JobPreferences&);

  // Assignment.
  JobPreferences& operator=(const JobPreferences&);

  // Destructor.
  ~JobPreferences();

public:  // non-const methods

  // Lock the preferences.
  // An ID is assigned and the preferences cannot be changed.
  // Object must be unlocked.
  // Returns 0 for success.
  int lock();

  // Set a name-value pair.
  // Object must be unlocked.
  // If successful, this object takes ownership of the XML element.
  // Fails if replace is false and name is already in the map.
  // returns zero for success.
  int insert(Name name, Value val, bool replace =false);

public:  // const methods

  // Is this a valid object?
  bool is_valid() const;

  // Return the error code. Nozero for an invalid object.
  int error() const;

  // Is this object valid and locked.
  bool is_locked() const;

  // Is this object valid and unlocked.
  bool is_unlocked() const;

  // Return the ID.
  JobPreferencesId id() const;

  // Number of entries.
  size_type size() const;
  
  // Return the list of names.
  const NameList& names() const;
  
  // Return if a name is known.
  bool has(Name name) const;

  // Get the value associated with a name.
  // Return is blank if there is no associated value.
  Value extract(Name name) const;

  // Copy preferences into a new unlocked object.
  JobPreferences* clone() const;

  // Write to XML.
  // Object must be locked.
  // Caller is responsible for managing the returned object.
  const XmlElement* xml() const;

  // Display.
  void display() const;

  // Web page.
  // entry:
  //   blank to show preferences
  //   file=xxx to show preference with name xxx
  Text web_page(std::string baseurl, std::string entry) const;

};

}  // end dial namespace

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

#endif