Fews PI service

/* ================================================================
 * Delft FEWS
 * ================================================================
 *
 * Project Info:  http://www.wldelft.nl/soft/fews/index.html
 * Project Lead:  Karel Heynert (karel.heynert@wldelft.nl)
 *
 * (C) Copyright 2003, by WL | Delft Hydraulics
 *                        P.O. Box 177
 *                        2600 MH  Delft
 *                        The Netherlands
 *                        http://www.wldelft.nl
 *
 * DELFT-FEWS is a sophisticated collection of modules designed
 * for building a FEWS customised to the specific requirements
 * of individual agencies. An open modelling approach allows users
 * to add their own modules in an efficient way.
 *
 * ----------------------------------------------------------------
 * WebService.java
 * ----------------------------------------------------------------
 * (C) Copyright 2003, by WL | Delft Hydraulics
 *
 * Original Author:  Erik de Rooij
 * Contributor(s):
 *
 * Changes:
 * --------
 * 10-Sep-2007 : Version 1 ();
 *
 *
 */
package nl.wldelft.fews.system.pi;

import java.util.Date;

/**
 * TODO <code>ISSUES</code>
 *<li>Optional Date arguments can not be set to NULL when not used.</li>
 *<li> When retrieving timeseries. What use is it to add ensemble Id? Because the timeseries set already contains the ensemble id. </li>
 *<li> Some interface call do not require the clientId. Should we remove this to simplify things?</li>
 */
public interface FewsPiService {


    String getLocations(String clientId);
    /**
     * Retrieve the configuration file for the .

     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param fileExtension. Case insensitive. Extension of the config file (e.g. xml, ini), One client can have multiple config files
     * with different file extensions.
     * @return client config text file. Format of file must be known by client.
     */
    String getClientConfigFile(String clientId, String fileExtension);


    /**
     * Create a new Task. Use return Task id when exporting data to the WebService.

     * @param clientId Id of web service client (obtained on command line when invoked)
     * @return Task id for the new task.
     */
    String createTask(String clientId);

    /**
     * Return the current time zero of the system.
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @return Time zero
     */
    Date getSystemTime(String clientId);

    /**
     * TODO
     *
     * ID of Configured timezone for the webservice
     * @param clientId
     * @return
     */
    String getTimeZoneId(String clientId);

    /**
     * Run a Single task. TaskId must be obtained using the method {@link FewsPiService#createTask(String)}.
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId Task Id
     * @param workflowId Workflow Id
     * @param startTime start date/time of run - NULL if the configured default is to be used
     * @param timeZero Forecast time zero.
     * @param endTime end date/time of run - NULL if the configured default is to be used
     * @param coldStateId String identifying the cold state to use - NULL if a cold state start is not forced
     * @param userId Id of user running task.
     * @param description Description
     * @return Returns the TaskRun id
     */
    String runTask(String clientId, String taskId, String workflowId, Date startTime, Date timeZero, Date endTime, String coldStateId, String scenarioId, String userId, String description);

	/**
	 * Request Ids of available cold states
	 *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param id Id of the State module instance for which to retrieve the cold state ids.
	 * @return List of available cold state groups
	 */
	String[] getColdStateIds(String clientId, String id);

    /**
     * Request run status of task. This can be used to wait for a task to complete
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId Task Id
     * @param waitMillis number of milli-seconds to wait between status requests
     * @return boolean if task is complete or has been cancelled
     */
    boolean waitForTask(String clientId, String taskId, int waitMillis);

    /**
     * cancel task. Cancel a running task
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId Task Id
     */
    void cancelTask(String clientId, String taskId);

    /**
     * Retrieve the indices for the given ensemble id.
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param ensembleId Id of the ensemble
     * @return All valid indices for this ensemble.
     */
    int[] getEnsembleMemberIndices(String clientId, String ensembleId);

