/* ================================================================
* 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);
}
|