net.agmodel.weatherData
Interface MetBroker

All Superinterfaces:

GenericBrokerRMI, Remote, ServerRMI

All Known Implementing Classes:

MetBrokerImpl

public interface MetBroker

extends GenericBrokerRMI

Handles:
database connections,
requests for details of databases and weather stations, and
requests for weather data.

Typically a client establishes a MetBroker session through a call to ServerRMI.getConnection(String,String).
The session manages connections to data sources, and also provides lists of available MetDataSources. MetBroker decides how to deal with requests for met data either from single stations, or over geographical areas. The session only exists for the duration of a user session, and doesn't serve any other clients.

Author:

Matthew Laurenson

Field Summary

static String	AMEDAS Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()
static String	CLIDB Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()
static String	FAWN Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()
static String	GAEMN Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()
static String	HRI Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()
static String	PAWS Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()
static String	PREFMETDB Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()
static String	RMIHOSTPARAM
static String	RMINAME The name that MetBroker is registered under in rmiregistry
static String	SASA Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()

Fields inherited from interface net.agmodel.genericBroker.GenericBrokerRMI

EMAIL, HOSTPARAMEXTENSION, NOLOGIN, PASSWORD

Fields inherited from interface net.agmodel.genericBroker.ServerRMI

EXISTINGUSER, NEWUSER, SUPERUSER

Method Summary

boolean[][]	getMetCatalog(String sessionID, String metSourceID, String stationID) Deprecated. Use getWeatherStation instead
MetSourceDetail	getMetSourceDetail(String sessionID, String metSourceID) Gets details about the MetSource in one object.
Region	getRegion(String sessionID, String metSourceID, String regionID) Gets details of a region associated with a data source.
GeographicalArea	getSourceGeographicalArea(String sessionID, String metSourceID) Deprecated. Use getMetSourceDetails or getSourceDetail
int	getSourceLoginRequirements(String sessionID, String metSourceID) Deprecated. Use getMetSourceDetails or getSourceDetail
String	getSourceName(String sessionID, String metSourceID) Deprecated. Use getMetSourceDetail or getSourceDetail
float	getSourceSuggestedDailyOffset(String sessionID, String metSourceID) Deprecated. Use getMetSourceDetails or getSourceDetail
String	getSourceSuggestedTimezone(String sessionID, String metSourceID) Deprecated. Use getMetSourceDetails or getSourceDetail
Location	getStationLocation(String sessionID, String metSourceID, String stationID) Deprecated. Use getWeatherStation instead
String	getStationName(String sessionID, String metSourceID, String stationID) Deprecated. Use getWeatherStation instead
Period	getStationOperational(String sessionID, String metSourceID, String stationID) Deprecated. Use getWeatherStation instead
String	getStationRegionID(String sessionID, String metSourceID, String stationID) Deprecated. Use getWeatherStation instead
String	getStationReport(String sessionID, String metSourceID, String stationID) Deprecated. Use getWeatherStation instead
WeatherStation	getWeatherStation(String sessionID, String metSourceID, String stationID) Get the details of the weather station
WeatherStation[]	listMatchingStations(String sessionID, SpatialMetRequest request) Get an array of all the stations that can potentially contribute to the request.
MetSourceDetail[]	listMetSourceDetails(String sessionID) Get the details for all the MetSources in MetBroker.
MetSourceDetail[]	listMetSourceDetails(String sessionID, GeographicalArea ofInterest) Get the details of the MetSources in MetBroker that coincide with the area specified.
String[]	listMetSources(String sessionID) Deprecated. Use listMetSourceDetails or listSourceDetails
String[]	listMetSources(String sessionID, GeographicalArea ofInterest) Deprecated. Use listMetSourceDetails or listSourceDetails
Region[]	listRegions(String sessionID, String metSourceID) Get a list of all regions for which the database holds data.
WeatherStation[]	listStations(String sessionID, String metSourceID) Get an array of all the stations in a source Typically used by a client application to get a subset of the entire list of stations for a large database.
WeatherStation[]	listStations(String sessionID, String metSourceID, String regionID) Get an array of all the stations that can potentially contribute to the request Typically used by a client application to get a subset of the entire list of stations for a large database.
boolean	loginToMetDataSource(String sessionID, String sourceID) Deprecated. Use loginToDataSource instead
boolean	loginToMetDataSource(String sessionID, String sourceID, String emailAddress) Deprecated. Use loginToDataSource instead
boolean	loginToMetDataSource(String sessionID, String sourceID, String usercode, String password) Deprecated. Use loginToDataSource instead
boolean	metCatalogCardExists(String sessionID, String metSourceID, String stationID, MetElement element, MetDuration resolution) Deprecated. Use getWeatherStation instead
SpatialMetSet	supplyMetData(String sessionID, SpatialMetRequest request) Get the relevant data from multiple stations.
StationDataSet	supplyMetData(String sessionID, StationMetRequest request) Get the relevant data from a single station.

