com.oopitis.weather
Class WeatherProperty<T>

java.lang.Object
  com.oopitis.weather.WeatherProperty<T>

Type Parameters:

T - the type of the data this property represents

All Implemented Interfaces:

Queryable

public abstract class WeatherProperty<T>
extends java.lang.Object
implements Queryable

An object of this class represents a piece of weather information. Every weather property is typed. The type of the data a property represents is determined when the property is defined. Once a property is defined, the data type cannot change. The strong typing is enforced by the compiler via the use of Java generics. At runtime, the type can be discovered by calling getValueClass.

A weather property is able to format the data it represents for a locale. The formatted data is fundamentally a string representation of the data object. In case of numeric types, formatting data often involves conversion to a different unit of measure. The string representation may look significantly different from the original value. For example,

 Float t = report.get(WeatherService.TempCelsius);
 
 // Format the temperature for locale US.
 System.out.println(WeatherService.TempCelsius.format(t, Locale.US));
 
 // Format the temperature according to the property definition.
 System.out.println(WeatherService.TempCelsius.format(t, null));
 
 // Format the temperature for the system default locale (which is also US
 // in this example).
 System.out.println(WeatherService.TempCelsius.format(t));
 
 Float w = report.get(WeatherService.WindDirectionDegree); 
 System.out.println(WeatherService.WindDirectionDegree.format(w));

Here is the output:

 60.06 °F
 15.59 °C
 60.06 °F
 Southwest (227°)

Notice how null represents the default string representation.

A weather property itself also has a locale-sensitive string representation which is the display name of the property. In addition to the display name, a WeatherProperty object, which is often assigned to a final static field, has a constant name. The constant name is the fully qualified name of the Java identifier the object is assigned to. For example, the display name of com.oopitis.weather.WeatherService.SunsetTime for Locale.US is "Sunset Time" while the constant name is "com.oopitis.weather.WeatherService.SunsetTime". The constant names are useful when a list of weather properties is given without documentation.

Implementation note: While technically it is possible to define a property without using generics, or to define a property as WeatherProperty<Object>, such practice must be avoided. The data type must be as specific as possible. As a rule, the data types are primitive types or simple data structures. When defining new properties, properties of the same data type should reuse the same class. It is neither necessary nor optimal to create a distinct class for every new property.

Objects of this class are meant to be constants. They are recognized by their object references as opposed to internal keys or numeric IDs. Having multiple semantically identical weather properties is confusing and must be avoided. If applicable, it is customary to include the unit of measure in the constant name of a property. For example, VisibilityKilometer is used instead of Visibility in WeatherService.

Field Summary

protected static java.util.Locale	LOCALE_RAW A locale with language code "" and country code "".
protected java.lang.String	resourceBundleName The base resource bundle name from the constructor.
protected java.lang.String	resourceKey The resource key from the constructor.

Constructor Summary

protected	WeatherProperty(java.lang.String constantName) Constructs a weather property with a constant name.
protected	WeatherProperty(java.lang.String constantName, java.lang.String resourceBundleName, java.lang.String resourceKey) Constructs a weather property with a locale-sensitive name from resource bundles.

Method Summary

java.lang.String	format(T value) Formats the data this property represents for the default locale.
abstract java.lang.String	format(T value, java.util.Locale locale) Formats the data this property represents for a given locale.
java.lang.String	getConstantName() Gets the fully qualified Java name of this constant.
WeatherProperty[]	getQueryableProperties() Returns an array with this property as the only element.
abstract java.lang.Class<T>	getValueClass() Gets the Class object of the data this property represents.
java.lang.String	toString() Returns the string representation for the default locale.
java.lang.String	toString(java.util.Locale locale) Returns a locale-specific string representation.

Methods inherited from class java.lang.Object

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

Field Detail

LOCALE_RAW

protected static final java.util.Locale LOCALE_RAW

A locale with language code "" and country code "". Used with "no fallback" resource bundle control, subclasses may use this locale to access the resources in the base bundle.

resourceBundleName

protected final java.lang.String resourceBundleName

The base resource bundle name from the constructor.

resourceKey

protected final java.lang.String resourceKey

The resource key from the constructor.

Constructor Detail

WeatherProperty

protected WeatherProperty(java.lang.String constantName)

Constructs a weather property with a constant name.

Parameters:

constantName - the constant name

Throws:

java.lang.NullPointerException - if the given constant name is null

WeatherProperty

protected WeatherProperty(java.lang.String constantName,
                          java.lang.String resourceBundleName,
                          java.lang.String resourceKey)

Constructs a weather property with a locale-sensitive name from resource bundles.

Parameters:

constantName - the constant name

resourceBundleName - the base resource bundle name

resourceKey - the resource key

Throws:

java.lang.NullPointerException - if any of the arguments is null

Method Detail

getValueClass

public abstract java.lang.Class<T> getValueClass()

Gets the Class object of the data this property represents.

Returns:

the Class object of the data this property represents

format

public abstract java.lang.String format(T value,
                                        java.util.Locale locale)

Formats the data this property represents for a given locale.

Parameters:

value - the data to be formatted

locale - the locale for which the data is to be formatted; null if the data is to be formatted according to the property definition

Returns:

the formatted data for the given locale

format

public java.lang.String format(T value)

Formats the data this property represents for the default locale. This is the same as this.format(value, Locale.getDefault()).

Parameters:

value - the data to be formatted

Returns:

the formatted data for the default locale

See Also:

format(Object,Locale), Locale.getDefault()

getQueryableProperties

public final WeatherProperty[] getQueryableProperties()

Returns an array with this property as the only element.

Specified by:

getQueryableProperties in interface Queryable

Returns:

an array with this property as the only element

getConstantName

public final java.lang.String getConstantName()

Gets the fully qualified Java name of this constant.

Returns:

the fully qualified Java name of this constant

toString

public java.lang.String toString(java.util.Locale locale)

Returns a locale-specific string representation.

Implementation note: Subclasses that override this method without overriding toString() must never invoke toString() directly or indirectly in the implementation. Doing so will result in an infinite loop and eventually a StackOverflowError.

Parameters:

locale - the locale for which the string is prepared; if null, the system default locale is used.

Returns:

the locale-specific string representation or the constant name if this object does not have a locale-sensitive name.

Throws:

java.util.MissingResourceException - if a resource key and bundle name are specified but the key is not found in any variations or the base bundle

See Also:

toString()

toString

public java.lang.String toString()

Returns the string representation for the default locale. This method returns this.toString(Locale.getDefault()) if the value is not null; otherwise the constant name is returned.

Overrides:

toString in class java.lang.Object

Returns:

the string representation of this constant for the default locale, or the constant name

See Also:

toString(Locale), Locale.getDefault()