The WeatherChart Application
This document describes the WeatherChart application and is divided into the following sections:

Introduction

The WeatherChart application illustrates the following tasks for developing Web applications with the eSuite DevPack:

The WeatherChart application demonstrates how you can use Lotus eSuite to graphically display real-time data from the Web. This type of application is useful for displaying business-related information, such as

WeatherChart displays a series of graphs that show weather information for US cities. The user clicks a button to select a city, and WeatherChart displays three charts that plot hourly temperature, humidity, and barometric pressure readings for the selected city. The readings cover the most recent 24-hour period. To view the weather information for another city, the user clicks another button.

WeatherChart polls a copy of WSI Corporation's Intellicast weather information on the Lotus Web site every hour. It reads the current-condition files for the featured cities and updates a set of dataset files for each city. It then plots the data from these files in three charts.

When the user selects a new city, WeatherChart dynamically changes the data source for the three charts, rather than reloading the HTML page. The quick response to user input is an advantage that eSuite applets, and Java applets in general, have over other Web implementations.

Application Pieces

WeatherChart uses the following components:

InfoBus and ScriptHelper applets

The InfoBus provides data communication between Java applets. In the WeatherChart application, the InfoBus is the vehicle for posting and retrieving weather data.

The ScriptHelper applet is the mechanism that lets you publish data items to and retrieve data items from the InfoBus through scripts. The WeatherChart HTML file contains JavaScript code that uses the ScriptHelper applet to publish data to the InfoBus and change the chart display to show weather data for the city selected by the user.

FileReader applet

The FileReader applet retrieves dataset files from the Web server, parses them, and publishes the parsed data to the InfoBus. The dataset files are constructed by the ReadWeather program. WeatherChart creates three FileReader objects, one for each type of data retrieved: temperature, humidity, and barometric pressure.

Chart Applet

The Chart class defines a chart object with which you can plot data from a data source, for example, a spreadsheet, text file, or database. WeatherChart creates three Chart objects to plot temperature, humidity, and barometric pressure data for a specified city.

The following diagram shows how the ScriptHelper, FileReader, and Chart applets interact in the WeatherChart application:

WeatherChart diagram

Note that WeatherChart uses three separate instances of both FileReader and Chart, one pair of each for temperature, humidity, and pressure, respectively. For simplicity, the diagram shows only one of these pairs.

The diagram illustrates the following process:

  1. A program called ReadWeather polls the Lotus Web site every hour and builds data sets based on the information read from the current-condition files for each city.

  2. FileReader retrieves the dataset files from the Web server, parses them, and places the parsed data on the InfoBus.

  3. Depending on the city selected, the Chart objects retrieve the appropriate data from the InfoBus and plot it.

Dataset files

A Chart object plots data that has been organized as a data set. A data set is a row or rows of data representing numerical sequences. In a data set with multiple rows, all the rows relate to each other by a common variable. That is, they share a common x-axis.

You can construct data sets to include title, legend, and label information as well as the data to be charted (called a series). In this case, the Chart object parses the data set to differentiate the data from the labels and titles.

WeatherChart uses data sets stored on the Web server as text files. For each city, there are three files with the extensions .TEM, .HUM and .PRE, for temperature, humidity, and pressure data sets, respectively. An example of a .TEM file is shown below:

"Temperature" 
" " p8 p9 p10 p11 a12 a1 a2 a3 a4
"Temperature" 74 72 72 70 69 67 68 66 67

The first line of the above file is parsed as the title of the chart, the second as the x-axis labels, and the third as the data series to be plotted. The x-axis labels represent the hours (AM or PM) when the temperature data was recorded.

ReadWeather program

ReadWeather is a Java program that builds the dataset files.

To execute ReadWeather, follow either of these steps:

