// LocalScheduler.h

#ifndef dial__LocalScheduler_H
#define dial__LocalScheduler_H

// David Adams
// July 2003
//
// This is a DIAL scheduler that assumes direct access to the application,
// task and job directories used by its jobs. The jobs are created with
// JobCreator::create_local_job().
//
// The following environmental variables must be defined or
// passed to the constructor:
//   DIAL_APPS = directory describing known applications
//   DIAL_TASKS = directory in which to build tasks
//   DIAL_JOBS = Directory in which to create run directories
//   DIAL_TASKBUILDER = script to build task (optional)
// 
// The subdirectories of DIAL_APPS are application names and the
// the subdirectories of those are version names. The value "default"
// is used for applications that do not define a version. Those
// subdirectories contain the files specifying how to build and run
// the application:
//   dataset.dtd - dataset DTD
//   dial.dtd - DIAL DTD
//   run - Script to run the application
//   build_task - executable script called to build the task
//
// Tasks are built in DIAL_TASKS/APPID/TSKID where APPID is the application
// ID and TSKID is the task ID.  These subdirectories are the task directories. 
//
// The task directory is created and task.xml is written and the task
// files are extracted into that directory. If the application contains the
// script build_task, then that script is run in the task directory. The build is
// considered successful if this script returns 0.
//
// During task installation and building the file task_building 
// appears in the task directory. After the install and build are finished,
// either task_installed or task_install_failed is written depending on
// on the status of the build.
//
// As of DIAL 1.30, these status files are writen by the scheduler or wrapper
// and archived to form the library task.so.)
//
// The subdirectories of DIAL_JOBS are the run directories for each job.
// The subdirectory names are the job ID's. These directories contain
// the files required by ProcessJob and those produced during execution.
// The following are provided as input to the application:
//   dial_run_script - script to run for this job
//   taskdir - Holds the name of the task directory (full path)
//   jid - Holds a string representation of the job ID
//   task.xml - descriptiom of input task
//   dataset.xml - descriptiom of the inpud dataset
// Output files include:
//   result.xml - the generated result (optional)
//   pid - process ID
//   start_time - start time
//   stop_time - stop time
//
// XML
//   LocalScheduler
//     jobrep = MYSQL:somedb:someaddress:sometable:someuser:somepass
//     JobCreator
//       ...

#include <string>
#include <iosfwd>
#include "dial_sched/Scheduler.h"

class Environment;
class XmlElement;

namespace dial {

class JobCreator;

class LocalScheduler : public Scheduler {

public:  // embedded clases

  // Implementation class
  class Imp;

public:  // typedefs
  
  typedef std::string Name;

private:  // data

  Imp* m_pimp;

public:  // Static members.
  
  // XML name.
  static std::string xml_name() { return "LocalScheduler"; }

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

public:  // Constructors and destructor.
  
  // Constructor.
  // If remove_jobs is true, then all jobs are removed (and so
  // directories deleted) when the scheduler is deleted.
  //   cre = job creator
  //   remove_jobs - If true jobs are deleted when the scheduler
  //                 is deleted
  //   jobrep = Connection string for job repository
  //            If blank, no repository.
  //   penv - Pointer to environment. If null, the process environment
  //          is used
  LocalScheduler(const JobCreator& cre,
                 bool remove_jobs,
                 std::string jobrep ="",
                 const Environment* penv =0);

  // Destructor.
  ~LocalScheduler();

public:  // Scheduler non-const interface

  // Add a task.
  int add_task(const Application& app, const Task& tsk);

  // Remove a task.
  int remove_task(const Application& app, const Task& tsk);

  // Submit a job.
  JobId submit(const Application& app,
               const Task& tsk,
               const dset::Dataset& dst,
               const JobPreferences& prf);

  // Kill a job.
  int kill(JobId jid);

  // Remove a job and any associated data.
  // The run directory and contents are deleted.
  int remove(JobId jid);

public:  // Scheduler const interface

  // Is an application available?
  bool has_application(const Application& app) const;

  // Is a task installed?
  bool has_task(const Application& app, const Task& tsk) const;

  // Task job.
  JobId task_job(const Application& app, const Task& tsk) const;

  // Return the list of job ID's.
  JobIdList jobs() const;

  // Fetch a job.
  Job& job(JobId jid) const;

  // XML.
  const XmlElement* xml() const;

public:  // Extension of interface

  // Validity.
  bool is_valid() const;

  // Log a message.
  void msg(std::string txt) const;

  // Return the job creator.
  const JobCreator& job_creator() const;

  // Return the directory where an application may be found.
  // Returns blank if the application is not available.
  // If create is true and the directory does not exist, it is created
  // and the files are extracted from the application.
  Name application_directory(const Application& app,
                             bool create = false) const;

  // Return the directory where a task would be installed
  // for the specified application.
  // Returns "" if the task category cannot be defined or the
  // category directory does not exist.
  Name task_directory(const Application& app, const Task& tsk) const;

  // Return the job directory directory.
  // Job with ID jid is run in job_directory()/jid
  Name job_directory() const;

  // Return the job repository connection.
  std::string job_repository_connection() const;

  // Return the job repository.
  JobRepository* job_repository() const;

  // Return the log.
  Text log() const;

  // Output stream.
  std::ostream& ostr(std::ostream& lhs) const;

};

}  // end namespace dial

#endif