Introduction
The Fews PI service data exchange uses XFire, a java SOAP framework. This framework allows a client application to obtain a proxy instance to the FewsPiService API. With this API the client can retrieve data from an OC or write data to an OC. Before a client application can access the FEWS system there is some configuration work that needs to be done.
User's looking to use XFire on a new project, should use CXF instead. CXF is a continuation of the XFire project and is considered XFire 2.0. It has many new features, a ton of bug fixes, and is now JAX-WS compliant! XFire will continue to be maintained through bug fix releases, but most development will occur on CXF now. For more information see the XFire/Celtix merge FAQ and the CXF website.
Fews PI Service API
Setting up PI Service Client
Example code
Appendix
FewsPiService API
/* ================================================================ * 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); }