    /**
     * Write timeseries associated to a specific task to webservice. The webservice will store this information in the database.
     *
     * If the time series is an ensemble then each ensemble member needs to be submitted individually.
     * using the <i>ensembleMemberIndex</i> argument. For deterministic time series the <i>ensembleMemberIndex</i> is NULL
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}
     * to obtain valid ensemble member index values.
     *
     * The TaskId may be NULL or the requested task id.
     * In case it is NULL the time series is written as data visible to all other processes in FEWS
     * In case it is TaskId the time series will be used only by the task run with TaskId (e.g. scenario time series)
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param id Id of the Pi timeseries xml content.
     * @param piTimeSeriesXmlContent  Time Series content in the form of a Pi timeseries xml file.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    void putTimeSeries(String clientId, String taskId, String id, String piTimeSeriesXmlContent, String ensembleId, int ensembleMemberIndex);

    /**
     * Write timeseries. The webservice will store this information in the database.
     *
     * <p>
     * For performance reasons it is possible to split the timeseries header information from the timeseries data. The header information
     * is stored in the <i>piTimeSeriesXmlContent</i> and the timeseries data is stored in the <i>byteTimeSeriesContent</i>.
     * <p>
     * If the time series is an ensemble then each ensemble member needs to be submitted individually.
     * using the <i>ensembleMemberIndex</i> argument. For deterministic time series the <i>ensembleMemberIndex</i> is NULL
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}
     * to obtain valid ensemble member index values.
     *
     * The TaskId may be NULL or the requested task id.
     * In case it is NULL the time series is written as data visible to all other processes in FEWS
     * In case it is TaskId the time series will be used only by the task run with TaskId (e.g. scenario time series)
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param id Id of the Pi timeseries xml content.
     * @param piTimeSeriesXmlContent  TimeSeries content in the form of a Pi timeseries xml file.
     * @param byteTimeSeriesContent  TimeSeries data content in the form of a byte array.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    void putTimeSeriesBinary(String clientId, String taskId, String id, String piTimeSeriesXmlContent, byte[] byteTimeSeriesContent, String ensembleId, int ensembleMemberIndex);

    /**
     * Write information about the parameter set file given the webservice.
     *
     * The TaskId may be NULL or the requested task id.
     * In case it is NULL the parameters version will be upaded
     * In case it is TaskId the parameters will be used only by the task run with TaskId (e.g. scenario run)
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param id Id of parameter set
     * @param piParameterSetXmlContent  Parameters content in the form of a Pi parameters xml file.
     * @param validityStartTime Start time of parameter validity (NULL if not applicable)
     * @param validityEndTime End time of parameter validity (NULL if not applicable)
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    void putModuleParameterSet(String clientId, String id, String taskId, String piParameterSetXmlContent, Date validityStartTime, Date validityEndTime, String ensembleId, int ensembleMemberIndex);

    /**
     * Write information about the dataset file for the given taskId back to the webservice. The webservice will store this information and will add it to the
     * task properties when the task is run.
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param id Id of Module DataSet file.
     * @param byteModuleDataSetContent Zipped module dataset file
     * @param validityStartTime Start time of dataset validity (NULL if not applicable)
     * @param validityEndTime End time of dataset validity (NULL if not applicable)
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    void putModuleDataSet(String clientId, String taskId, String id, byte[] byteModuleDataSetContent, Date validityStartTime, Date validityEndTime, String ensembleId, int ensembleMemberIndex);

    /**
     * Write state information to webservice. The webservice will store this information in the database.
     *
     * <p>
     * The state information consists of two seperate parts. The <i>piStateXmlContent</i> containing information
     * about the state files. And the <i>byteStateContent</i> containing the actual state data for the module.
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param piStateXmlContent  Pi state xml file.
     * @param byteStateFileName  name of the state file data content byte array.
     * @param byteStateContent  State file data content in the form of a byte array.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    void putState(String clientId, String taskId, String piStateXmlContent, String byteStateFileName, byte[] byteStateContent, String ensembleId, int ensembleMemberIndex);


    /**
     * Put a log message
     *
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param piDiagnosticsXmlContent Pi Diagnostics xml file.
     */
    void putLogMessage(String clientId, String piDiagnosticsXmlContent);

    /**
     * Read module dataset information from webservice.
     *
     * <p>
     *Default data set is returned.
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id Id of the module data set .
     * @return Module data set file as byte array.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    byte[] getModuleDataSet(String clientId, String id, String ensembleId, int ensembleMemberIndex);

    /**
     * Read module parameter set information from webservice.
     *
     * <p>
     *Default data parameterSet is returned.
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id name of the binary module parameter set file.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     * @return Module parameter set PiParameters xml.
     */
    String getModuleParameterSet(String clientId, String id, String ensembleId, int ensembleMemberIndex);


    /**
     * Read all available state times for requested state file.
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id Id of the module state .
     * @return All available state times for this module state file.
     */
    Date[] getAvailableStateTimes(String clientId, String id);


    /**
     * Read module state information from webservice.
     *
     * <p>
     *Module state data file is returned for given time. Use method {@link FewsPiService#getAvailableStateTimes(String, String)}
     * to retrieve the available state times.
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id Id of the state .
     * @param stateTime Time for which to retrieve a state file.
     * @return Module state data file as byte array.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. NULL if this is not an ensemble.
     */
    byte[] getModuleStateBinary(String clientId, String id, Date stateTime, String ensembleId, int ensembleMemberIndex);


