The Mayday Application

The Problem

Boats at sea usually report their position once a day via radio to a land-based controller. These reports provide a 'last known position' in case of accident. The position of a boat is expressed as a Latitude (North or South of the Equator) and Longitude (East or West of the Greenwich Meridian). Both Latitude and Longitude are expressed in degrees and minutes. Degrees are whole numbers ranging from +180 to -180 for Longitude and +90 to -90 for Latitude. The minutes must be in the range 00 to 59.9999.

A minute of Latitude (anywhere) corresponds to 1 Nautical mile. Minutes of Longitude are equal to minutes of Latitude at the Equator, but get progressively shorter as the Latitude increases, until they become zero at the poles.

The calculation of the distance between two positions, expressed as Latitude/Logitudes, is complicated by the shape of the earth. For small distances, an adequate approximation is to imagine a straight line between the two points and to calulate the distance using Pythagoras, correcting for the changing length of minutes of Longitude. For longer distances, a calculation which accounts for the curvature of the earth is required.

'Mayday' is the internation signal for distress and indicates that there is a danger to life aboard a boat. If a MayDay is called by one of the boats (the 'target' boat), all nearby boats are required under international maritime law to proceed to its help, but it makes sense to identify the boats nearest to the target's position.

Running the Application

When the application starts, a form is generated containing a drop-down list of the known boats.
With this form, the user can select a target boat from amongst the set of known boats and specify the range in which to search.
When the request is submitted, a second page shows the position of the target boats and the position of all boats with range of the target.

Search for a nearby Boat

Design

Types

We will represent a position as two quantities, a Latitude and a Longitude. Both of these are expressed in degrees and minutes so we will also define a more basic degrees/minutes type. Both will be value types - that is they will behave like primitive data types, which have immutable values.

Both new types will need functions (aka methods or operations) to return calculated (derived) values. So for a degrees/minutes object, we want to convert to Radians (there are 2Pi radians in 360 degrees) since trigonometric functions require input in radians. We also want to display these values in a readable way, as a formatted string.

The LatLong type, containing two degrees/minutes values, will need methods to present the value in a readable string, and more critically, to calculate the distance between one LatLong object and another.

The boat Boat Type will initially contain a name (using the standard String type) and current position (using the LatLong type).

Only one set of Objects will need to be held, the set of known Boats, so just one table is required, a table of boat objects.

3-tier System Architecture

User interaction

User interaction will be provided by HTML pages running on any browser. HTML provides the capability to display information from the database as well as collect user selections and input.

Middle ware

PL/SQL procedures will provide the interface between the User interface and the database of boats. Two procedures will be required.

The first will extract the set of known boats from the database so that an appropriate selection can be presented to the user.
The second will accept the user's request, search for boats within range and return a list of boats and their positions, nearest first.

Database

The database will be implemented in Oracle 9i using the Object extensions.

Implementation

Type definitions

First we define a new datatype to hold degrees and minutes: The type dm
We can test this type on its own Test dm Note the use of the default constructor to create objects.
Then we can define a type for latitude/longitude positions: The type latlong
We can test this type on its own Test latlong
Finally we define a type to describe a boat: The boat type
We can test this type on its own Test boat

Table definitions

Objects are contained in tables in Oracle (not stored on a heap as in a pure object system). So we need to define a table of boats

Initial configuration

We now need to create some initial objects.

Interfacing procedures

Two PL/SQL procedures are required in the middle layer.

