| MultiGraph: Multi-Purpose Interactive Scientific Graphics for Java | ||
|---|---|---|
| Prev | Chapter 4. MultiGraphlet Configuration and Usage | Next |
MultiGraphlet uses HTTP requests to fetch the data it needs from a data server. The data server is a program, running on the same web server where MultiGraphlet resides, that receives requests from MultiGraphlet and responds with the requested data. The details of the requested data are specified in parameters encoded into the request URL, and data server returns the requested data in an XML format described below.
The parameters that MultiGraphlet passes to the data server are:
| first |
The hour of the first observation to return, in UTC (GMT). The format should be YYYYMMDDHH, where YYYY=year, MM=month (01-12), DD=day (00-31), and HH=hour (00-23). There should be exactly 10 characters in this string; if the month, day, and/or hour are less than 10, be sure to use a leading 0 to make them 2 digits each. For example, "2004112909" means 9am on November 28, 2004. |
| last |
The hour of the last observation to return, in UTC (GMT). The is the same as for "first". The hour specified by "last" should be chronologically after "first". |
| data |
A string specifying which station to return data from, and which data element(s) to return. The string consists of a station id, followed by a colon, followed by a comma-separated list of data fields. The station id is the id number (an integer) of the station to return data from. It will be the id of one of the stations in the station list returned by the station server described in Section 4.2, or the id number of the single station given by the "station_id" applet parameter (see Section 4.5) if you you have no station server. Each data field will be the "field" value given for one of the data elements in your graph specification; see Section 4.3 for details. |
| getpor |
If this parameter is present it should have the value "1", to indicate that a period of record is being requested, rather than data. See below for details. |
MultiGraphlet generates two types of requests that it sends to the data server: a "POR request", and a "data request". The data server should respond with a different type of response for each type of request.
In a data request, the "getpor" parameter is not present. The data server should respond with the data described in the "data" parameter for the period of time starting with the "first" parameter and ending with the "last" parameter. The returned data should be in an XML format that looks like the following:
<timeseriesdata dim="DIM" first="FIRST" last="LAST" count="COUNT">
<data>
...
</data>
</timeseriesdata>
The word DIM in the above stands for the dimension of the data being returned --- this is the number of data fields being returned (which is the same as the number of fields specified in the "data" parameter). The words FIRST and LAST stand for the hour of the first and last observation being returned, in the same format used for the "first" and "last" parameters. These are usually the same values as the "first" and "last" parameters, but might be different if the requested station does not have data for all of the requested period. The word COUNT stands for the number of observations being returned.
The ... in the above stands for the actual data. It consists of COUNT lines, with one list of comma-separated values per line.
For example, if the data server is called with the argument string "first=2004110900&last=2004110903&data=1029:TEMP", it might return:
<timeseriesdata dim="1" first="2004110900" last="2004110903" count="4">
<data>
17.78
16.17
15.09
14.39
</data>
</timeseriesdata>
Or, for an example with more than one element, if the data server is called with the argument string "first=2004110900&last=2004110903&data=1029:TEMP,WIND", it might return:
<timeseriesdata dim="2" first="2004110900" last="2004110903" count="4">
<data>
+17.78,+0.549
+16.17,+0.477
+15.09,+0.651
+14.39,+0.687
</data>
</timeseriesdata>
In a POR request, the "getpor" parameter is present and has the value "1". In this kind of request, the "first" and "last" parameters are not present (or are ignored if they are present). A POR request should return information about the period of record for a station. The "period of record" is the period of time for which data is available. MultiGraphlet uses this information to give a visual indication of the beginning and end of the period of record, in case the time period on view extends beyond that period either forwards or backwards in time. It also uses the period of record to avoid making useless data requests for data outside that period.
When the data server gets a POR request (indicated by the fact that the "getpor" parameter is present and has the value "1"), it should examine the "data" parameter to find the station id number, and should then return an XML description of that station's period of record. (It should ignore the field list part of the "data" parameter.) The format of this description is as follows:
<timeseriespor>
<start>YYYYMMDDHH00</start>
<end>YYYYMMDDHH00</end>
</timeseriespor>
where YYYY=year, MM=month (01-12), DD=day (00-31), HH=hour (00-23). Note HH must be followed by two zeros; the start and end values must both be exactly 12 characters long; pad any single-digit numbers with leading zeros if necessary.
For example, if the data server is called with the argument string "getpor=1&data=1029:TEMP", it might return:
<timeseriespor>
<start>200207131400</start>
<end>200411161400</end>
</timeseriespor>
MultiGraphlet echos the URLs of the data server requests it generates to standard error; you can see these requests if you open the java console in your browser while you have a MultiGraphlet window up. They are printed as if they were calls to the Unix program "wget"; you can cut and past them from the java console to a unix shell to issue the requests by hand in order to see what the data server returns. (MultiGraphlet does not actually use wget when it fetches the URLs --- it just formats the requests this way when printing them, to aid in debugging.)