ReadWeather operates as follows:

  1. ReadWeather reads each line in the specified configuration file.

    The configuration file specifies where weather information is read from, and which dataset files to update. It is a text file, with lines in the form:

    city name|dataset base file name|URL

    Where
    city name is the name of the city that the files refer to.
    data set base filename specifies the path and base file name for that city's dataset files.
    URL is the URL that is read to obtain the weather information.
    | is the pipe character used to separate data items on each line.

    The configuration file that accompanies WeatherChart contains the following lines:

    New York   |newyork    |http://nextgenserver.lotus.com/samples/weatherchart/curcond.lga
    Los Angeles|losangeles |http://nextgenserver.lotus.com/samples/weatherchart/curcond.lax
    Detroit    |detroit    |http://nextgenserver.lotus.com/samples/weatherchart/curcond.dtw
    Chicago    |chicago    |http://nextgenserver.lotus.com/samples/weatherchart/curcond.ord
    Chattanooga|chattanooga|http://nextgenserver.lotus.com/samples/weatherchart/curcond.mem
    Baton Rouge|batonrouge |http://nextgenserver.lotus.com/samples/weatherchart/curcond.btr
    The dataset file names in the example above do not specify a path. The path defaults to the location of ReadWeather.

  2. ReadWeather accesses the URLs specified in the configuration file to retrieve weather information for each city. This information is contained in the current-condition files. The Intellicast system refreshes the contents of these files once each hour, and a program running on the Lotus Web server reads these files and makes a local copy for the ReadWeather application.

    These current-condition files each contain two lines of text. The first line provides date and time information; the second line lists values for weather conditions, separated by semi-colon (;) characters. The values are provided in the following order: temperature, humidity, wind, visibility, conditions, pressure. Following is a sample current-condition file:

          Observations for  2pm(18z) 29-aug-97
    	89;56;e3;7;m cldy;29.95

  3. After reading the needed values from the current-condition files, ReadWeather updates the dataset files for each city. For example, if the base file name specified in the configuration file is c:\rwdata\boston, the three files that get updated are: c:\rwdata\boston.tem, c:\rwdata\boston.hum, and c:\rwdata\boston.pre.

Coding the WeatherChart Application

This section discusses the tasks required to implement the WeatherChart application.

Embedding and configuring applets on a Web page

WeatherChart uses ScriptHelper, FileReader, and Chart objects. They are included in the HTML page using the APPLET tag. Values for CODE, CODEBASE, NAME, WIDTH, and HEIGHT are specified in the tag. The APPLET tag below embeds and configures the Chart object called TemperatureSet.

<APPLET
CODEBASE="../.."
CODE="lotus.chart.Chart"
ARCHIVE="jars/devpack_chart_app.jar"
Width=566 HEIGHT=219
NAME="TemperatureSet">

CODEBASE specifies the location of the Java class files for the applet. This includes the applet class file and any class files upon which the applet depends. In general, you should install a single copy of the eSuite DevPack class files in a set location on your server, and then configure each applet instance to use that location as the CODEBASE. In the example above, the path is relative to the HTML file.

CODE specifies the name of the Java class representing the applet, for example Chart. When an applet is part of a package, as the eSuite applets are, the class name you specify must be the fully qualified package name. In the example above, this fully justified name is lotus.chart.Chart.

ARCHIVE specifies the path to the class definitions for Chart, ScriptHelper, and FielReader. These class definitions are bundled together and compressed. Netscape needs this path to find and decompress the files.

WIDTH and HEIGHT specify the size of the applet's bounding rectangle, in pixels. The ScriptHelper and FileReader applets have no user interface, so they are made invisible on the Web page by using a WIDTH and HEIGHT setting of 1 in the APPLET tag. In the example above, the Chart dimensions are 566 x 219 pixels. The displayed chart automatically scales to fit this area.

NAME specifies the name of the applet on the page. This value is used to identify applet objects in scripts, among other things. The value for NAME must be unique for all applets on a single page. In the example above, the Chart object name is TemperatureSet. Two other charts, named HumiditySet and BaroSet are created in the application.

Using PARAM tags to set applet properties

