source: branches/OaaS/HeuristicLab.Services.Optimization.Controller/Interfaces/IControllerService.cs @ 9674

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.ServiceModel;
using System.Net.Security;
using HeuristicLab.Services.Optimization.ControllerService.Model;

namespace HeuristicLab.Services.Optimization.ControllerService {
  /// <summary>
  /// The ControllerService represents the entry point of 
  /// the OaaS backend. It contains all possible operations 
  /// of OaaS.
  /// </summary>
  [ServiceContract(ProtectionLevel = ProtectionLevel.EncryptAndSign)]
  public interface IControllerService {
    /// <summary>
    /// Retrieves all available scenarios, including all
    /// their information.
    /// </summary>
    /// <returns>All scenarios</returns>
    [OperationContract]
    IEnumerable<OptimizationScenario> GetOptimizationScenarios();

    /// <summary>
    /// Returns the names of all scenarios. This doesn't load
    /// parameters or other scenario specific data.
    /// </summary>
    /// <returns>
    /// The names of the scenarios, 
    /// e. g. ["Benchmark Algorithm", "Genetic Algorithm - TSP"]
    /// </returns>
    [OperationContract]
    IEnumerable<string> GetOptimizationScenarioNames();

    /// <summary>
    /// Retrieves a scenario by a given name including all of
    /// it's data. 
    /// </summary>
    /// <param name="name">
    /// The scenario to lookup, e. g. "Benchmark Algorithm"
    /// </param>
    /// <returns></returns>
    [OperationContract]
    OptimizationScenario GetOptimizationScenarioByName(string name);

    /// <summary>
    /// Schedules a scenario for certain user.    
    /// </summary>
    /// <param name="user">The user which wants to execute a scenario.</param>
    /// <param name="scenario">The scenario to execute.</param>
    /// <param name="details">The title of the job, the number of repititions of the scenario and the group of the job.</param>
    /// <returns>true, if the scenario has been successfully scheduled.</returns>
    [OperationContract]
    bool ScheduleOptimizationScenario(User user, OptimizationScenario scenario, JobExecutionDetails details);

    /// <summary>
    /// Schedules an experiment for a certain user.
    /// </summary>
    /// <param name="user">The user which wants to execute a scenario.</param>
    /// <param name="experiment">The name of the experiment to schedule.</param>
    /// <param name="details">The title of the job, the number of repititions of the experiment and the group of the job.</param>
    /// <returns></returns>
    [OperationContract]
    bool ScheduleExperiment(User user, string experiment, JobExecutionDetails details);

    /// <summary>
    /// Returns all available jobs of a user.
    /// </summary>
    /// <param name="user">The user to query the jobs for.</param>
    /// <returns>All jobs for a certain user.</returns>
    [OperationContract]
    IEnumerable<Job> GetJobs(User user);

    /// <summary>
    /// Retrievs a job by it's id.
    /// </summary>
    /// <param name="user">The owner of the job.</param>
    /// <param name="id">The id of the job.</param>
    /// <returns>The job with the given user and id.</returns>
    [OperationContract]
    Job GetJob(User user, string id);

    /// <summary>
    /// Deletes a job of a user.
    /// </summary>
    /// <param name="user">The owner of the job.</param>
    /// <param name="id">The job to delete.</param>
    /// <returns>true, if the job has been deleted.</returns>
    [OperationContract]
    bool DeleteJob(User user, string id);

    /// <summary>
    /// Returns the results of a job including the input parameters and result parameters.
    /// </summary>
    /// <param name="user">The owner of the job.</param>
    /// <param name="id">The id of the job.</param>
    /// <returns>The result and input parameters of the job.</returns>
    [OperationContract]
    IList<Model.Run> GetJobResults(User user, string id);

    /// <summary>    
    /// Adds a new scenario to the system. This has to include a valid scenario xml representing all necessary inputs
    /// for the new scenario and a scenario mapper which is capable of converting the OaaS-scenario-model into the
    /// hive specific version.
    /// Note: This method might be only usable by an underlying hive data access layer.
    /// </summary>
    /// <param name="user">The owner of the scenario (must have administrator privileges).</param>
    /// <param name="scenarioXml">The new scenario to upload.</param>
    /// <param name="scenarioMapper">The converter between OaaS-model and hive model.</param>
    /// <returns>true, if the scenario has been successfully saved.</returns>
    [OperationContract]
    bool AddHiveScenario(User user, string scenarioXml, string scenarioMapper);
    
    /// <summary>
    /// Deletes a stored scenario including its xml and mapper.
    /// </summary>
    /// <param name="user">An administrator of the system.</param>
    /// <param name="scenarioName">The name of the scenario.</param>
    /// <returns>true, if the scenario has been deleted.</returns>
    [OperationContract]
    bool DeleteHiveScenario(User user, string scenarioName);

    /// <summary>
    /// Stores an experiment which is a tree of experiments and scenarios.
    /// This method will schedule the experiment, if it contains job details.
    /// </summary>
    /// <param name="user">The owner of the experiment.</param>
    /// <param name="experiment">The experiment including all of it's details.</param>
    /// <returns>If scheduled it will return the job id. In every other case null will be returned.</returns>
    [OperationContract]
    string SaveExperiment(User user, Experiment experiment);

    /// <summary>
    /// Returns the names of the experiments for a certain user.
    /// </summary>
    /// <param name="user">The owner of the experiments.</param>
    /// <returns>A list of experiment names.</returns>
    [OperationContract]
    IEnumerable<string> GetExperimentNames(User user);

    /// <summary>
    /// Returns all experiments. If "namesOnly" is false, the experiments include all of their details.    
    /// </summary>
    /// <param name="user">The owner of the experiments.</param>
    /// <param name="namesOnly">If true, returns only a list of experiments where only the Name parameter is set.</param>
    /// <returns></returns>
    [OperationContract]
    IEnumerable<Experiment> GetExperiments(User user, bool namesOnly = false);

    /// <summary>
    /// TODO
    /// </summary>
    /// <param name="user"></param>
    /// <param name="experiment"></param>
    /// <returns></returns>
    [OperationContract]
    bool DeleteExperiment(User user, string experiment);

    [OperationContract]
    Job GetTasks(User u, string jobId);

    [OperationContract]
    Task GetTaskData(User u, string jobId, string taskId);

    [OperationContract]
    Experiment GetExperimentByName(User user, string scenario);

    [OperationContract]
    Experiment GetExperimentById(User u, string nodeId);

    [OperationContract]
    VisualExtension GetVisualExtension(string algorithmId);

    [OperationContract]
    bool AddVisualExtension(string algorithmId, string script);

    [OperationContract]
    bool DeleteVisualExtension(string algorithmId);

    [OperationContract]
    bool ExistsVisualExtension(string algorithmId);
  }
}