Introduction
The Tomcat Fews PI service is hosted in a Tomcat service container. This service allows SOAP clients to interact with a FewsPiService that is connected to a FEWS system through the FEWS DataAccessComponent. With this API the SOAP client can retrieve data from the FEWS system. Before a client application can access the FEWS system there is some configuration work that needs to be done.
Tomcat Fews PI Service API
Description of the methods provided by the Embedded Fews PI Service API.
Getter methods
String getTimeZoneId(String piVersion);
Get ID of Configured timezone for the webservice.
- clientId: <id not used>
- returns: String representation of time zone.
String getFilters(String filterId, String piVersion);
Retrieve Pi Filters configuration from the Fews instance hosting the current FewsPiService.
The PiVersion defines the format of the return file content. If omitted the
latest version of the Pi file format will be used. (Expected 1.9 or higher)
- filterid: Subset filter id. (optional).
- piVersion: File format version (optional).
- returns: PiFilters xml file content.
String getLocations(String clientId, String filterId, String piVersion);
Retrieve Pi Locations file containing all locations that are available for the passed 'filterId' argument.
If argument 'null' is passed then all locations configured in the pre-defined filter will be returned.
The PiVersion defines the format of the return file content. If omitted the latest version of the Pi file format will be used. (Expected 1.9 or higher).
- clientId <id not used>.
- filterId Filter id (optional).
- piVersion File format version (optional)
- returns PiLocations XML file content.
String getParameters(String clientId, String filterId, String piVersion);
Retrieve Pi Parameters file containing all parameters that are available for the passed 'filterId' argument.
If argument 'null' is passed then all parameters configured in the pre-defined filter will be returned.
The PiVersion defines the format of the return file content. If omitted the latest version of the Pi file format will be used. (Expected 1.9 or higher).
- clientId <id not used>.
- filterId Filter id (optional).
- piVersion File format version (optional)
- returns PiTimeSeriesParameters XML file content.
String getTimeSeriesHeadersForFilter(String clientId, Date startTime, Date timeZero, Date endTime, String filterId, String[] locationIds, String[] parameterIds, boolean useDisplayUnits, String piVersion);
Read the timeseries header information from the webservice. Returns a pi timeseries xml file containing the timeseries headers information belonging to the filter defined by the 'filterId'.
Retrieve the timeseries data using the method getTimeSeriesForFilter
The PiVersion defines the format of the return file content. If omitted the latest version of the Pi file format will be used. (Expected 1.9 or higher).
- clientId <id not used>.
- startTime start date/time of run.
- timeZero Forecast time zero. If missing System time is used (optional)
- endTime end date/time of run.
- filterId Filter id (optional).
- locationIds Subset of locations for which to retrieve timeseries (optional).
- parameterIds Subset of parameters for which to retrieve timeseries (optional).
- useDisplayUnits Export values using display units (optional).
- piVersion File format version (optional)
- return PiTimeseries xml file content.
String getTimeSeriesForFilter(String clientId, Date startTime, Date timeZero, Date endTime, String filterId, String[] locationIds, String[] parameterIds, boolean convertDatum, boolean useDisplayUnits, String piVersion);
Returns a pi timeseries xml file containing the timeseries data belonging to the filter defined by the 'filterId'.
The 'convertDatum' argument is to allow timeseries that support a global datum to have their values converted from a value relative to the location height to an absolute value.
The PiVersion defines the format of the return file content. If omitted the latest version of the Pi file format will be used. (Expected 1.9 or higher).
- clientId <id not used>.
- startTime start date/time of run.
- timeZero Forecast time zero. If missing System time is used (optional)
- endTime end date/time of run.
- filterId Filter id (optional).
- locationIds Subset of locations for which to retrieve timeseries (optional).
- parameterIds Subset of parameters for which to retrieve timeseries (optional).
- convertDatum Convert values from relative location height to absolute height values (optional).
- useDisplayUnits Export values using display units (optional).
- piVersion File format version (optional)
- return PiTimeseries xml file content.
Setter methods
void putTimeSeriesForFilters(String clientId, String piTimeSeriesXmlContent, byte[] piTimeSeriesBinaryContent, boolean convertDatum);
Write timeseries data to the FEWS system using the timeseries sets defined by the filters.
For performance reasons it is possible to split the timeseries header information from the timeseries data. The header information is stored in the piTimeSeriesXmlContent and the timeseries data is stored in the piTimeSeriesBinaryContent. If both header information and data is stored in the XML content the the 'piTimeSeriesBinaryContent' argument can be null.
The 'convertDatum' argument is to allow timeseries that support a datum to have their values converted to a value
relative to the location height. If values are already relative to location then enter FALSE or omit.
- clientId <id not used>.
- piTimeSeriesXmlContent PiTimeseries xml file content
- piTimeSeriesBinaryContent FastInfoSet PiTimeseries file content(optional)
- convertDatum Convert values from relative location height to absolute height values (optional).
Installing a Tomcat Fews PI Service
The file DAC installation guide (final).doc describes how to install a Tomcat instance containing a DataAccessComponent instance. Once these steps are completed the FewsPiService.WAR can be deployed using a context xml file such as FewsPiService.xml
Example SOAP calls
See soap-example-calls.zip for examples SOAP client calls.