Applets usually need some configuration information that is specific to their intended task. Data of this type is supplied to the applet using applet PARAM tags. You specify this data by including one or more tags between the <APPLET> and </APPLET> tags. The example below sets configuration parameters that define the TemperatureSet chart's appearance. Among the chart properties it specifies are the following: the chart is a two-dimensional bar chart with a red bar; no legend is displayed and no title is displayed for the chart or x-axis; and the major increment of the y-axis scale is 20 units. The CABINETS PARAM tag specifies the paths to the class definitions for Chart, ScriptHelper, and FielReader. Internet Explorer needs these paths to find and decompress the class files.
<APPLET
.
.
.>
<PARAM NAME="backgroundImageName" VALUE="temperature_bg.gif">
<PARAM NAME="Rendering" VALUE="2D">
<PARAM NAME=CABINETS VALUE="cabs/devpack_scripthelper_app.cab, cabs/devpack_chart_app.cab, cabs/devpack_filereader_app.cab" >
<PARAM NAME="SeriesBackgroundColors" VALUE="red">
<PARAM NAME="SeriesMixedType" VALUE="bar">
<PARAM NAME="ShowLegend" VALUE="false">
<PARAM NAME="ShowTitle" VALUE="false">
<PARAM NAME="ShowXAxisTitle" VALUE="false">
<PARAM NAME="ShowYAxisMinorTicks" VALUE="false">
<PARAM NAME="XAxisLabelFontColor" VALUE="white">
<PARAM NAME="YAxisScaleMajor" VALUE="20">
<PARAM NAME="ShowXAxisLabels" VALUE="FALSE">
</APPLET>

Using the Infobus to pass information between eSuite applets

Setting up the communication

In the WeatherChart application, the FileReader objects publish weather data to the InfoBus, and the Chart objects read and plot that data. To set up communication between FileReader and Chart objects, WeatherChart uses two FileReader PARAM tags: fileDataItemName and outputName.

fileDataItemName specifies the name of an InfoBus data item whose value is the name of a dataset file to read. outputName specifies the name with which the parsed data is published. The output file name is the same as the Chart object name. This establishes a relationship between the two.

The diagram below shows the relationship among the ScriptHelper, FileReader and Chart objects. It uses the FileReader and Chart objects concerned with temperature data.

WeatherChart diagram
The code below implements the process illustrated in the diagram. A FileReader object named _tempSrc is created and configured. Notice that the output file is called TemperatureSet, which is the name given to the Chart object shown above.

<APPLET
CODE="lotus.filereader.FileReader"
ARCHIVE="jars/devpack_chart_app.jar"
CODEBASE="../.."
NAME="_tempSrc"
WIDTH=1 HEIGHT=1> <PARAM NAME=CABINETS VALUE="cabs/devpack_scripthelper_app.cab, cabs/devpack_chart_app.cab, cabs/devpack_filereader_app.cab" >
<PARAM NAME=fileDataItemName VALUE="TemFileItem" >
<PARAM NAME=outputName VALUE="TemperatureSet" >
</APPLET>

The FileReader object (_tempSrc) that is configured to read temperature data looks for the data item named "TemFileItem" on the InfoBus. When this item becomes available, _tempSrc gets the value of that item and reads the file identified by the value (newyork.tem) from the server.

Once the file is successfully read, the data is published using the name specified by outputName, in this case "TemperatureSet". This corresponds to the name of the Chart, which by default reads a data item with the same name as itself.

Passing information via the ScriptHelper

WeatherChart uses a ScriptHelper object to pass the weather data between the FileReader and the Chart objects. The code to create the ScriptHelper object is shown below.

<APPLET
CODE="lotus.scripthelper.ScriptHelper"
CODEBASE="../.."
ARCHIVE="jars/devpack_scripthelper_app.jar"
NAME="_ibBridge" WIDTH=1 HEIGHT=1>
</APPLET>

A function called doClick() is defined in the HTML file. This function, written in JavaScript, is executed when the user clicks a button to select a city. doClick() takes two arguments: (1) the base name for the dataset files to be published to the InfoBus and (2) the name of the selected city, which is displayed in the HTML page banner.

