Configuring the WeatherEase Demo Program

Last revised: 09Nov01 GLG

Table of Contents

• Notice of Disclaimer
• Introduction
• Principal Properties and Command-Line Parameters
• Stations File Format
• FlexibleListView List-item Properties
• FlexibleListView List-item Symbols
• FlexibleListView Descriptive-text Properties
• FlexibleListView Descriptive-text Symbols

Notice of Disclaimer

By default, this software uses and presents data supplied by a NOAA web-server.

NOAA disclaims any use of the supplied data for aviation or other operational purposes -- "Data distribution via the Internet is not considered an operational delivery mechanism by the NWS due to our inability to insure access to this service, therefore, the information available here shall not be used for flight planning or other operational purposes."

Furthermore, the author of the WeatherEase Toolkit software reminds you that this software is distributed under the "Artistic License", one condition of which is:

THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Introduction

The Weather Watcher demo program is very flexible and configurable. Nonetheless, it is still only a demo program. It is not intended as full-featured consumer software for presenting current weather conditions. So if you think of a feature you'd like to see, you are encouraged to implement it yourself, rather than asking me to add the feature. My purpose behind creating the WeatherEase Toolkit was to make it easier for YOU to write weather software.

Numbers are typically shown rounded to the nearest whole number for whatever the reading and its units are. There are exceptions to this rule, however:

• When the pressure units are inches of mercury (in-Hg), the reading is displayed rounded to the nearest two decimal places, e.g. 29.80 in-Hg.
• In the descriptive text, precipitation is rounded to 2 decimal places for inches (in) and centimeters (cm), or to 1 decimal place for millimeters (mm).
• In the descriptive text, when the temperature and dew-point are available as tenths of degrees, they are shown rounded to one decimal place. Otherwise they are shown rounded to whole degrees.

All the properties described below are optional. If not defined, a default is used. There are no default stations, so if the stations-file is missing, empty, or malformed, the list will have no items in it.

Principal Properties and Command-Line Parameters

