North Carolina Department of Environment and Natural Resources
Division of Air Quality - IMPAQ Documentation
Air Awareness Module - Ozone Forecasting
The addition of a mechanism for Ozone Forecasting to IMPAQ's previously existent Air
Awareness module results from a need realized in part by the redesign of DAQ's public WEB site.
Previously, forecasters had submitted forecasts and associated data via WEB forms residing the
external SIPS WEB server. That data was then processed by PERL scripts running on the SIPS
server to generate WEB pages for public consumption. Further, scheduled (CRON) jobs on the
SIPS server were responsible for regenerating these WEB pages at specified intervals during the
day.
One of the Air Awareness module's important functions is to disseminate Ozone Forecast data
via email to various recipients. The forecast and associated data have previously been
downloaded in the form of text files from the SIPS server and used to populate ORACLE tables.
To avoid this cumbersome and often error-prone process, it is necessary to provide a mechanism
within IMPAQ where ozone forecasts and associated data may be submitted directly into
ORACLE. Then, public WEB pages will be generated in-house and delivered to the SIPS WEB
server via FTP. Additionally, the storage of forecast data into ORACLE will provide historical
records necessary for desired reporting and presentational products. Lastly, we gain additional
control over the process by alleviating the need for data processing by both the SIPS WEB server
and our in-house servers.
I.
IMPAQ Screens (JSP)
The Ozone Forecasting sub-module consists of two (2) screens, or Java Server
Pages (JSPs). The first, o3ForecastSubmission.jsp, is the entry point for Forecast
Ozone AQI (air quality index) values. The second, o3ForecastDiscussion.jsp, is the
entry point for associated Forecast Discussions. These files are found within the
IMPAQ application in the AirAwareness folder.
a. o3ForecastSubmission.jsp
North Carolina Department of Environment and Natural Resources
Division of Air Quality - IMPAQ Documentation
Air Awareness Module - Ozone Forecasting
i. General Description
The first and most prominent feature of the forecast submission screen is a
grid consisting of forecast areas on the Y-axis and dates on the X-axis.
For each area/date combination, there is an HTML form input box for the
AQI value. Under each input box is a graphical pixel shim which changes
to reflect the color code associated with the AQI value (GREEN, YELLOW,
ORANGE, RED, or PURPLE). The bottom row of the grid contains buttons
labeled "DSC" for each date shown. These buttons direct the user to the
discussion submission screen.
The last row of our grid contains two buttons. The first, "Save Forecasts",
first calls a Javascript function to check for errors in the input data. If a
value is found in error, the user is alerted to check that value and is given
the specific date on which the error occurred. If no errors are found, we
initiate a process to save the forecast data into the
AIR_AWARE.FORECAST table. The "Submit Forecasts" button is used to
manually regenerate the HTML code fragment for the current forecast and
transfer it to the SIPS server. In essence, this is used to recreate the
ozone forecast WEB page on our external WEB site. This button is only
used in the event that something must be changed outside of our
scheduled file uploads.
To the left of the aforementioned grid are controls for adjusting the view
presented by the grid. The user may use these controls to move the grid
forward or backward in time from one (1) day to six (6) days, with the
former being the default value. In addition, the number of days shown in
the grid may be adjusted from one (1) to seven (7), with the latter being the
default value.
Finally, underneath the view adjustment controls is an AQI calculator. Its
function is to compute an AQI value from an ozone concentration value
expressed in PPB (parts per billion). The user may enter the ppb
concentration, depress the "Calculate" button, and the AQI value appears
in the appropriately labeled text input field. The AQI value is automatically
selected such that a copy-and-paste operation becomes easier.
ii. Technical Details
The dates for the main grid are generated by instantiating a
GregorianCalendar object which an index value determined by the
"daysMoved" parameter (set via view adjustment controls). By default,
the index value is set to -1 so that we begin with yesterday's date. We
then produce 2 Vectors, 1 containing textual days (Monday, Tuesday,
etc.) and the second containing numerical dates (01/01/2002, etc.). The
size of these vectors is determined by the "daysShown" parameter (set
via view adjustment controls) and is initially set to 7 so that we display 7
days. We reload the page any time the user changes the "daysMoved"
or "daysShown" parameter to produce the desired output.
Forecast Area names for the grid are produced by instantiating an
AreaManger object and retrieving a Vector of AreaObjects. We then
loop through this vector and gather an area name and area id for each
AreaObject. Using this information, we produce the main grid, naming
North Carolina Department of Environment and Natural Resources
Division of Air Quality - IMPAQ Documentation
Air Awareness Module - Ozone Forecasting
each input field with the convention (AREA_ID)_(DATE). If the input field
date is 36 hours prior to the current date (calculated from 12:00 AM
midnight), we disable that field. We loop through our Vector of dates a
second time to produce the buttons labeled "DSC" at the bottom of each
column and associate each of these buttons with the corresponding date.
An additional feature of this main grid is the pre-population of historical
forecast data if it exists. To accomplish this, we call a Javascript
function as the page loads. This function retrieves a resultSet from a
database call based upon the dates we have selected for our grid. We
then loop through the resultSet and set values for the corresponding
input fields.
Pre-population also sets the graphical pixel shim underneath each input
box to the appropriate color via Javascript. This same function is called
from each input field using an onChange event. If the input field's value
is within the realm of valid AQIs (0-301), we change the graphic to reflect
the appropriate color code. If not, we alert the user of an invalid entry.
The "Save Forecasts" button instantiates a ForecastManager which
inserts records into the AIR_AWARE.FORECAST table. The "Submit
Discussion" button instantiates an ExternalForecastFragment which
generates and transfers an HTML code fragment to the SIPS WEB
server. This HTML fragment makes up the main portion of the external
Ozone Forecast WEB page, found at
http://daq.state.nc.us/airaware/ozone/. The fragment is encased in this
WEB page via SSI such that we only need to recreate the fragment, NOT
the entire page, to update the external WEB site.
Finally, the AQI calculator is implemented purely in Javascript. The user
enters an ozone concentration in ppb and the "Calculate" button calls a
function. That function then sets equation parameters based upon the
user's input, computes the AQI value, and sets the AQI field to that
value.
North Carolina Department of Environment and Natural Resources
Division of Air Quality - IMPAQ Documentation
Air Awareness Module - Ozone Forecasting
b. o3ForecastDiscussion.jsp
i. General Description
The most prominent feature of the forecast discussion screen is an
HTML textarea that houses discussion text input. The discussion type is
shown in a select list on the upper left. The date for the discussion is
shown on the upper left along with buttons to allow the user to move
forward or backward through time.
The buttons underneath the textarea present the user with several
options. The simplest is the "Cancel" button that simply closes the
discussion window. This button are always visible to the user.
The "Save Discussion" button initiates a process to save the discussion
text into an ORACLE table. The "Submit Discussion" button generates
and transfers HTML code fragments to the SIPS WEB server for use in
our public WEB pages. If the user moves to a date which is 36 hours
prior to the current date (calculated from 12:00 AM midnight), the save
and submit buttons are not visible.
ii. Technical Details
The forecast discussion screen opens in a new window when one of the
buttons labeled "DSC" on the forecast submission screen is pressed.
This button calls a Javascript function to open the new window, passing
the associated date as the only parameter.
North Carolina Department of Environment and Natural Resources
Division of Air Quality - IMPAQ Documentation
Air Awareness Module - Ozone Forecasting
If a forecast discussion for the selected date exists in the database, the
textbox is pre-filled with the appropriate text. This checking is again
accomplished with a Javascript call when the page loads. The actions of
moving forward of backward in time, as well as that of selecting a
different discussion type, are processed solely on the client side and
involve no interaction with the server. In most cases, Javascript is called
simply to set parameters and to reload the page.
II.
Servlets
a. ForecastServlet.java
ForecastServlet is the only servlet used by the Ozone Forecasting screens and is
responsible for handling requests from those screens. Generally, most processing
for the JSPs is accomplished with client-side Javascript such that the requests
handled by ForecastServlet involve saving or submitting forecasts and discussions.
III.
Serverclasses
a. ExternalForecastFragment.java
ExternalForecastFragement is responsible for generating the HTML code
fragment for the main Ozone Forecast page on the SIPS external WEB server.
Additionally, it transports this fragment to the SIPS server via FTP. An
ExternalForecastFragment is instantiated from ForecastServlet when the "Submit
Forecasts" button on the Forecast Submission screen is depressed. This class is
also instantiated via a scheduled job to regenerate the external forecast page at
3:05 pm and 12:01 am.
b. ExternalDiscussionFragment.java
ExternalDiscussionFragment generates HTML code fragments for the three
forecast discussions and transfers these fragments to the SIPS external WEB
server via FTP. A ExternalDiscussionFragment is instantiated from
ForecastServlet when the "Submit Discussion" button on the Forecast Discussion
screen is depressed. Because this button is the only mechanism by which the
external discussion pages are regenerated, there is no scheduling associated
with a ExternalDiscussionFragment.
**Note the above classes are extensions of ExternalFragment.java which
contains common methods for writing output files and transferring those files via
FTP.
c. ForecastManager.java
ForecastManager is responsible for inserting records into the
AIR_AWARE.FORECAST table based upon user input from
o3ForecastSubmission.jsp. A ForecastManager is instantiated when the user
depresses the "Save Forecasts" button in the Forecast submission screen.
North Carolina Department of Environment and Natural Resources
Division of Air Quality - IMPAQ Documentation
Air Awareness Module - Ozone Forecasting
d. DiscussionManager.java
DiscussionManager is responsible for inserting records into the
AIR_AWARE.DISCUSSION table based upon user input from
o3ForecastDiscussion.jsp. A DiscussionManager is instantiated when the user
depresses the "Save Discussion" button in the Forecast Discussion screen.
e. FileTransferManager.java
FileTransferManager is responsible for handling the scheduled transfer of the
ozone forecast HTML code fragment to the SIPS WEB server.
FileTransferManager is instantiated from a command file
(ozoneFileTransfer.cmd) and contains much the same code with respect to the
external HTML code generation and transport as found in ForecastServlet. The
main difference is that it uses ClientDatabase rather than Database so that it may
be run independently. In addition, FileTransferManager contains a method to
send an email message to select IT associates in the event that the scheduled
file transfer fails.
IV.
Email / Fax Dissemination
Alterations in the Email / Fax portion of the Air Awareness application were
necessary because of data source changes. Specifically, the downloaded text files
from the external SIPS server will no longer feed data into the process. Instead, the
forecast color code and AQI index will be accessible directly from the
AIR_AWARE.FORECAST table. Because data entry and submission are now
accomplished through IMPAQ screens, the need for saving information in the
Database as part of the Email / Fax process also disappears.
Changes to this process involve AAProcessor.java and AAManager.java.
a. AAProcessor.java
Called from a command file, AAProcessor handles most tasks associated with
delivering forecast emails / faxes. This code previously downloaded the
necessary text files from the SIPS external WEB server in its getFiles() method.
This method has been removed in favor of a new method, getForecastData(),
which reads values from the AIR_AWARE.FORECAST table and returns a
Hashtable for use throughout the rest of the program. Additional alterations were
necessary to pull data from this Hashtable rather than from a text file.
b. AAManager.java
AAManager was previously responsible for saving ozone forecast data into the
AIR_AWARE.FORECAST table. Because that process is now handled via
IMPAQ data entry screens, Database insertion code was removed from
AAManager. This is the only change made to AAManager.
The process begins at 3:10pm daily when an AAProcessor is instantiated via
command file, D:\Webgain\bea\wlserver6\config\DAQ\serverclasses\airawareprod.cmd (in development and production test, the "-prod" is replaced with "-dev" and
"-test”, respectively). AAProcessor determines tomorrow's date and uses it to
retrieve the necessary data from AIR_AWARE.FORECAST. It then builds and sends
Daily and Alert emails to a list of recipients generated from AIR_AWARE.CONTACTS
and associated database tables.
North Carolina Department of Environment and Natural Resources
Division of Air Quality - IMPAQ Documentation
Air Awareness Module - Ozone Forecasting
In addition, printable forecast flyers are generated as HTML documents and exported
into D:\webgain\bea\wlserver6\config\daq\applications\impaq\AirAwareness\FaxDocs.
A link in the email messages and in the external Ozone Forecast Center page(s)
directs users to this location for these printable flyers.
While major changes to this process involve the data source, minor modifications
concerning printed URIs and formatting of email / fax documents have also been
made.
V.
Miscellaneous Notes
The default "Ozone Forecast Center" WEB page must be changed at the beginning
and ending of the forecast season (01 May and 30 September, respectively). During
the season, the default index page is the "shell page" containing our dynamically
generated forecast fragment. This page links to another index (index1.shtml) which
contains "Additional Information and Links" and is much the same as our off-season
index page, except that it contains a link to printable flyers and does not include an
end-of-season message at the top.
Therefore, the default pages present in the EXTERNAL /airaware/ozone/ directory
are as follows:
a. Off-season
Index.shtml
Index.in
Index1.in
b. In-season
Index.shtml
Index.off
Index1.shtml
Default page containing end-of-season msg. at top of page
In-season default "shell" page
In season "Additional Information and Links" page
Default "shell" page containing dynamic forecast fragment via
SSI
Off-season default page containing end-of-season message at
the top
In season "Additional Information and Links" page
At the beginning of Ozone Season, we run OzoneStart.cmd, a command file that
receives FTP instructions from OzoneStart.ftp. This functions to rename files on the
external WEB server as listed in (b) above. Specifically, index.shtml is renamed to
index.off, index.in is renamed to index.shtml, and index1.in is renamed to
index1.shtml. This process takes place a shortly AFTER the first forecast code
fragment is transferred at the start of ozone season (~3:07pm 30 April). It occurs
after the first dynamic code transfer to prevent the user from seeing our "shell"
default page without any forecast information.
At the end of ozone season, we run OzoneEnd.cmd (OzoneEnd.ftp), which does the
exact opposite of OzoneStart.cmd. This is run at ~12:01am 01 October to bring the
directory contents into off-season mode.
Although this process might be easier accomplished with scheduled CRON tasks
running directly on our external WEB server, we maintain more control over the
process by running these command files remotely. These command files and
associated FTP instructions reside in the
D:\webgain\bea\wlserver6\config\daq\serverclasses directory.