to generate a form to allow the user to select a target boat and range
to do the search and return the results [If these procedures don't format properly in your browser, view the source instead]

Suppport code

Exercises

Week 1

Start Exceed to login to the Unix machine
Using Netscape, browse through this appplication to get a feel for how it has been developed
Run the application
Install the dm type on your own database by :
- create a new directory under your public_html directory
- saving the defdm.sql file and the testdm.sql file to this directory (Save as from Netscape)
- start sqlplus and execute these command files (@defdm and @testdm)
modify the testdm.sql file to add additional tests and rerun it
using a text editor, add a new method to return the degrees as a real number - you can model this method on the asMinutes method
modify testdm.sql again to add tests for this new method - choose values for which you can predict the answer.
use the new function to simplify the code for asRad()
add a further function to return the number of hours ( 24 hours is 360 degrees)

Week 2

Install the full boat application as follows:
- Change directory to the directory created last week
- copy the files from my directory with the command (Note the final . in this command):
```
cp -i ~cjwallac/public_html/oodbms/boat/* .
```
  This will copy everything in my boat subdirectory to the current directory. The -i directive will prompt you if you are about to overwrite a file of the same name.
- using sqlplus, run the command @createdb
- run each of the test scripts
- run the queries q1,q2 and q3
replace the copied index.html page with one of your own. To invoke the chooseboat.sql, use a link of the form:

< a href=http://roger.cems.uwe.ac.uk:7778/pls/cems901dad/cjwdemo.chooseboat>
Change cjwdemo to the usercode of your own database.
Remember to change the access rights of the index.html file to 644 (chmod 644 index.html)
When you have got the base application going, you can modify it yourself.
- modify the stored procedures to put in your own headings and prompts
- put the results of the search in tablular form
- harder: create two new procedures :
  - modifying chooseboat by replacing the range input by a position (latitude and longitude). The user should be able to enter the position in degrees and minutes, so 4 fields will need to be added.
  - modifying getnearestboats to return the distance between the selected boat and this position. Note that the values passed from the form in the first procedure are strings, and will need to be converted to numbers by the function TO_NUMBER() e.g.
```
      latdeg := TO_NUMBER(latdegstring);
```
  - Put a link on the modified index.html page and test it.
- Here is my solution : [procedures look better when you view the source]

Week 3 Further exercises

Here are some of the exercises which could be undertaken with this basic system. In tutorial we will look see how you might solve these problems, but not necessarily implement them. Look out for opportunities to re-use Types which have already been developed.

Add a new table, containing the locations of places such as ports, headlands etc. Using this new table, write new procedures to allow the user to calculate how far away a selected boat is from a selected place. Do you need a new type to do this, or maybe we should generalise and existing type?
Extend the boat object type to incorporate a new attribute speed and a new member function hoursTo(x latlong) which calculates how long the boat will take to get to the position at its speed. Modify the procedures accordingly.
We sometimes want to report the speed in m/sec and also Km/hr. If Speed has a simple number type, there is nowhere to put methods to do this conversion. Create a Speed type with just one attribute but several methods to return the speed expressed in different units.
We really need to represent the Velocity of the boat - its speed and direction. Values of this type can be used to represent the speed and direction of the boat, but can also be used as the type for wind speed and current later in the exercises. Create a new type Velocity, with two attributes: speed in Knots and direction in degrees. You will need a Type for Direction as well, because sometimes we want to be able to report it in the coarser units of points of a compass. The compass is divided into 16 points which run: N NNE NE ENE E etc. Each point covers a range of 360/16 = 15 degrees, so E would cover the range from 90-7.5 = 92.5 to 90+7.5 = 97.5. Will the StepFunction do this or is there a simpler way? Use this new type to replace the simple speed variable in the Boat type.
Wind speed is often reported in the Beaufort Scale. Add a suitable method to the Speed type to return this value.
Add a new method to latlong to compute a new position given a velocity and a time. The method to calculate the new position will require some trigonometry. Test it with the following select statement:
```
  select latlong(dm(0,0),dm(0,0)).move(velocity(20,270), 60)) from dual;
```

Step Function

The StepFunction type and some tests

Reports

Position reports are received each day. We need to keep the history of reports, together with the date and time they were recorded. Each position report will record the date and time, the position and velocity.
Interspersed with the position reports are other reports.

weather reports describe the wind velocity, wave height, swell direction and cloud cover.
warning reports describe the observation of a navigational hazard is seen at a given time and place
problem reports which describe the problem and assistance required

Use cases and sequence diagrams

Update Position

Here is a simple example of implementing the 'Update Boat position' use case. It can be described by a sequence diagram from which the code for each prodedure can be reached and the whole use case executed: Update Position Usecase

The sequence diagram is generated from a text script by a perl program. I intend to put this application on-line in the near future.