The name of the principal properties file is "All-watched-settings", with or without a ".txt" suffix. This file is first looked for in the "user.dir" directory (i.e. in the app's own directory), then in the "user.home" directory. In each location, it is first looked for without a suffix, then with a ".txt" suffix. When the first matching file is found, that is the file whose contents are read as the principal properties. If no matching file is found anywhere, then the principal properties are just the system properties.

After any principal properties have been loaded, the command-line args are parsed. All the args are treated as additional properties-files, which are loaded in turn. Any arg that starts with "-" is quietly ignored, since the demo uses no option-flags. Any filename that does not exist or is unreadable is skipped over without ill effect. Any file whose contents are not really structured as properties-text will cause parsing exceptions which are ultimately ignored.

Since command-line properties-files are opened in turn, files later in the list override properties defined earlier. That is, the last property-file loaded that defines a particular property will prevail. There is no warning of this, and it is not considered an error. It's a feature.

You can also define command-line properties in lieu of using properties-files. These are simply added to the system properties before main() is called, so are part of the default properties context.

All the properties defined by loading files or defined as system properties will ultimately determine how the application looks and acts:

• app.weather.watch.settings = filename
  -- filename of an additional set of properties, looked for in "user.dir" and "user.home";
  no default.
  This property is most useful when you're using only the principal properties-file and not relying on command-line args. It's still respected in command-line properties, though it's less useful in that context.
• app.weather.watch.stations = filename
  -- filename of stations to produce reports for;
  default is "All-watched-stations.txt".
• app.weather.watch.template = URL-template
  -- The URL template from which to retrieve report data;
  default is "http://weather.noaa.gov/pub/data/observations/metar/stations/$$$$.TXT".
• app.weather.watch.pattern = pattern
  -- The pattern in the URL template where a Station's ICAO name is substituted;
  default is "$$$$".
• app.weather.watch.title = string
  -- Title of the WatchFrame;
  default is "Simple Weather Watcher".
• app.weather.watch.color.bg = color
  -- Background color of frame and sub-components in #xxxxxx format;
  default is "#DEFACE" which is a light green.
• app.weather.watch.color.fg = color
  -- Foreground color of frame and sub-components in #xxxxxx format;
  default is "#000000" which is black.
• app.weather.watch.list.font = fontname-style-size
  -- Font to use in List (only monospaced fonts advised);
  default is Monospaced-plain-12.
• app.weather.watch.list.lines = integer
  -- Initial height of List, an integer count of list items;
  default is 15.
• app.weather.watch.text.font = fontname-style-size
  -- Font to use in TextArea;
  default is SansSerif-plain-12.
• app.weather.watch.text.font = integer
  -- Height in lines of TextArea;
  default is 10.
• app.weather.watch.secs.first = integer
  -- Integer number of seconds to delay before first retrieval of first URL;
  default is 10 (seconds).
• app.weather.watch.secs.between = integer
  -- Integer number of seconds to delay between subsequent retrievals of report URLs;
  default is 180 (seconds, which is 3 minutes).
• app.weather.watch.stations.class = classname
  -- fully qualified class name of StationBuilder subclass that builds Stations from the data in the "app.weather.watch.stations" file;
  default class is glguerin.weather.parse.nws.NWSStationBuilder.
• app.weather.watch.builder.class = classname
  -- fully qualified class name of ReportBuilder subclass that builds reports from the data retrieved from the URL;
  default is glguerin.weather.parse.nws.NWSMetarInterpreter.
• app.weather.watch.listview.class = classname
  -- fully qualified class name of a WatchListView subclass to use;
  default is app.weather.watch.FixedListView.
  If you designate app.weather.watch.FlexibleListView as the classname, then you have myriad additional configurable properties and symbols (described below) that control the appearance of list-items and descriptive-text.

Stations File Format

The list of stations to watch is given by the contents of a text file. The filename of the stations file is given by the app.weather.watch.stations property in the main properties file. By default, that filename is "All-watched-stations.txt", which is a relative pathname signifying that the file is located in the app's own default directory.

The contents of the stations file must be in a format acceptable to the StationBuilder class whose fully qualified class-name is given by the app.weather.watch.stations.class property. By default, that's the fully qualified name of the NWSStationBuilder class.

The NWSStationBuilder reads stations one line at a time. Empy lines, blank lines, and lines consisting entirly of white-space are ignored. Lines starting with "#" are treated as comments and are also ignored. All other lines consist of a semicolon-separated list of station data. That format matches the format in which NOAA/NWS distributes a zipped text file containing a comprehensive list of stations. Not all stations in that list are actually available from the NOAA web-server. The simplest way to determine whether a given station is available from the NOAA web-server or not is to copy and paste its line of semicolon-separated fields into "All-watched-stations.txt" and see whether the demo program can retrieve data for it or not. If you see a FileNotFoundException in the list rather than weather readings, then you know that no data is available from NOAA for that station.

The format of stations recognized by NWSStationBuilder is for the NOAA-supplied station-list keyed by location identifier (ICAO location ID). The field offsets in an array are as follows:

(0) ICAO Location Indicator -- 4 alphanumeric characters.

(1) Block Number -- 2 digits representing the WMO-assigned block. Not all stations in the file have an assigned block number. The value "--" is used for stations without an assigned number.

(2) Station Number -- 3 digits representing the WMO-assigned station. Not all stations in the file have an assigned station number. The value "---" is used for stations without an assigned number.

(3) Place Name -- Common name of station location.

(4) State -- 2 character abbreviation (included for stations located in the United States only).

(5) Country Name -- Country name in ISO short English form.

(6) WMO Region -- digits 1 through 6 representing the corresponding WMO region, 7 stands for the WMO Antarctic region.

(7) Station Latitude -- DD-MM-SSH where DD is degrees, MM is minutes, SS is seconds and H is N for northern hemisphere or S for southern hemisphere. The seconds value is omitted for those stations where the seconds value is unknown.

(8) Station Longitude -- DDD-MM-SSH where DDD is degrees, MM is minutes, SS is seconds and H is E for eastern hemisphere or W for western hemisphere. The seconds value is omitted for those stations where the seconds value is unknown.

(9) Upper Air Latitude -- DD-MM-SSH where DD is degrees, MM is minutes, SS is seconds and H is N for northern hemisphere or S for southern hemisphere. The seconds value is omitted for those stations where the seconds value is unknown.

(10) Upper Air Longitude -- DDD-MM-SSH where DDD is degrees, MM is minutes, SS is seconds and H is E for eastern hemisphere or W for western hemisphere. The seconds value is omitted for those stations where the seconds value is unknown.

(11) Station Elevation (Ha) -- The station elevation in meters. Value is omitted if unknown.

(12) Upper Air Elevation (Hp) -- The upper air elevation in meters. Value is omitted if unknown.

(13) RBSN indicator -- P if station is defined by the WMO as belonging to the Regional Basic Synoptic Network, omitted otherwise.

FlexibleListView List-item Properties

These properties control how each list-item is formatted, and the units in which readings are displayed.

• app.weather.watch.listview.template = template-string
  -- the list-item formatting template.
  The template consists of literal characters, and symbols prefaced with a '$'.
• app.weather.watch.listview.time = template
  -- a SimpleDateFormat template for the $T and $U symbols.
• app.weather.watch.listview.wind.units = units
  -- units of wind speed for the $W and $G reading. (kph, mph, kt, m/s, km/hr, mi/hr)
• app.weather.watch.listview.wind.pad = width
  -- field-width for the $W and $G readings.
• app.weather.watch.listview.wind.arc = degrees
  -- degrees of variability threshold for the $W and $G reading.
• app.weather.watch.listview.vis.units = units
  -- units of distance for the $V reading. (km, mi, m, ft, naut mi)
• app.weather.watch.listview.vis.pad = width
  -- field-width for the $V reading.
• app.weather.watch.listview.pres.units = units
  -- units of pressure for the $P reading. (mb, hPa, in-Hg, mm-Hg)
• app.weather.watch.listview.pres.pad = width
  -- field-width for the $P reading.
• app.weather.watch.listview.sky = list
  -- a comma-separated list for the $K symbol.

The comma-separated list in the "app.weather.watch.listview.sky" property is an ordered list of 6 text items used to represent the different levels of sky cover (cloudiness). It must consist of at least 6 items or it will not be used. The first item is for clear skies, the next for 1/4 coverage, and so on through 4/4 coverage (overcast). The last (6th) item is for obscured skies (i.e. Sky.INDEFINITE). Excess white-space is always trimmed from the text before determining the padding width.

FlexibleListView List-item Symbols

The list-item template contains literal characters, and symbols prefaced with '$'. Every literal character is placed into the formatted list item exactly as and where given. Use literal characters for inserting spaces or literal text between symbols, and those literals appear in the formatted list item.

Every symbol is replaced in the formatted list item with a specific reading or measurement from the weather report. Most symbols produce a number and the units. $C, $F, and $H only produce numbers. $D, $K, $X and some others produce text and no units.

• $C -- temperature in rounded whole degrees Celsius, 3-digit blank-padded right-aligned
• $D -- wind direction around an 8-point compass circle, 2-chars blank-padded right-aligned
• $E -- temperature-extremes indicator: '*' if any extremes, blank if none
• $F -- temperature in rounded whole degrees Fahrenheit, 3-digit blank-padded right-aligned
• $G -- wind speed with gusts, in designated units and field-width, right-aligned
• $H -- relative humidity in whole percent, 3-digit blank-padded right-aligned
• $K -- sky-cover text from "app.weather.watch.listview.sky" list, blank-padded left-aligned
• $M -- station's WMO number, if any, or "-----" if none
• $P -- altimeter pressure in designated units and field-width, right-aligned
• $R -- precipitation indicator: '*' if any precip, blank if none
• $S -- station's ICAO name
• $T -- time/date of report in designated SimpleDateFormat form and local time-zone
• $U -- time/date of report in designated SimpleDateFormat form and GMT/UTC time-zone
• $V -- visibility distance in designated units and field-width, right-aligned
• $W -- prevailing wind speed only, in designated units and field-width, right-aligned
• $X -- present weather phenomena, if any, in a comma-separated list

FlexibleListView Descriptive-text Properties

When you designate FlexibleListView as the listview class, you also gain control over the contents of the descriptive-text area. You will always get a description of the station itself, including its name, country, elevation, and latitude & longitude. You can also specify additional readings or measurements to be described from the current report. In general, the descriptive-text version of some reported reading will either expand on the data presented in the list-item, or present it in the highest available precision.

In addition to reported readings that can appear in list-items, you have additional readings that can only appear in descriptive text. For example, recent weather phenomena, peak wind, pressure-trend, cumulative precipitation, temperature extremes, and the string form of the actual report data.

• app.weather.watch.listview.alt.units = units
  -- units of altitude for the descriptive text. (m, ft)
• app.weather.watch.listview.precip.units = units
  -- units of precipitation for the descriptive text. (mm, in, cm)

• app.weather.watch.listview.describe = template-string
  -- the descriptive-text formatting template. The template consists entirely of symbolic characters. Characters not recognized as symbols are ignored.
• app.weather.watch.listview.describe.sky = list
  -- a comma-separated list of words or phrases describing sky-coverage;
  default is US English phrases and words.
• app.weather.watch.listview.describe.time = template
  -- a SimpleDateFormat template for formatting the T and U symbols;
  default is "yyyy/MM/dd HH:mm zzz".
• app.weather.watch.listview.describe.num0 = template
  -- a DecimalFormat pattern for describing whole numbers;
  default is "0".
• app.weather.watch.listview.describe.num1 = template
  -- a DecimalFormat pattern for describing one-decimal-place numbers;
  default is "0.0".
• app.weather.watch.listview.describe.num2 = template
  -- a DecimalFormat pattern for describing two-decimal-place numbers;
  default is "0.00".

FlexibleListView Descriptive-text Symbols

The descriptive-text formatting template is a string with symbols representing different readings from a weather report. Unlike the List-item template, every character is a symbol representing a reading, and there are no literal characters. You include or exclude specific characters to include or exclude the corresponding readings. The order of the characters in the template determines the order of the descriptive text. All characters that don't have a symbolic meaning are ignored.

The recognized descriptive-text symbols are:

• C -- temperature, dewpoint, and relative humidity, in whole or tenths of degrees Celsius; the decision of whole or tenths depends on the reading itself
• E -- temperature extremes, if any, in tenths of degrees Fahrenheit and Celsius
• F -- temperature, dewpoint, and relative humidity, in whole or tenths of degrees Fahrenheit; the decision of whole or tenths depends on the reading itself
• G -- details about wind-gusts and peak-wind readings, if any.
• J -- overall sky coverage, if any, using text given by "app.weather.watch.listview.describe.sky"
• K -- notable sky conditions, if any: variable ceiling, notable cloud layers and altitudes, etc. A notable cloud layer is any layer constituting a ceiling, or any layer with a specific cloud type.
• L -- complete sky conditions, if known: ceiling, all cloud layers and altitudes, etc.
• P -- altimeter pressure, if any
• Q -- pressure-trend details, if any
• R -- all cumulative precipitation readings, if any
• S -- sea-level pressure reading, if any
• T -- time and date of the report, in local time
• U -- time and date of the report, in GMT/UTC
• V -- visibility distance, if any
• W -- prevailing wind details, if any
• X -- present weather phenomena, including intensity, if any
• Y -- recent weather phenomena, including intensity, if any
• Z -- the raw report data (typically METAR text)
• - (hyphen) -- a blank line if any descriptive text has actually appeared yet, or nothing if not.

The J descriptive text uses the list of 6 comma-separated text items given by the "app.weather.watch.listview.describe.sky" property.

The T and U descriptive texts use the SimpleDateFormat template designated by the "app.weather.watch.listview.describe.time" property.

To Greg's Home Page
To Greg's Software Page