Page History

The embedded SOAP PI service is being phased out. Since 2022.02 the embedded REST service is used instead.

Note! Please note that the argument names generated by XFire for the embedded FewsPiService are not descriptive. So in the section below we added descriptive identifiers to make the documentation more clear. When writing a client application always use the argument names provided in the fewsPiServiceWSDL.xml.

String getClientConfigFile(String in0, String in1);

String getTimeZoneId(String in0);

String getFilters(String in0);

String getTimeSeriesHeaders(String in0, String in1, String in2, Date in3,
		Date in4, Date in5, String[] in6, String[] in7, String in8, int in9,
		boolean in10);

String[] getAllNodesWithDataset();

void setSystemTime(Date in0);

float[] convertToDisplayUnitValue(String in0, float[] in1);

void saveDataSet(String in0, String in1, byte[] in2, String in3, String in4);

ObjectServiceFactory serviceFactory = new ObjectServiceFactory();
Service service = serviceFactory.create(FewsPiService.class);
XFireProxyFactory proxyFactory = new XFireProxyFactory();
 //port Number must be equal to the number configured in the Explorer.xml
int portNumber = 8100;
//localhost can be replaced by the ip address of the machine on which the FEWS system is running.
FewsPiService serviceProxy = (FewsPiService) proxyFactory.create(service, "http://localhost:" + portNumber + "/FewsPiService")

#include <stdio.h>
#include <tcl.h>

/* Define some helper variables and functions */

Tcl_Interp *interp;

int main( int argc, char *argv[] ) {

    /* Get the library started */

    if ( Init( argv[0] ) != TCL_OK ) {
        fprintf( stderr, "Sorry, initialisation failed: %s\n",
            Tcl_GetStringResult( interp ) );
    }

    /* Here insert calls to Pi Service */
    fprintf( stdout, "Locations: %s\n", getLocations( "id not required" ) );
    fprintf( stdout, "New task: %s\n", createTask( "id not required" ) );
}

void TearDown () {Tcl_Finalize();}

int EvalFile (char *fileName) {
    return Tcl_EvalFile(interp, fileName);
}