doClick() appends .TEM, .HUM, and .BAR extensions to the base file name to construct three file names. It makes three calls to a ScriptHelper method called publishStringToInfoBus().

publishStringToInfoBus() takes two arguments: a data item name, specified in the FileReader PARAM tag called fileDataItemName and a dataset file name. Because the output file name associated with the data item name is the same as a Chart object, the InfoBus knows to advise the Chart object of the data availability. The Chart object reads the data and plots it.

The following JavaScript code sample shows the definition of the doClick() function:


<SCRIPT LANGUAGE="JavaScript">
function doClick(s, n)
{
var filename;
if (s == null) return;
filename = s + ".TEM";
document._ibBridge.publishStringToInfoBus( "TemFileItem", filename );
filename = s + ".HUM";
document._ibBridge.publishStringToInfoBus( "HumFileItem", filename );
filename = s + ".BAR";
document._ibBridge.publishStringToInfoBus( "BaroFileItem", filename );
if (n == null) return;
// IE 4 and 3 handle object model differently
var vers = navigator.appVersion;
if (vers.substring(0,1) == "4") // IE 4.0
document._banner.setText( n );
else
document._theForm._banner.setText( n ); // IE 3

}
</SCRIPT>

Following is a sample call to doClick():

<A HREF="Javascript:doClick('newyork', 'New York');">

This HTML code is executed when the user clicks a button to select the city of New York. It does the following steps:

  1. Call doClick(), which sets up the file names newyork.TEM, newyork.HUM, and newyork.BAR.

  2. Pass each of these file names, along with the data item that contains the file name, to the ScriptHelper object. This is achieved by calling the method, publishStringToInfoBus().

Overview of the .java files

This section describes the following .java files that support the WeatherChart application:

ReadWeather.java

The ReadWeather program updates the dataset files that record weather information -- temperature, humidity, and barometric pressure -- for various cities. It is meant to run once an hour, which is scheduled by running the atstart.cmd file. ReadWeather keeps appending data to the file, so it's a good idea to trim the data every 24 hours to keep the file a manageable size. For example, you could open the files and delete the earliest hours in the file.

ReadWeather contains three static methods: parseArgs(), updateDataset(), and main(), which are described in the following paragraphs. It also depends on three Java classes to read the weather data from the Intellicast Web site. The base class is GetWData. Two other classes, GetWDataDirect and GetWDataProxy, extend the base class.

parseArgs() parses the ReadWeather command you issue from your JVM. It stores the name of the configuration file you specify and the proxy and time zone information, if you specified this optional information.

updateDataset() updates three dataset files for each city listed in the configuration file wchart.dat. For each dataset file, updateDataset() executes the following sequence of tasks:

  1. Delete the temporary (.tmp) dataset file if it exists.
  2. Create and open a new temporary file.
  3. Open the dataset file, for example, newyork.TEM.
  4. Read and copy the first line from the the dataset file to the .tmp file. The first line contains the caption, for example, "Temperature".
  5. Read and copy the second line from the dataset file to the .tmp file. The second line contains the column labels, for example, "a9", "a10", "a11", "a12", "p1", where "a" indicates AM and "p" PM.
  6. Read the new label (using the GetWData class) from the current-condition file and append it (including the AM or PM tag) to the second line in the .tmp file.
  7. Read and copy the third line from the dataset file to the .tmp file. The third line contains the weather data values, for example, "68", "70", "67".
  8. Read the new value from the current-condition file and append it to the third line of the .tmp file.
  9. Close the dataset and .tmp files.
  10. Rename the dataset file to filename.BAK.
  11. Rename the temporary file to filename.TEM or .HUM, or .PRE, depending on the dataset file being updated.
  12. Delete the .BAK file.
main() is the method that executes in response to the ReadWeather command. It calls the other two methods in the file. main() executes the following sequence of tasks:
  1. Call parseArgs() to parse the command line.

  2. Open the configuration file specified on the command line.

  3. Call updateDataset() for each line in the configuration file.