Methods inherited from interface net.agmodel.genericBroker.GenericBrokerRMI

alreadyLoggedIn, getSourceDetail, getSourceID, listSourceDetails, listSourceDetails, loginToDataSource, loginToDataSource, loginToDataSource, logOutOfAllSources, logOutOfSource

Methods inherited from interface net.agmodel.genericBroker.ServerRMI

disconnect, getConnection, getConnection

Field Detail

RMINAME

public static final String RMINAME

The name that MetBroker is registered under in rmiregistry

See Also:

Constant Field Values

RMIHOSTPARAM

public static final String RMIHOSTPARAM

See Also:

Constant Field Values

PREFMETDB

public static final String PREFMETDB

Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()

A small database containing data from various individual sites

See Also:

Constant Field Values

GAEMN

public static final String GAEMN

Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()

The Georgia Agricultural Environment Monitoring Network

See Also:

Constant Field Values

CLIDB

public static final String CLIDB

Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()

The New Zealand National Climate Database

See Also:

Constant Field Values

HRI

public static final String HRI

Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()

Horticulture Research International (UK) database of two sites

See Also:

Constant Field Values

AMEDAS

public static final String AMEDAS

Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()

MAFF's database of AMeDAS data accessed via HTML

See Also:

Constant Field Values

FAWN

public static final String FAWN

Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()

Florida Agricultural Weather Network

See Also:

Constant Field Values

SASA

public static final String SASA

Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()

South African Sugar Association

See Also:

Constant Field Values

PAWS

public static final String PAWS

Deprecated. Use listMetSourceDetails and then MetSourceDetail.getID()

Pacific Automatic Weather Service

See Also:

Constant Field Values

Method Detail

listMetSources

public String[] listMetSources(String sessionID)
                        throws RemoteException,
                               GeneralException

Deprecated. Use listMetSourceDetails or listSourceDetails

Get the IDs for all the MetSources in MetBroker.

Parameters:

sessionID - the ID returned by getConnection

Returns:

a list of sources

Throws:

RemoteException

GeneralException

listMetSources

public String[] listMetSources(String sessionID,
                               GeographicalArea ofInterest)
                        throws RemoteException,
                               GeneralException

Deprecated. Use listMetSourceDetails or listSourceDetails

Get the IDs of the MetSources in MetBroker that coincide with the area specified.

Parameters:

sessionID - the ID returned by getConnection

ofInterest - the area from which weather data is required

Returns:

a list of sources whose GeographicalAreas overlap with the area of Interest

Throws:

RemoteException

GeneralException

listMetSourceDetails

public MetSourceDetail[] listMetSourceDetails(String sessionID)
                                       throws RemoteException,
                                              GeneralException

Get the details for all the MetSources in MetBroker.

Parameters:

sessionID - the ID returned by getConnection

Returns:

a list of sources

Throws:

RemoteException

GeneralException

See Also:

for a generic version

listMetSourceDetails