int Init (char *argv0) {
    char *pchar;
    char  buffer[1000];

    /* Initialise the library itself */

    Tcl_FindExecutable(argv0);
    interp = Tcl_CreateInterp();
    if (Tcl_Init(interp) != TCL_OK) {
        return TCL_ERROR;
    }

    /* Initialise the FEWS PI services */

    strcpy( buffer, argv0 );
    pchar = strrchr( buffer, '/' );
    if ( pchar == NULL ) {
        pchar = strrchr( buffer, '\\' );
    }
    if ( pchar == NULL ) {
        pchar = buffer;
    }
    strcpy( buffer, "fewspi.tcl" );

    return EvalFile( buffer );
}

   /**
     * Test the retrieval of system time.
     * <p/>
     * With this test the system time of a running Fews Region (on port 8191) can be retrieved. If the
     * system time of the region is changed then the returned value here will match the change.
     */
    public void testSystemTime() {
        String clientId = "not required";
        Date date = serviceProxy.getSystemTime(clientId);


        System.out.println("Current System time : " + dateFormat.format(date));
    }

    /**
     * Return the warm state times from the data base for the configured moduleState id=RSNWELEV_DETO3I
     * in the service configuration file = TestConfig.
     */
    public void testGetWarmStateTimes() {
        //name of service config file
        String clientId = "TestConfig";
        //id of moduleState element
        String moduleId = "RSNWELEV_DETO3I";

        Date[] stateTimes = serviceProxy.getAvailableStateTimes(clientId, moduleId);

        System.out.println("State times for Module " + moduleId);
        for (Date stateTime : stateTimes) {
            System.out.println("time: " + dateFormat.format(stateTime));
        }
    }

    /**
     * Return the cold state ids from the data base for the configured moduleState id=RSNWELEV_DETO3I
     * in the service configuration file = TestConfig.
     */
    public void testGetColdStateIds() {
        //name of service config file
        String clientId = "TestConfig";
        //id of moduleState element
        String moduleId = "RSNWELEV_DETO3I";

        String[] stateIds = serviceProxy.getColdStateIds(clientId, moduleId);

        System.out.println("Cold state ids for model " + moduleId);
        for (String id : stateIds) {
            System.out.println("cold state: " + id);
        }
    }

    /**
     * Return the warm state file from the data base for the configured moduleState id=SNOW17_LSMO3U
     * in the service configuration file = TestConfig. Write file to location d:/temp/<moduleStateId>.zip
     */
    public void testGetModuleStateBinary() throws IOException {
        //name of service config file
        String clientId = "TestConfig";
        //id of moduleState element
        String moduleId = "SNOW17_LSMO3U";

        Date[] stateTimes = serviceProxy.getAvailableStateTimes(clientId, moduleId);
        byte[] binary = serviceProxy.getModuleStateBinary(clientId, moduleId, stateTimes[0], null, -1);

        ZipInputStream zipInputStream = new ZipInputStream(new ByteArrayInputStream(binary));
        try {
            ZipUtils.unzipFiles(zipInputStream, new File("d:/temp/" + moduleId + ".zip"));
        } finally {
            zipInputStream.close();
        }
    }

    /**
     * Returns the content of a client configuration file from the config directory PiClientConfigFiles.
     *
     * Only requirement is that a configuration file (any type) with the clientId as name and moduleId as extension
     * must exist in this config directory.
     */
    public void testGetClientConfigurationFile(){
        //Name of client file
        String clientId = "MyClientConfigFile";
        //extension of client file
        String moduleId = "txt";

        String clientText = serviceProxy.getClientConfigFile(clientId, moduleId);

        System.out.println("Client file content: " + clientText);

    }

    /**
     * Retrieve the content of the locations xml. Write this to d:/temp/locations.xml
     * @throws IOException
     */
    public void testGetLocations() throws IOException {

        String locations = serviceProxy.getLocations("id not required");

        System.out.println("Content of locations xml file: " + locations);
        FileUtils.writeText("d:/temp/locations.xml", IOUtils.UTF8_CHARSET, locations);

    }

    /**
     * Return the member indices for the ensemble id = "ESP" from the timeseries table.
     *
     * This only works when there are ensemble members in the TimeSeries table.
     */
    public void testGetEnsembleMemberIndices(){

        String ensembleId = "ESP";
        int[] indices = serviceProxy.getEnsembleMemberIndices("id not required", ensembleId);

        System.out.println("Ensemble id " + ensembleId + " contains " + indices.length + " members.");
        System.out.println("indices are: ");
        for (int indice : indices) {
            System.out.println(indice);
        }

    }

    /**
     * Get the logentries for an Import TaskId.
     *
     * Check the LogEntries table to find a matching taskId.
     *
     * @throws IOException
     */
    public void testGetLogInformation() throws IOException {

        String taskId = "NWSNWMC00:0000026"; //=import
        String logInfo = serviceProxy.getLogMessages("id not required", taskId);

        System.out.println("Content of log: " + logInfo);
        FileUtils.writeText("d:/temp/log.xml", IOUtils.UTF8_CHARSET, logInfo);

    }

    /**
     * Return the timeseries defined in the service configuration file under timeSeries element with id 'Reservoir'.
     *
     * Filter using parameter ids QIN and RQIN and location ids DETO3, GPRO3 and FOSO3
     *
     * Check timeseries table to look for existing times for these timeseries.
     *
     * @throws IOException
     */
    public void testGetTimeSeries() throws IOException {

        Date systemTime = serviceProxy.getSystemTime("id not required");
        Calendar instance = GregorianCalendar.getInstance(TimeZone.getTimeZone("GMT"));
        instance.set(2009, 4, 1);
        Date start = instance.getTime();
        instance.set(2009, 4, 11);
        Date end = instance.getTime();
        String[] params = new String[]{"QIN", "RQIN"};
        String[] locs = new String[]{"DETO3","GPRO3","FOSO3"};
        String headers = serviceProxy.getTimeSeriesHeaders("TestConfig", "Reservoir", null, start, systemTime, end, params, locs, null, -1);

        System.out.println("Content of tineseries headers: " + headers);

        String timeseriesfile = serviceProxy.getTimeSeries("TestConfig", "Reservoir", null, start, systemTime, end, params, locs, null, -1);

        FileUtils.writeText("d:/temp/timeseries.xml", IOUtils.UTF8_CHARSET, timeseriesfile);

    }

    /**
     * Upload a pi_diag log file to the region.
     *
     * Make sure to create an input file in corresponding directory.
     *
     * @throws IOException
     */
    public void testInsertLogMessages() throws IOException {

        String logText = FileUtils.readText("d:/temp/inputlog.xml");
        serviceProxy.putLogMessage("used as description", logText);
    }

    /**
     * Upload a pi_timeseries file to the Region. The timeseries in this file must be linked to timeseries configured
     * in the PiServiceConfig file.
     *
     * Make sure to create an input file in the corresponding directory.
     *
     * @throws IOException
     */
    public void testInsertTimeSeries() throws IOException {

        String timeseriesText = FileUtils.readText("d:/temp/inputtimeseries.xml");
        System.out.println("Input timeseries: " + timeseriesText);
        serviceProxy.putTimeSeries("TestConfig", null, "Reservoir", timeseriesText, null, -1);
    }

    /**
     * Schedule a task run and wait for it to finish.
     *
     */
    public void testRunningTask(){
        String taskId = serviceProxy.createTask("id not required");
        Date date = serviceProxy.getSystemTime("");
        System.out.println("Starting task with id " + taskId + " time=" + new Date(System.currentTimeMillis()));
        String taskRunId = serviceProxy.runTask("id not required", taskId, "Santiam_Forecast", date, date, date, null, null, "Test user", "PiWebservice taskrun");

        boolean result = serviceProxy.waitForTask("id not required", taskRunId, 120000);
        System.out.println("Task with id " + taskId + (result ? " finished successfully" : " failed"));
        System.out.println("time=" + new Date(System.currentTimeMillis()));
    }

/* Fews PI services: wrapper functions */

char *getLocations( char *clientId ) {
    char buffer[1000];

    strcpy( buffer, "getLocations " );
    strcat( buffer, clientId );

    if ( Tcl_Eval( interp, buffer ) != TCL_OK )
{
        return NULL;
    } else {
        return Tcl_GetStringResult( interp ) ;
    }
}

char *createTask( char *clientId ) {
    Tcl_Obj *obj[2];

    obj[0] = Tcl_NewStringObj( "createTask", -1 );
    obj[1] = Tcl_NewStringObj( clientId, -1 );

    Tcl_IncrRefCount( obj[0] ) ;
    Tcl_IncrRefCount( obj[1] ) ;

    if ( Tcl_EvalObjv( interp, 2, obj, 0 ) != TCL_OK ) {
        return NULL;
    } else {

        Tcl_DecrRefCount( obj[0] ) ;
        Tcl_DecrRefCount( obj[1] ) ;
        return Tcl_GetStringResult( interp ) ;
    }
}

/* ================================================================
 * 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 scenarioId String identifying the "what if" scenario - NULL if not used
     * @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);


}