MetSOAP Documentation

MetSOAP Documentation

See:
Description

Packages

net.agmodel.metsoap

MetSOAP Documentation

This documentation is aimed at software developers who need flexible access to weather data within their applications. It describes how MetBroker can be accessed through a SOAP-based WebService. The documentation was automatically generated from the Java versions of MetSOAP classes but serves as a reasonable guide to how MetSOAP can be used in other languages.

MetBroker provides consistent access to various online weather databases. MetBroker can be accessed from Java applications using Java Remote Method Invocation (RMI). Unfortunately, on Java applications can communicate using RMI. RMI is also often blocked by firewalls. SOAP provides a language-independent way of executing Remote Procedure Calls (RPCs). This means that an application written in Visual Basic or Delphi can call procedures on and receive data from a server written in Java. Many other language combinations are possible. SOAP is based on XML, but if all works well you will never have to see any XML.

MetSOAP's operation

Applications interact with MetBroker by sending requests and receiving back responses. Usually the requests look like function calls in your favourite language. The function results are objects (instances of classes or user-defined types) or arrays of objects. This documentation describes both the function calls and the resulting objects. Here is a little diagram that shows interactions between two client applications and MetSOAP:

MetSOAP works using a family of SOAP objects. These objects can be mapped to corresponding objects in Java, VB or Delphi. One of the main jobs of the various toolkits is to transform (map) between SOAP objects and language-specific classes or types. Taking Visual Basic in the diagram above as an example, a typical interaction with MetBroker would proceed as follows:

1. The VB application requests a "stub" object from the toolkit - this stub relays function calls and results across the Web to MetSOAP, but makes them look like local function calls.
2. The VB calls a local function on the stub corresponding to a MetBroker function and passes several parameters.
3. The stub converts this local call to a SOAP request to MetSOAP, which relays the request to MetBroker.
4. MetSOAP gets a result object back from MetBroker, and sends a SOAP response object back to the stub
5. The stub converts the SOAP response into a Visual Basic object, and returns a reference to the object to calling program
6. The calling program retrieves data from the local object.

StationData Structure

The station data that comes back from MetSOAP has the following structure:

The StationData object contains an array of ElementData objects - one for each kind of meteorological variable (eg Air Temperature, Rainfall). Each ElementData object contains one ore more DataStore objects (eg an Element Data object containing daily air temperatures might contain a DataStore of minimum temperatures, and a DataStore of maximum temperatures. An ElementData object containing soil temperatures might contain a DataStore for each depth.) Each DataStore contains a single float array of data values.

In addition to the data in the ElementData array, the StationData object also contains a WeatherStation object, which describes the station that the data came from, and identifies the database and region if any.

Metadata objects

In addition to providing weather data, MetSOAP also makes available details of what data is available. This diagram shows the main metadata classes, including the WeatherStation class mentioned in the preceding section, and the relationships between them.

Instances of the MetSource class hold details about each database. Instances of the Region class hold details about regions within a database. Larger databases are more likely to group stations into regions.

Request Objects

The earlier description of how applications request data from MetSOAP neglected to mention that the request itself is sometimes a class. This diagram shows the MetSOAP request classes.

At present, StationMetRequest is the only option, but soon it will be joined by a Spatial Request that specifies the required stations in terms of a GeographicalBox. To request weather data, an application creates an instance of StationMetRequest, sets the various values, and then passes it to the getStationData function as the main parameter.

WSDL file

The key file that describes the MetSOAP service is MetSOAP.wsdl. "wsdl" is short for "Web Services Definition Language" and this file contains a definition of the service that is readable by both SOAP tools and people. You can view wsdl files using Internet Explorer or other XML viewers. To access the service described in these documents, you will need to have some SOAP tools for your particular programming language. Examples include the enterprise version of Delphi, the Microsoft SOAP Toolkit (freely available from Microsoft) for Visual Basic, ASP, Visual C++, and tools like GLUE. If you need help, tools are available from companies such as Cape Science (www.capescience.com) that will automatically generate VB or Java client applications from wsdl files.