com.oopitis.weather
Class WeatherService<L extends GeoLocation,Q extends QueryHint,R extends WeatherReport>

java.lang.Object
  com.oopitis.weather.WeatherService<L,Q,R>

Type Parameters:

L - the type of the location objects for queries

Q - the type of the query hints

R - the type of the weather reports

Direct Known Subclasses:

FioWeather, OwmWeather

public abstract class WeatherService<L extends GeoLocation,Q extends QueryHint,R extends WeatherReport>
extends java.lang.Object

A service that reports weather conditions for a location based on a query hint. A weather service supports a list of features. Each feature is a group of weather data that share the same semantics. Such information is represented by a list of weather properties. In other words, a feature is always associated with a list of weather properties. Common features are defined in this class such as CONDITIONS and CONDITIONS_DAY, which represent the current weather conditions and daily weather conditions respectively. This class also defines common properties such as TempCelsius or SunsetTime.

To obtain weather information, an instance of this class is required. This class is a common interface for different data sources to provide weather information without the users understanding the proprietary protocols. At the same time, each provider can extend the interfaces and classes in this package or define new features and properties to support provider-specific operations. For example, service providers may extend GeoLocation to allow users to describe a location in a way that is more suitable for their database.

The simplest form of data query returns reports from basic features a service provides:

 List<? extends WeatherReport> reports = service.query(location);

Other variances allow users to indicate properties of interest or features to include:

 // Get reports where sunset time is applicable.
 List<? extends WeatherReport> reports = service.query(location, 
         WeatherService.SunsetTime);
 
 // Get reports that contain precipitation related properties as well as 
 // reports from ALERT feature.
 List<? extends WeatherReport> reports = service.query(location, 
         WeatherService.Precipitation, WeatherService.ALERT);
 
 // Get hourly weather reports.
 List<? extends WeatherReport> reports = service.query(location, 
         WeatherService.CONDITIONS_HOUR);

More sophisticated queries require the use of a QueryHint object:

 QueryHint h = service.newQueryHint();
 h.include(WeatherService.HumidityPercent);
 h.exclude(WeatherService.CONDITIONS_MINUTE);
 
 // Get reports that contain humidity data but not minute-by-minute reports
 // even though minute-by-minute reports also contain humidity data.
 List<? extends WeatherReport> reports = service.query(location, h);

Once a list of reports is obtained, users can examine the time, feature and location of each report and determine which reports are truly relevant. Utility methods are provided to further refine the result:

 List<Feature> features = WeatherService.listFeatures(reports);
 if (features.contains(WeatherService.CONDITIONS_HOUR)) {
     reports = WeatherService.subList(reports, WeatherService.CONDITIONS_HOUR);
     reports1 = WeatherService.subList(reports, tonight9pm, tomorrow11am);
     reports2 = WeatherService.subList(reports, tomorrow3pm, null);
 }

Finally, to get data from a report and display it, a weather property is used as a key to retrieve data and as a formatter to format data:

 for (WeatherReport r: reports) {
     Float t = r.get(WeatherService.TempMaxCelsius);
     Date d = r.get(WeatherService.TempMaxTime);
 
     System.out.printf("%s %s at %s\n", WeatherService.TempMaxCelsius, 
             WeatherService.TempMaxCelsius.format(t), 
             WeatherService.TempMaxTime.format(d));
 }

Notice how weather properties are typed and type casting is not required. In fact, a compilation error will occur if the data is assigned to the wrong type. The data however can be assigned to an Object reference. This is the case when a property set is used to retrieve data:

 for (WeatherReport r: reports) {
     Map<WeatherProperty, Object> windData = r.get(WeatherService.Wind);
     for (Iterator<WeatherProperty> it = windData.keySet().iterator(); 
             it.hasNext();) {
         WeatherProperty p = it.next();
         Object data = windData.get(p);
     }
 }

A service also provides basic presentation of the weather reports:

 List<WeatherReport> reports = service.query(location);
 service.print(System.out, reports);