    /**
     * Read the timeseries from the webservice. Returns a pi timeseries xml file containing the timeseries information.
     *
     * <p>
     * If the ensemble id has been configured for this timeseries then add the <i>ensembleMemberIndex</i> as argument. Use NULL if not an ensemble
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}
     * to obtain valid index values.
     *
     * The TaskId may be NULL or the requested task id.
	 * In case it is TaskId the time series is retrieved for the taskId only for simulated time series
	 * In case it is NULL time series for the current forecast will be retreived
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id Id of the time series string.
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param startTime start date/time of run - NULL if the configured default is to be used
     * @param timeZero Forecast time zero.
     * @param endTime end date/time of run - NULL if the configured default is to be used
     * @param parameterIds Subset of parmaters for which to retrieve timeseries.
     * @param locationIds Subset of locations for which to retrieve timeseries.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. (Only if configured)
     * @return  PiTimeseries xml file content.
     */
    String getTimeSeries(String clientId, String id, String taskId, Date startTime, Date timeZero, Date endTime, String[] parameterIds, String[] locationIds, String ensembleId, int ensembleMemberIndex);


    /**
     * Read the timeseries from the webservice. Returns a pi timeseries xml file
     * containing the timeseries headers information. Retrieve the timeseries data using the method
     * {@link FewsPiService#getTimeSeriesBytes(String, String, String, java.util.Date, java.util.Date, java.util.Date, String[], String[], String, int)}
     *
     * <p>
     * If the ensemble id has been configured for this timeseries then add the <i>ensembleMemberIndex</i> as argument. Otherwise
     * this argument is skipped by the webservice.
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}
     * to obtain valid index values.
     *
     * The TaskId may be NULL or the requested task id.
	 * In case it is TaskId the time series is retrieved for the taskId only for simulated time series
	 * In case it is NULL time series for the current forecast will be retreived
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id Id of the time series string.
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param startTime start date/time of run - NULL if the configured default is to be used
     * @param timeZero Forecast time zero.
     * @param endTime end date/time of run - NULL if the configured default is to be used
     * @param parameterIds Subset of parmaters for which to retrieve timeseries.
     * @param locationIds Subset of locations for which to retrieve timeseries.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. (Only if configured)
     * @return  PiTimeseries xml file content.
     */
    String getTimeSeriesHeaders(String clientId, String id, String taskId, Date startTime, Date timeZero, Date endTime, String[] parameterIds, String[] locationIds, String ensembleId, int ensembleMemberIndex);

    /**
     * Read the timeseries data from the webservice. Returns the data belonging to the
     * timeseries that are retrieved when the method  {@link FewsPiService#getTimeSeriesBytes(String, String, String, java.util.Date, java.util.Date, java.util.Date, String[], String[], String, int)}
     * is called using the same arguments.
     *
     * <p>
     * If the ensemble id has been configured for this timeseries then add the <i>ensembleMemberIndex</i> as argument. Otherwise
     * this argument is skipped by the webservice.
     * Use {@link FewsPiService#getEnsembleMemberIndices(String, String)}
     * to obtain valid index values.
     *
     * The TaskId may be NULL or the requested task id.
	 * In case it is TaskId the time series is retrieved for the taskId only for simulated time series
	 * In case it is NULL time series for the current forecast will be retreived
     *
     * @param clientId Id of webservice configuration that is to be queried
     * @param id Id of the time series string.
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @param startTime start date/time of run - NULL if the configured default is to be used
     * @param timeZero Forecast time zero.
     * @param endTime end date/time of run - NULL if the configured default is to be used
     * @param parameterIds Subset of parmaters for which to retrieve timeseries.
     * @param locationIds Subset of locations for which to retrieve timeseries.
     * @param ensembleId Id of the ensemble
     * @param ensembleMemberIndex Ensemble member index for this time series. (Only if configured)
     * @return  PiTimeseries xml file content.
     */
    byte[] getTimeSeriesBytes(String clientId, String id, String taskId, Date startTime, Date timeZero, Date endTime, String[] parameterIds, String[] locationIds, String ensembleId, int ensembleMemberIndex);

    /**
     * get a log message associated to a specified taskId
     * @param clientId Id of web service client (obtained on command line when invoked)
     * @param taskId  Task id. Obtained using method {@link FewsPiService#createTask(String)}
     * @return PiDiagnostics XML file content.
     */
    String getLogMessages(String clientId, String taskId);


}