![[Image of the Calendar Screen]](calscrn.gif)
This is the design documentation for Moon Calendar, a Java applet which displays the phases of the Moon for each day of a chosen month. The documentation is divided into the following sections:
The purpose of this project is to teach 1st through 5th grade elementary school students about the moon. It will consist of two main graphical displays. One, a monthly calendar, showing the phase of the moon for each day of the month, will serve as the introductory screen. On this display, students will be able to access a help item giving general instructions for the use of the program, and will be able to enter the month and year for any calendar they wish to generate. A new calendar will be generated as soon as any change is made. Selecting a particular day cell from this display will bring up the second display. This will consist of a more detailed representation of the moon's appearance on that particular day, along with other information. From this display, the student will again be able to set the year and month, as well as the particular day of interest. Further, the student may enter their geographical latitude and longitude, and the local time. With this information, the program will calculate and display the following information: the distance to the moon and sun at the chosen instant, and the time of moonrise, moonset, sunrise and sunset. Selecting any of these items will bring up a text description of the item.
The student will also be able to "animate" the image; in this mode, the lunar phase will be calculated each twelve hours (forward or backward) and the image redisplayed at a rate of approximately four frames per second. Any information related to the calculations, such as distance, will be updated at the same time. Upon terminating the animation, the display will reset to the time selected when the animation began.
The program will also include a list of links to external Web sites related to the Moon and Astronomy; this list , along with the help and information displays, may be edited by the instructor to allow tailoring to specific age groups and interests.
Many of the project constraints are concerned with the age of the target audience - 1st through 5th grade students. Although the aim of the project is to educate, it should be entertaining as well. Students at this age do not have the motor and reading skills of adults and this should be kept in mind when designing the user interface and writing any textual supplements.
The first graphical display, shown below, will consist of the calendar showing lunar phases, an information button, and drop-down lists for selecting the month and year of interest. An list for years 'AD' or 'BC' will also be provided. These lists should be fairly large, as children often have trouble precisely positioning the mouse cursor over a target. Lists also prevent the user from entering invalid data, as only acceptable choices are presented.
Selecting any day cell from the calendar will bring up a detail screen, showing a more accurate picture of the Moon for the day selected, along with other information such as the distance, rise and set times of the Sun and Moon. The user will also be able to animate this image, as well as select other geographical locations.
![[Image of the Detail Screen]](detscrn.gif)
On either of these screens, the user may choose to reset the date to that currently maintained by the system clock; the program defaults to this setting when it starts. Also, selecting any screen element with a dark gray background will bring up a help screen explaining the selected item.
![[Image of the Help Screen]](helpscrn.gif)
Regarding dates, the calculations involved lose accuracy as one moves further from the present time, but should be able to accommodate a range extending from 3999 BC to 3999 AD. This is large enough to include any historical dates of interest the student may wish to explore, and simplifies the logic needed to build the drop down list used for date selection.
It is a fact that in astronomical calculations, it is often convenient to count days consecutively from some starting point in the remote past. This is traditionally accomplished with Julian day numbers, which began their count on January 1, 4713 BC. November 4, 1997 is Julian date 2450758. This approach simplifies incrementing time, rather than having to carry results through months, years, etc. The traditional calendar date may be extracted from the Julian date algorithmically. Since many calculations need both the date and the time, the time is often appended to the Julian date as a fraction of a 24-hour day. Thus, we have one number which represents both the calendar date and the time, which may simplify program structure.
Determining the circumstances of the moon is perhaps the most lengthy astronomical calculation which is commonly undertaken. The most complete theory involves hundreds of terms for each of several different parameters. This is obviously beyond the scope of this project. However, to maintain a reasonable degree of accuracy, there are still many dozens of computations involved, all in double precision arithmetic. As a result, care should be taken to calculate only that which is necessary, and to do so in an efficient manner. Efficiency should not obscure clarity, however. In order to create a program which can be maintained easily, the clarity of the code should be given priority over any attempts to squeeze an few extra cycles out of the equipment.
Finally, a word about external links. Although we find the prospect of linking our program to the internet exciting, it is a sad fact that on the Internet today, searching for just about any word in the English language is bound to turn up some reference to pornography. We need to take the utmost care concerning this, given the intended audience. Therefore, the links provided with the program will have been personally inspected and found suitable for inclusion; they are contained in an external text file which may be edited by instructors as they see fit.
To design the program, we begin by attempting to identify potential software objects, using the problem statement and constraints already discussed. A first pass through the statement turns up the following potential objects:
To determine whether these entities should be retained as objects in this analysis, we evaluate them according to the following criteria [Pressman 567]:
Examining our potential list in this light, we see the User submits or produces information in order to initiate the update action. Once the update takes place, the user reads or consumes the information. Thus, the sixth selection characteristic alone qualifies the selection of a User Object.
The Moon Information Tool consists of two parts: the Calendar Utility and the Detail Utility. Since both parts potentially qualify as objects, the Moon Information Tool is dismissed as an object, although it may be used to describe the system as a whole.
A calendar is an object by implication - it retains a list of related dates, and dates are crucial to providing any celestial information. Thus, the Calendar Screen qualifies under all six selection characteristics. The Detail Screen would seem to be an extension of the Calendar, but in fact, it provides information a calendar would not customarily display, namely Celestial Statistics. Thus, Celestial Statistics are a set of related attributes but not an object, and the Detail Screen qualifies under all six selection characteristics. We will identify these objects as the Lunar Calendar Object and the Lunar Detail Object.
Date and Position are dismissed as objects by selection characteristic one: They do not retain information. In fact, they are data items and are listed as attributes of the two utilities. Date will be assigned to the Calendar utility since a list of dates can be derived from a single date, and since date can easily be passed as a message to other objects. Position will be assigned to the Detail utility since derivation of celestial statistics require not only the date but the position.
The Symbolic Images and the Actual Image would seem to be two similar attributes to be assigned to their respective utility objects. In fact, they are so similar as to be treated as the same attribute, thus providing a good argument to identify this singular "image" attribute as a separate object. In addition, it is known that the "image" is an image of the Moon; thus, the image must depict various degrees of shadow depending on the date. Building varied images will entail the use of attributes that are unlikely to be germane to any other object, so we will identify the "image" as the Lunar Image Generator Object.
Another definition of Phase is the "degree of shadow" mentioned above. Calculating the phase will also require the use of attributes that are unlikely to be germane to any other object, so Phase will be identified as the Lunar Phase Generator Object.
Date is an essential attribute to most of the objects - it is attached to one object and passed as a message to the rest. However, the date must be in Julian format to be useful in various calculations. Thus, date as listed as an attribute is defined as Gregorian; date passed as a message must be Julian and Gregorian. Since Julian conversion requires unique attributes, an additional object will be identified as the Calendar Calculator Object.
Lastly, Help is an object not because information about it must be remembered; it is included as a project requirement and thus is included in the Requirements/Analysis phase. Help attributes will be textual; it's operations will consist of displaying that text. Thus is has enough commonality of attributes and operations to qualify as an object; it will be identified as the Help Object.
These objects are summarized below, with their attributes and methods noted.
Attributes
Methods
Attributes
Methods
Attributes
Methods
Attributes
Methods
Attributes
Methods
Attributes
Methods
Attributes
Methods
Of course, this is a fairly high-level view of the program. Many of the objects identified above could be further decomposed into sub-objects, which in turn could be further decomposed. However, the analysis above gives us enough detail to proceed with implementation.
The aforementioned objects are related to the source code modules as follows, with abstract objects identified in bold type, and corresponding software modules in normal face:
Moon Calendar Applet - MoonCalendar.java
Because it is difficult to write custom event handlers in v1.0, messages are gathered from low-level objects by polling the object whenever an event occurs, to see if it may be of interest to the higher-level object. Any events which can be handled by their enclosing object are consumed, and not passed into the event chain. This approach poses few real problems, other than making the code somewhat obtuse, and violating the spirit of object independence.
The animation and once-per-second updates which occur on the Detail Screen run as a concurrent thread, which is killed whenever another screen is activated or the browser links to a new page; the individual screens are components of a CardLayout object.
Particularly troublesome was the inconsistent appearance of the applet in different browsers running on different platforms. A layout which looked fine under Netscape Navigator on a Macintosh looked terrible under Windows 95, or when viewed with Internet Explorer. Java 1.0 implements it's components by invoking the underlying platform's peer component, and different browser manufacturers choose different peer components in many cases. Add to this the fact that fonts don't support relative scaling, and it quickly becomes impossible to achieve a layout which is satisfying on all platforms. This problem may be ameliorated somewhat when the Java Foundation Classes become part of the standard, but we are reluctant to use such facilities for fear of limiting our audience.
Java's garbage collection routines are another source of trouble. when running in an applet viewer, Moon Calendar was easily able to generate animations at nearly 50 frames per second. When run under the Netscape browser, this frame rate did not allow enough time for the interpreter to dispose of the old images, and we consistently locked up the machine we were testing on. After much experimentation, we had to settle for a frame rate of only four per second, which provides enough idle time for cleanup to occur.
Because we were concerned about speed, we chose a somewhat inexact algorithm to calculate the Moon's position; this leads to lunar rise and set times which are only within about 45 minutes of the actual value. Although this could be substantially improved, the computational cost of doing so are quite high; again, many schools do not have access to state of the art equipment, and we want them to get as much benefit as possible from the program. It was felt that this was a decent trade-off, since actual Moon rise and set are usually blocked by horizon obstructions.
As an applet, Moon Calendar must be installed as part of a Web page. It is preferable to store all of the .class files in a single .jar file for fast downloading; however, some browsers do not yet support this access method, in which case the individual .class files will be downloaded if they are present. It is therefore recommended that both the .jar and individual .class files be placed on the server to accommodate the widest audience.
In addition to these files, the various help files, site list and Moon image .gif should be placed in the same directory as the object files. The program will still run if these are absent, substituting default messages for help screens and a plain white image for the Moon; the site list will simply not appear.
The list of external sites is a plain text file, called "Sites". The first line in the file is the name you wish to appear in the drop down site list; the second line is the URL of this site. For example, here is the file currently installed with the program:
Clementine Lunar Image Browser
http://www.nrl.navy.mil/clementine/clib/
Apollo Project
http://www.ksc.nasa.gov/history/apollo/apollo.html
Lunar Exploration
http://nssdc.gsfc.nasa.gov/planetary/lunar/apollo_25th.html
Moon Photographs by Michael Myers
http://www.netaxs.com/~mhmyers/moon.tn.html
Royal Greenwich Observatory
http://www.ast.cam.ac.uk/RGO/RGO.html
Due to a bug in the Netscape browser, the last line in the file must NOT be terminated with a carriage return; doing so will result in the last link being misinterpreted.
The help files for the various screen elements are:
Calendar.hlp
Credits.hlp
DateCalendar.hlp
DateDetail.hlp
DetailInfo.hlp
Gregorian.hlp
Info.hlp
LatLongDetail.hlp
TimeDetail.hlp
Although these files may be plain text files, it is recommended that line breaks be hard-coded at present; due to a faulty implementation of text wrapping on some browsers, a flat text file may be displayed as one long line, which must be scrolled for viewing. Make any changes to the file required, select the pertinent item from the running program, and evaluate line breaks manually.
The association of these files with the various program elements is shown in the illustrations below:
Even a moderately complex program requires extensive testing, and Moon Calendar is no exception. Our main concerns were that the program should perform well in terms of speed, that it be as fault tolerant as possible, and that it's results should be as accurate as possible.
Object oriented, top down design greatly reduces the number of tests that need to be performed on software. A properly designed software object possesses two desirable characteristics: High cohesiveness and low coupling. Cohesion indicates that the functions of an object are logically related and well encapsulated within the object. Low coupling means that dependencies between objects are kept to a minimum. This last is particularly important from a testing standpoint, as a large number of dependencies quickly leads to a combinatorial explosion of tests which must be performed. Although integration testing must still be performed, the number of combinations implied by exhaustive testing is greatly reduced if each object exists in relative isolation from others.
A strange time warp exists with regard to computers: although they can perform many tasks far more quickly than the user could ever hope to, small periods of inactivity are magnified into what are perceived as inordinately long delays. For this reason alone, a program should execute as quickly as possible, or at least provide some indication to the user that work is being done.
As an applet, Moon Calendar is at the mercy of two main performance bottlenecks: the speed of the user's network connection, and the speed of the Java interpreter. We have no control over either of these factors, and attempt to work around them as best we can.
The applet displays nothing until it is fully loaded by the browser, a process which takes about one minute on an average connection. Although the browser typically displays a message in it's status line that a download is taking place, this delay can be mitigated somewhat by downloading as few files as possible, and by encapsulating all Java .class files into a .jar file, which requires only one server hit to download. The only additional files required are the help files, and the .gif image of the Moon used on the Detail Screen. While this image is downloading, the applet displays a message in the status bar to indicate that something is happening, so at least the user doesn't feel that the program is frozen. The help files are not downloaded at all, until they are requested, using the following technique.
A hash table is created, containing entries for each help item; these are initially set to null. If a help request is encountered, the applet first checks the hash table to see if there is a non-null entry. If so, it is read from the table and displayed. Only if the entry is null does the applet attempt to download the relevant file. If this is unsuccessful, a default message is displayed. This approach has several advantages. The help files exist as separate entities, which the installer can easily modify; the experienced user is not penalized by having to wait for the files to download; the novice user, meanwhile, can be expected to access help for a particular item several times until they learn it's usage, yet only have to wait for a single, small file to download once for each item.
Another great concern for this particular applet was the speed of the Java interpreter. Moon Calendar performs extensive floating point calculations to determine the position and phase of the Moon, and these calculations must be done for each frame of an animation, and approximately thirty times each time a new calendar screen is requested. In addition, the routine which draws the shadow onto the lunar .gif required a hand-coded routine to draw a rotated ellipse, a facility which the Java graphics routines do not provide.
Although interpreted languages are inherently slower than their compiled counterparts, we were pleased to find that Java performed extremely well in this regard. Typically, the routines to calculate and draw the Moon image executed in well under 1/50 second. Due to inefficient garbage collection, however, we were forced to limit the frame rate for animations to four frames per second, to avoid exhausting memory under some browsers. This still provides an acceptable animation, and we would hope that in the future more efficient garbage collection routines will make higher frame rates possible.
Any program should be able to survive adverse conditions; if it fails, it should fail gracefully. Because we intended Moon Calendar to be used in elementary schools, where it would potentially be incorporated into lesson plans, we wanted it to perform even when errors were encountered, to avoid disrupting class schedules. To this end, we took the following steps.
One potential source of trouble was bad user input, in the form of invalid dates or times. This is avoided by limiting input to acceptable values only, through the use of drop-down lists. As already noted, this entry method was preferred over typing given the age of our target audience. Two potential problems still need to be checked: a date beyond the acceptable range for a particular month (i.e., February 30) and selecting the year zero, which doesn't occur in the civil calendar. Unfortunately, Java v1.0 does not allow modification of drop-down list during program execution, so we could not remove dates outside the range of a particular month. However, if the user selects such a date, the program will default to the last day of the month selected. For example, choosing February 30 would cause the program to set it's date to February 28 (or 29 in a leap year). Similarly, if the year zero is chosen, the program displays the choice as the year 1 BC, which is consistent with the manner in which years are counted: the year 1 BC immediately precedes the year 1 AD.
During animations, the applet increments/decrements the current time by 12 hours, and draws the corresponding image. It is possible that, during an animation near the limits of the acceptable range, the program will "walk off" the range. If the date ever exceeds the limits of 3999 BC/AD, the animation simply stops. This may be somewhat jarring to the user, but such an eventuality is expected only rarely, and is preferable to the somewhat ambiguous alternative of reversing the animation direction.
It is possible, for various reasons, that the external files used by the program will be unavailable. These include the Moon image, help files and external site list. The files may be improperly installed, or the server may choose an inopportune moment to go down. To allow the program to survive such eventualities, default behavior is provided.
If the lunar image file cannot be found, the program constructs a substitute graphic, replacing the .gif photo with a white disk on a black background. Apart from the plain image, the program remains fully functional.
If the help files cannot be downloaded, a default help message indicating this fact is substituted for their content; similarly, if the external site list is missing, the drop-down list which contain the links is simply not displayed. In both cases, the program continues to execute normally.
Finally, if the user's browser does not support Java, they won't be able to view the applet. Obviously, there is no workaround for this; however, we do inform the user of this difficulty through the use of HTML [alt] tags. The program has been tested under all of the aforementioned circumstances, and has been found to perform well under Netscape Navigator 3.0 - 4.01 and Internet Explorer 3.0 - 4.0, on Solaris, Macintosh and Windows NT and 95.
As previously noted, the algorithm used to compute Moon rise and set times is somewhat inaccurate, but acceptably so. The other information, such as lunar phase, lunar and solar distance, has been checked against as many different sources as possible. In the case of our references, several worked examples were examined, and program results were found to be in agreement with them. Further, local newspapers were consulted for phase, rise and set times. Finally, historical results were checked, and phase information has been validated back to the mid-1700's.
We wanted the program to display the Moon as it would appear naturally in the sky. As things now stand, this is true for an observer in the Northern hemisphere, looking South. Ideally, if a southern latitude is chosen, the image would be flipped upside down. This is not presently done, because such a routine will perform slowly under an interpreter, and is a feature which should be available when Java v1.1 becomes widespread. We apologize to those living south of the equator, and plan to correct this deficiency when time allows.
Although the program accepts a wide range of dates, it should be noted that the accuracy slowly decreases as one moves farther from the present time. We have so far been unable to find historical records of lunar phases for the distant past; however, the program has been found accurate for at least a few hundred years into the past, and given the vagaries of remote calendar systems, any departure much beyond this span would be difficult to quantify.
Testing of the date calculations was again verified against worked examples in references, and particular attention was paid to various boundary values. The transition from the BC to AD epoch was of particular concern, to ensure that the civil convention of not having a year zero was obeyed; internally, dates BC are counted as negative values, another reason for checking this boundary. Another transition takes place in October 1583, when Pope Gregory XIII revised how leap years are calculated, and eliminated 10 days from the calendar in order to bring it back into alignment with astronomical events. Calendars on both sides of this boundary were validated, and special provisions are made for displaying this particular month. This leads to a small "Easter Egg" in the applet: if October 1582 is chosen, the missing days are represented as blanks, and a new information button appears on the screen, explaining the odd appearance.
Finally, calendars were checked in both leap and non-leap years, paying particular attention to the month of February, to ensure that the proper rules were followed in both the Julian and Gregorian epochs. Checks were also performed from month to month and year to year, to ensure that dates and weekdays flowed smoothly over such transitions.
All checks performed produced the expected results; Moon Calendar has been in use for several months, in both classrooms and by casual users, and no anomalies have been reported apart from minor inconsistencies from one browser or operating system to another. Amongst elementary school users, the favorite activities seem to be checking the phase of the Moon on a child's birthday (adults do this, too) and on the date of particular historical events, such as battles. We feel that Moon Calendar is a good beginning towards using the World Wide Web as an educational tool; now that there is a mandate to have a computer in every classroom, providing good quality educational software should be the next goal.
Deitel, Harvey M. and Paul J. Deitel, Java: How To Program, 1998, Prentice-Hall, Upper Saddle River, New Jersey
Dershowitz, Nachum and Edward M. Reingold, Calendrical Calculations, 1997, Cambridge University Press, New York
Meeus, Jean, Astronomical Algorithms, 1991, Willman-Bell, Richmond, Virginia
Pressman, Roger S., Software Engineering, A Practioner's Approach, 4th Edition, 1997, McGraw-Hill, New York
Schach, Stephen R., Classical and Object-Oriented Software Engineering, 3rd Edition, 1996, Richard D. Irwin, division of Times Mirror Higher Education Group, Inc., Chicago, Illinois
Tufte, Edward R., The Visual Display of Quantitative Information, 1983, Graphics Press, Cheshire, Connecticut