In this case, the reports cannot be assigned to an upper bounded wildcard because print can only handle the type of reports the service supports.

While generally it is the best to consult documentation about which information an instance of this class can provide, it is possible to discover the features a service supports by calling getSupportedFeatures() and the properties associated with a feature by calling getApplicableProperties(Feature). All Feature and WeatherProperty objects have constant names, which are fully qualified names of the Java identifiers they are assigned to.

Field Summary

static WeatherPropertySet	Alert Weather alert related properties.
static Feature	ALERT A feature that provides weather alerts.
static WeatherProperty<java.lang.String>	AlertDescription The description of a weather alert.
static WeatherProperty<java.lang.String>	AlertTitle The title of a weather alert.
static WeatherPropertySet	Astronomy Astronomy related properties.
static WeatherProperty<java.lang.Float>	CloudCoverPercent Cloud cover in percentages.
static Feature	CONDITIONS A feature that provides reports for weather conditions at a given time.
static Feature	CONDITIONS_DAY A feature that provides day-by-day weather reports.
static Feature	CONDITIONS_HOUR A feature that provides hour-by-hour weather reports.
static Feature	CONDITIONS_MINUTE A feature that provides minute-by-minute weather reports.
static WeatherProperty<java.lang.Float>	DewPointCelsius Dew point in degrees Celsius.
static WeatherProperty<java.lang.Float>	HumidityPercent Humidity in percentages.
static WeatherProperty<java.lang.Float>	OzoneColumnarDensityDU Ozone columnar density in Dobson units.
static WeatherProperty<java.lang.Float>	PrecipAccumCentimeter The accumulated precipitation over a given period of time in centimeters.
static WeatherProperty<PrecipitationForm>	PrecipForm The form of precipitation.
static WeatherPropertySet	Precipitation Precipitation related properties.
static WeatherProperty<java.lang.Float>	PrecipMaxMillimeterPerHour The maximum precipitation in a given period of time in millimeters of liquid water per hour.
static WeatherProperty<java.util.Date>	PrecipMaxTime The time when the maximum precipitation occurs.
static WeatherProperty<java.lang.Float>	PrecipMillimeterPerHour The precipitation in millimeters of liquid water per hour.
static WeatherProperty<java.lang.Float>	PrecipProbabilityPercent The probability of precipitation.
static WeatherProperty<java.lang.Float>	PressureHectopascal Atmospheric pressure in hectopascal.
static WeatherProperty<java.util.Date>	SunriseTime The time of sunrise.
static WeatherProperty<java.util.Date>	SunsetTime The time of sunset.
static WeatherProperty<java.lang.Float>	TempCelsius The temperature at a given time in degrees Celsius.
static WeatherPropertySet	Temperature Temperature related properties.
static WeatherProperty<java.lang.Float>	TempMaxCelsius The maximum temperature in a given period of time in degrees Celsius.
static WeatherProperty<java.util.Date>	TempMaxTime The time when the maximum temperature occurs.
static WeatherProperty<java.lang.Float>	TempMinCelsius The minimum temperature in a given period of time in degrees Celsius.
static WeatherProperty<java.util.Date>	TempMinTime The time when the minimum temperature occurs.
static WeatherProperty<java.lang.Float>	UltravioletIndex Ultraviolet index.
static WeatherProperty<java.lang.Float>	VisibilityKilometer Visibility in kilometers.
static WeatherPropertySet	Wind Wind related properties.
static WeatherProperty<java.lang.Float>	WindDirectionDegree The direction from which the wind originates in degrees, with true north in zero degree and moving clockwise.
static WeatherProperty<java.lang.Float>	WindMeterPerSecond The wind speed in meters per second.

Constructor Summary

protected

WeatherService() Constructs a weather service.

Method Summary