public MetSourceDetail[] listMetSourceDetails(String sessionID,
                                              GeographicalArea ofInterest)
                                       throws RemoteException,
                                              GeneralException

Get the details of the MetSources in MetBroker that coincide with the area specified.

Parameters:

sessionID - the ID returned by getConnection

ofInterest - the area from which weather data is required

Returns:

a list of sources whose GeographicalAreas overlap with the area of Interest

Throws:

RemoteException

GeneralException

See Also:

for a generic version

loginToMetDataSource

public boolean loginToMetDataSource(String sessionID,
                                    String sourceID,
                                    String usercode,
                                    String password)
                             throws RemoteException,
                                    GeneralException

Deprecated. Use loginToDataSource instead

Establish a connection to the specified database using the usercode and password supplied

Parameters:

sessionID - the ID returned by getConnection

sourceID - the identifier assigned to the source by MetBroker - see listMetSources

usercode - a valid usercode on the source

password - the corresponding password (warning - may be transmitted without encryption)

Returns:

true if the MetBroker was able to log in to the source, false otherwise

Throws:

RemoteException

GeneralException

See Also:

getSourceLoginRequirements(String,String)

loginToMetDataSource

public boolean loginToMetDataSource(String sessionID,
                                    String sourceID,
                                    String emailAddress)
                             throws RemoteException,
                                    GeneralException

Deprecated. Use loginToDataSource instead

Establish a connection to the specified database using the e-mail address supplied as identification.

Parameters:

sessionID - the ID returned by getConnection

sourceID - the identifier assigned to the source by MetBroker - see listMetSources

emailAddress - the user's e-mail address

Returns:

true if the MetBroker was able to log in to the source, false otherwise

Throws:

RemoteException

GeneralException

See Also:

getSourceLoginRequirements(String,String)

loginToMetDataSource

public boolean loginToMetDataSource(String sessionID,
                                    String sourceID)
                             throws RemoteException,
                                    GeneralException

Deprecated. Use loginToDataSource instead

Establish a connection to the specified database without identifying the user in any way

Parameters:

sessionID - the ID returned by getConnection

sourceID - the identifier assigned to the source by MetBroker - see listMetSources

Returns:

true if the MetBroker was able to log in to the source, false otherwise

Throws:

RemoteException

GeneralException

See Also:

getSourceLoginRequirements(String,String)

supplyMetData

public StationDataSet supplyMetData(String sessionID,
                                    StationMetRequest request)
                             throws RemoteException,
                                    GeneralException

Get the relevant data from a single station. If no matching data is found for the query, a StationDataSet is returned rather than null. However, the station data set will not contain any data sequences.

Parameters:

sessionID - the ID returned by getConnection

request - specifies which station get data for, and what data to get

Returns:

the requested data, or an "empty" StationDataSet if no matching data is found.

Throws:

RemoteException

GeneralException

supplyMetData

public SpatialMetSet supplyMetData(String sessionID,
                                   SpatialMetRequest request)
                            throws RemoteException,
                                   GeneralException

Get the relevant data from multiple stations. If a station "should" have data, based on the metadata MetBroker holds, then a StationDataSet will be returned for that station. "Should" means that the station operated during the period of the query and recorded elements of interest at an appropriate resolution. The StationDataSet returned may, however, be empty (as in the single station example).

Parameters:

sessionID - the ID returned by getConnection

request - specifies which area to get data for, and what data to get

Returns:

the requested data

Throws:

RemoteException

GeneralException

getMetSourceDetail

public MetSourceDetail getMetSourceDetail(String sessionID,
                                          String metSourceID)
                                   throws RemoteException

Gets details about the MetSource in one object.

Parameters:

sessionID - the ID returned by getConnection

Returns:

the database details

Throws:

IllegalArgumentException - if the language is not known

RemoteException

See Also:

for a generic version

getSourceName

public String getSourceName(String sessionID,
                            String metSourceID)
                     throws RemoteException,
                            IllegalArgumentException