GetWData class

GetWData is a Java class that ReadWeather uses to read data from the current-condition files on the Intellicast Web site. It defines three methods: trimInt(), trimFloat(), and parseStream(), which are described in the following paragraphs.

parseStream() executes the following sequence of tasks:

  1. Parse the data in the current-condition file, specified by the URL portion of the line in the configuration file.

    The line in the configuration file may be:

    New York   |newyork    |http://nextgenserver.lotus.com/samples/weatherchart/curcond.lga

    The current-condition file on the weather site, curcond.lga, may look like this:
    Observations for  2pm(18z)  1-sep-97
    81;69;ne 6;5;m cldy, haze;30.16

  2. Skip the first line of the current-condition file.

  3. Read the second line, which contains the weather data. Skip over the middle three values--wind, visibility, and conditions. Keep the values within a specified range. For example, pressure values are kept within the range of 29.0 to 31.5. These are the y-axis values for the chart. Because a smaller range of values is applied to the y-axis, the hourly change in pressure is more apparent on the chart.

trimInt() trims the string passed to it so the string contains only an integer value. This method is used to trim the temperature value, if needed.

trimFloat() trims the string passed to it so the string contains only a floating point value. This method is used to trim the humidity and pressure values, if needed.

GetWDataDirect and GetWDataProxy extender classes

GetWDataDirect and GetWDataProxy extend GetWData. These class extensions connect to the URL specified in the configuration file. If the ReadWeather command includes a proxy server specification, GetWDataProxy is used to connect to the URL. Otherwise, GetWDataDirect is used.

Installing and running the WeatherChart application

Before installing the WeatherChart application, review the DevPack installation guide. You can open and view the WeatherChart Web page from its installation directory.

To install WeatherChart on a Web server:

  1. Set the system environment variables for the sample applications.

    See the instructions below.

  2. Reboot your computer to have these environment variables take effect.

  3. Make sure the NT Schedule service is installed and running. (Use the Services applet in the Control panel.)

    This service is needed to run the atstart.cmd file in the next step.

  4. Run the atstart.cmd command file.

    Atstart issues the necessary AT commands to run the ReadWeather program once each hour.

To set the system environment variables for the sample applications:

  1. Right click the My Computer icon on your desktop.
  2. Select Properties from the menu that is displayed.
  3. Click the Environment tab.
  4. Set the following system variables:
  5. DEMODRIVE - The install drive for eSuite DevPack and samples, for example, c:
  6. DEMOROOT - The install directory for eSuite DevPack. This is the directory referred to in the CODEBASE statements in the WeatherChart HTML page.
  7. DEMOLOC - The directory where the WeatherChart HTML page is installed.

Files that comprise the WeatherChart application

File type File name Description
ReadWeather source files GetWData.java
GetWDataDirect.java
GetWDataProxy.java
ReadWeather.java
Reads data from the current condition files.
Extends GetWData class.
Extends GetWData class.
Builds and updates the dataset files.
Text banner applet source file Banner.java Implements the banner for the HTML page
Compiled class files GetWData.class
GetWDataDirect.class
GetWDataProxy.class
ReadWeather.class
Banner.class
See source file descriptions above.
Command files ATSTART.CMD
doMakeDat.cmd
doReadInit.cmd
doReadW.cmd
See source file descriptions above.
WeatherChart HTML page files WeatherChart.html
newyork.gif
detroit.gif
chicago.gif
batonrouge.gif
losangeles.gif
chattanooga.gif
The application page.
The buttons used to select a city.
Sample dataset files newyork.BAR/.HUM/.TEM
detroit.BAR/.HUM/.TEM
chicago.BAR/.HUM/.TEM
batonrouge.BAR/.HUM/.TEM
losangeles.BAR/.HUM/.TEM
chattanooga.BAR/.HUM/.TEM
The pressure, humidity, and temperature data for each city.