protected java.util.Set<Feature>	getApplicableFeatures(Q hint) Derives the set of relevant features from a query hint.
abstract WeatherPropertySet	getApplicableProperties(Feature f) Gets the set of properties applicable to a feature.
abstract java.util.Set<Feature>	getBasicFeatures() Returns the set of features for which the weather reports are created when the query hint does not exist or does not specify properties of interest or features to include.
abstract java.util.Set<Feature>	getSupportedFeatures() Gets all features this service supports.
static java.util.List<Feature>	listFeatures(java.util.List<? extends WeatherReport> list) Lists all features referenced by a list of weather reports.
abstract Q	newQueryHint() Creates a new query hint.
void	print(java.io.PrintStream out, java.util.List<R> reports) Prints a list of weather reports to a print stream.
java.util.List<R>	query(L location) Queries the data source for a location about the weather information from the basic features this service provides.
abstract java.util.List<R>	query(L location, java.util.Date beginDate, Q hint) Queries the data source about the weather in a location from a specific date onward.
java.util.List<R>	query(L location, Feature f, Feature... ff) Queries the data source for a location about the weather information from a list of features.
java.util.List<R>	query(L location, Q hint) Queries the data source about the weather in a location.
java.util.List<R>	query(L location, Queryable q, Feature f, Feature... ff) Queries the data source for a location about the weather information that includes the given queryable and list of features.
java.util.List<R>	query(L location, Queryable q, Queryable... others) Queries the data source for a location about the weather information that includes a list of queryables.
static <T extends WeatherReport> java.util.List<T>	subList(java.util.List<T> list, java.util.Date beginDate, java.util.Date endDate) Extracts the list of weather reports between two dates.
static <T extends WeatherReport> java.util.List<T>	subList(java.util.List<T> list, Feature f) Extracts the list of weather reports that belong to a feature.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AlertTitle

public static final WeatherProperty<java.lang.String> AlertTitle

The title of a weather alert.

AlertDescription

public static final WeatherProperty<java.lang.String> AlertDescription

The description of a weather alert.

SunriseTime

public static final WeatherProperty<java.util.Date> SunriseTime

The time of sunrise.

SunsetTime

public static final WeatherProperty<java.util.Date> SunsetTime

The time of sunset.

TempCelsius

public static final WeatherProperty<java.lang.Float> TempCelsius

The temperature at a given time in degrees Celsius.

TempMinCelsius

public static final WeatherProperty<java.lang.Float> TempMinCelsius

The minimum temperature in a given period of time in degrees Celsius.

TempMinTime

public static final WeatherProperty<java.util.Date> TempMinTime

The time when the minimum temperature occurs.

TempMaxCelsius

public static final WeatherProperty<java.lang.Float> TempMaxCelsius

The maximum temperature in a given period of time in degrees Celsius.

TempMaxTime

public static final WeatherProperty<java.util.Date> TempMaxTime

The time when the maximum temperature occurs.

HumidityPercent

public static final WeatherProperty<java.lang.Float> HumidityPercent

Humidity in percentages.

DewPointCelsius

public static final WeatherProperty<java.lang.Float> DewPointCelsius

Dew point in degrees Celsius.

PrecipForm

public static final WeatherProperty<PrecipitationForm> PrecipForm

The form of precipitation.

See Also:

PrecipitationForm

PrecipMillimeterPerHour

public static final WeatherProperty<java.lang.Float> PrecipMillimeterPerHour

The precipitation in millimeters of liquid water per hour.

PrecipProbabilityPercent

public static final WeatherProperty<java.lang.Float> PrecipProbabilityPercent

The probability of precipitation.

PrecipMaxMillimeterPerHour

public static final WeatherProperty<java.lang.Float> PrecipMaxMillimeterPerHour

The maximum precipitation in a given period of time in millimeters of liquid water per hour.

PrecipMaxTime

public static final WeatherProperty<java.util.Date> PrecipMaxTime

The time when the maximum precipitation occurs.

PrecipAccumCentimeter

public static final WeatherProperty<java.lang.Float> PrecipAccumCentimeter

The accumulated precipitation over a given period of time in centimeters.

WindMeterPerSecond

public static final WeatherProperty<java.lang.Float> WindMeterPerSecond

The wind speed in meters per second.

WindDirectionDegree

public static final WeatherProperty<java.lang.Float> WindDirectionDegree