Deprecated. Use getMetSourceDetail or getSourceDetail

The name of the database, suitable for presentation to the user. Usually this method would be called by MetBroker, which knows the language already.

Parameters:

sessionID - the ID returned by getConnection

Returns:

the name of the database

Throws:

IllegalArgumentException - if the source is not known

RemoteException

getSourceGeographicalArea

public GeographicalArea getSourceGeographicalArea(String sessionID,
                                                  String metSourceID)
                                           throws RemoteException

Deprecated. Use getMetSourceDetails or getSourceDetail

The portion of the globe that the database covers

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier assigned to the source by MetBroker

Returns:

a GeographicalArea which encompasses the locations of all the stations in the database.

Throws:

RemoteException

getSourceLoginRequirements

public int getSourceLoginRequirements(String sessionID,
                                      String metSourceID)
                               throws RemoteException

Deprecated. Use getMetSourceDetails or getSourceDetail

Indicate the usercode and password detail that need to be supplied by users of the database Interpret the result using the constants included with this interface.

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier assigned to the source by MetBroker

Returns:

one of (GenericBrokerRMI.NOLOGIN, GenericBrokerRMI.EMAIL, GenericBrokerRMI.PASSWORD)

Throws:

RemoteException

getSourceSuggestedTimezone

public String getSourceSuggestedTimezone(String sessionID,
                                         String metSourceID)
                                  throws RemoteException

Deprecated. Use getMetSourceDetails or getSourceDetail

Provide client applications with a sensible default timezone for building requests to the database and for displaying the resulting data. The String ID of the timezone is used rather than a TimeZone object for speed of transmission and portability to other languages.

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier assigned to the source by MetBroker

Returns:

the timezone that users of this database are likely to be in.

Throws:

RemoteException

getSourceSuggestedDailyOffset

public float getSourceSuggestedDailyOffset(String sessionID,
                                           String metSourceID)
                                    throws RemoteException

Deprecated. Use getMetSourceDetails or getSourceDetail

Provide client applications with a sensible default offset for building requests for daily data for displaying the resulting data. Daily weather data is usually recorded either at midnight or in the morning at around 9am local time.

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier assigned to the source by MetBroker

Returns:

the number of hours from midnight that the data is recorded,eg if at midnight return 0, if at 9am return 9

Throws:

RemoteException

listRegions

public Region[] listRegions(String sessionID,
                            String metSourceID)
                     throws RemoteException

Get a list of all regions for which the database holds data. "Region" is not precisely defined, but might be prefecture, state or county depending on the database.

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier for the metsource

Returns:

an array of regions, or null if the database has no "region" layer.

Throws:

RemoteException

getRegion

public Region getRegion(String sessionID,
                        String metSourceID,
                        String regionID)
                 throws RemoteException

Gets details of a region associated with a data source. Note that it is more efficient to call listRegions(sessionID, metSourceID) rather than calling getRegion repeatedly.

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier for the metsource

regionID - the identifier for the region

Returns:

a region, or null if the database has no "region" layer or the regionID doesn't exist.

Throws:

RemoteException

listStations

public WeatherStation[] listStations(String sessionID,
                                     String metSourceID)
                              throws RemoteException

Get an array of all the stations in a source Typically used by a client application to get a subset of the entire list of stations for a large database. If the region parameter is null, then all the MetSource's stations are returned.

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier for the metsource

Returns:

an array of ids for the stations which can contribute useful data

Throws:

RemoteException

listStations

public WeatherStation[] listStations(String sessionID,
                                     String metSourceID,
                                     String regionID)
                              throws RemoteException

Get an array of all the stations that can potentially contribute to the request Typically used by a client application to get a subset of the entire list of stations for a large database. If the region parameter is null, then all the MetSource's stations are returned.

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier for the metsource

regionID - specifies the region for which data is required

Returns:

an array of ids for the stations which can contribute useful data

Throws:

RemoteException

listMatchingStations