The direction from which the wind originates in degrees, with true north in zero degree and moving clockwise.

CloudCoverPercent

public static final WeatherProperty<java.lang.Float> CloudCoverPercent

Cloud cover in percentages.

VisibilityKilometer

public static final WeatherProperty<java.lang.Float> VisibilityKilometer

Visibility in kilometers.

PressureHectopascal

public static final WeatherProperty<java.lang.Float> PressureHectopascal

Atmospheric pressure in hectopascal.

UltravioletIndex

public static final WeatherProperty<java.lang.Float> UltravioletIndex

Ultraviolet index.

OzoneColumnarDensityDU

public static final WeatherProperty<java.lang.Float> OzoneColumnarDensityDU

Ozone columnar density in Dobson units.

Alert

public static final WeatherPropertySet Alert

Weather alert related properties. This set contains:

1. AlertTitle
2. AlertDescription

Astronomy

public static final WeatherPropertySet Astronomy

Astronomy related properties. This set contains:

1. SunriseTime
2. SunsetTime

Precipitation

public static final WeatherPropertySet Precipitation

Precipitation related properties. This set contains:

1. PrecipMillimeterPerHour
2. PrecipForm
3. PrecipProbabilityPercent
4. PrecipMaxMillimeterPerHour
5. PrecipMaxTime
6. PrecipAccumCentimeter
7. CloudCoverPercent<
8. HumidityPercent

Temperature

public static final WeatherPropertySet Temperature

Temperature related properties. This set contains:

1. TempCelsius
2. TempMinCelsius
3. TempMinTime
4. TempMaxCelsius
5. TempMaxTime
6. DewPointCelsius

Wind

public static final WeatherPropertySet Wind

Wind related properties. This set contains:

1. WindMeterPerSecond
2. WindDirectionDegree

CONDITIONS

public static final Feature CONDITIONS

A feature that provides reports for weather conditions at a given time.

CONDITIONS_MINUTE

public static final Feature CONDITIONS_MINUTE

A feature that provides minute-by-minute weather reports.

CONDITIONS_HOUR

public static final Feature CONDITIONS_HOUR

A feature that provides hour-by-hour weather reports.

CONDITIONS_DAY

public static final Feature CONDITIONS_DAY

A feature that provides day-by-day weather reports.

ALERT

public static final Feature ALERT

A feature that provides weather alerts.

Constructor Detail

WeatherService

protected WeatherService()

Constructs a weather service.

Method Detail

subList

public static <T extends WeatherReport> java.util.List<T> subList(java.util.List<T> list,
                                                                  Feature f)

Extracts the list of weather reports that belong to a feature.

Type Parameters:

T - the type of the weather reports

Parameters:

list - the list of the weather reports

f - the feature

Returns:

the list of weather reports that belong to the given feature

Throws:

java.lang.NullPointerException - if the given list of reports is null

subList

public static <T extends WeatherReport> java.util.List<T> subList(java.util.List<T> list,
                                                                  java.util.Date beginDate,
                                                                  java.util.Date endDate)

Extracts the list of weather reports between two dates.

Type Parameters:

T - the type of weather reports

Parameters:

list - the list of weather reports

beginDate - the begin date (inclusive); null if the begin date is the earliest time of the reports

endDate - the end date (inclusive); null if the end date is the latest time of the reports

Returns:

the list of weather reports between the begin date (inclusive) and the end date (inclusive)

Throws:

java.lang.NullPointerException - if the given list is null

listFeatures

public static java.util.List<Feature> listFeatures(java.util.List<? extends WeatherReport> list)

Lists all features referenced by a list of weather reports. Each feature is listed only once and the order of the features is the same as the order of their appearance in the list.

Parameters:

list - the list of weather reports

Returns:

the list of features referenced by the given reports

Throws:

java.lang.NullPointerException - if the given list is null

query

public java.util.List<R> query(L location)

Queries the data source for a location about the weather information from the basic features this service provides.

Parameters:

location - the location

Returns:

the weather information from the basic features this service provides

Throws:

java.lang.NullPointerException - if the given location is null

query

public java.util.List<R> query(L location,
                               Queryable q,
                               Queryable... others)

Queries the data source for a location about the weather information that includes a list of queryables. A queryable is usually a weather property or a weather property set.

Parameters:

location - the location

q - the first queryable

others - other queryables

Returns:

the weather information that includes a list of queyrables

Throws:

java.lang.NullPointerException - if the given location is null

java.lang.IllegalArgumentException - if any given queryable is null

query

public java.util.List<R> query(L location,
                               Queryable q,
                               Feature f,
                               Feature... ff)

Queries the data source for a location about the weather information that includes the given queryable and list of features.

Parameters:

location - the location

q - a queryable, which is usually a weather property or a weather property set

f - the first feature

ff - other features

Returns:

the weather information that includes the given queryable and list of features

Throws:

java.lang.NullPointerException - if the given location is null

java.lang.IllegalArgumentException - if any of the given features is null

query

public java.util.List<R> query(L location,
                               Feature f,
                               Feature... ff)

Queries the data source for a location about the weather information from a list of features.

Parameters:

location - the location

f - the first feature

ff - the other features

Returns:

the weather information for a location from a list of features

Throws:

java.lang.NullPointerException - if the given location is null

java.lang.IllegalArgumentException - if any given feature is null

query

public java.util.List<R> query(L location,
                               Q hint)

Queries the data source about the weather in a location. This method returns this.query(location, null, hint).

Parameters:

location - the location

hint - the query hint; null if the data from the basic features should be returned

Returns:

the weather in the given location

Throws:

java.lang.NullPointerException - if the given location is null

print

public void print(java.io.PrintStream out,
                  java.util.List<R> reports)

Prints a list of weather reports to a print stream. A weather property and its data are printed only when the data is not null. The data are formatted according to the system default locale.

Parameters:

out - the print stream

reports - the list of weather reports

Throws:

java.lang.NullPointerException - if the given print stream or list of weather reports is null

getApplicableFeatures

protected java.util.Set<Feature> getApplicableFeatures(Q hint)

Derives the set of relevant features from a query hint. The algorithm is described in QueryHint. When no features can be inferred, the set of features from getBasicFeatures is returned, except the features that are explicitly excluded.

Parameters:

hint - the query hint; null if unavailable

Returns:

the set of relevant features based on the query hint

See Also:

QueryHint, getBasicFeatures()

query

public abstract java.util.List<R> query(L location,
                                        java.util.Date beginDate,
                                        Q hint)

Queries the data source about the weather in a location from a specific date onward.

Parameters:

location - the location

beginDate - the first date of the reporting period; null if the report should start from the current date. This argument is mostly used to retrieve historical data. Since weather forecast cannot extend indefinitely, giving a future date far from now is impractical. To get forecast data for a future date, pass null for this argument, include appropriate features such as CONDITIONS_DAY, and use subList(List, Date, Date) to filter the reports. A service provider may ignore this argument if it cannot provide historical data.

hint - the query hint; null if the data from the basic features should be returned

Returns:

the weather in the given location in the given period of time

Throws:

java.lang.NullPointerException - if the given location is null

newQueryHint

public abstract Q newQueryHint()

Creates a new query hint.

Returns:

the new query hint

getSupportedFeatures

public abstract java.util.Set<Feature> getSupportedFeatures()

Gets all features this service supports.

Returns:

all features this service supports

getBasicFeatures

public abstract java.util.Set<Feature> getBasicFeatures()

Returns the set of features for which the weather reports are created when the query hint does not exist or does not specify properties of interest or features to include.

Returns:

the basic features when the query hint does not specify any

getApplicableProperties

public abstract WeatherPropertySet getApplicableProperties(Feature f)

Gets the set of properties applicable to a feature.

Parameters:

f - the feature

Returns:

the set of properties applicable to a feature

Throws:

UnsupportedFeatureException - if the given feature is not supported

See Also:

Feature.getProperties(WeatherService)