public WeatherStation[] listMatchingStations(String sessionID,
                                             SpatialMetRequest request)
                                      throws RemoteException

Get an array of all the stations that can potentially contribute to the request.
To contribute, stations must fall within the area specified in the request, and record elements requested, and have operated at some point during the period of interest of the request. The resolution of the request, and whether data may be summarised or temporally interpolated are also taken into account. This method would typically be used by a client application to display stations spatially

Parameters:

sessionID - the ID returned by getConnection

request - specifies the data required

Returns:

an array of WeatherStations which can contribute useful data

Throws:

RemoteException

getWeatherStation

public WeatherStation getWeatherStation(String sessionID,
                                        String metSourceID,
                                        String stationID)
                                 throws RemoteException

Get the details of the weather station

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier assigned to the source by MetBroker

stationID - the identifier for the station used by the host database.

Returns:

the details of the station such as name, location, period of operation.

Throws:

RemoteException

getStationOperational

public Period getStationOperational(String sessionID,
                                    String metSourceID,
                                    String stationID)
                             throws RemoteException

Deprecated. Use getWeatherStation instead

Get the period of operation of the weather station

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier assigned to the source by MetBroker

stationID - the identifier for the station used by the host database.

Returns:

the date when the station began operating, and, if it has closed, the date when it closed.

Throws:

RemoteException

metCatalogCardExists

public boolean metCatalogCardExists(String sessionID,
                                    String metSourceID,
                                    String stationID,
                                    MetElement element,
                                    MetDuration resolution)
                             throws RemoteException

Deprecated. Use getWeatherStation instead

Check whether a station has ever recorded an element at a particular resolution.

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier assigned to the source by MetBroker

stationID - the identifier for the station used by the host database.

element - the weather element of interest

resolution - the temporal resolution (eg hourly or daily)

Returns:

true if it has recorded the element, false if it hasn't.

Throws:

RemoteException

getMetCatalog

public boolean[][] getMetCatalog(String sessionID,
                                 String metSourceID,
                                 String stationID)
                          throws RemoteException

Deprecated. Use getWeatherStation instead

Check whether a station has ever recorded an element at a particular resolution.

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier assigned to the source by MetBroker

stationID - the identifier for the station used by the host database.

Returns:

true if it has recorded the element, false if it hasn't.

Throws:

RemoteException

getStationReport

public String getStationReport(String sessionID,
                               String metSourceID,
                               String stationID)
                        throws RemoteException

Deprecated. Use getWeatherStation instead

Provide a description of the station and the data it holds

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier assigned to the source by MetBroker

stationID - the identifier for the station used by the host database.

Returns:

a summary of the station's metadata

Throws:

RemoteException

getStationName

public String getStationName(String sessionID,
                             String metSourceID,
                             String stationID)
                      throws RemoteException

Deprecated. Use getWeatherStation instead

Get the weather station's location's name.

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier assigned to the source by MetBroker

stationID - the identifier for the station used by the host database.

Returns:

the name of the place where the station is located, in the language specified at initialization

Throws:

RemoteException

getStationRegionID

public String getStationRegionID(String sessionID,
                                 String metSourceID,
                                 String stationID)
                          throws RemoteException

Deprecated. Use getWeatherStation instead

Get the weather station's current region ID.

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier assigned to the source by MetBroker

stationID - the identifier for the station used by the host database.

Returns:

the ID of the region that the station is currently under, or null if no reqions are used

Throws:

RemoteException

getStationLocation

public Location getStationLocation(String sessionID,
                                   String metSourceID,
                                   String stationID)
                            throws RemoteException

Deprecated. Use getWeatherStation instead

Get the weather station's position on the globe.

Parameters:

sessionID - the ID returned by getConnection

metSourceID - the identifier assigned to the source by MetBroker

stationID - the identifier for the station used by the host database.

Returns:

the location of the station (latitude, longitude and altitude)

Throws:

RemoteException