Mujtaba's design study

About the Project

Java Ephemerides API (JEA) is a project to design a java API library that can be used to connect to any ephemeris data repository and query it for information about celestial bodies.

Problem Demystified

It is important to understand the problem I'm trying to solve here before one can proceed with trying to understand the OO design below. Basically the main problem here is that we want to know information about celestial bodies. Celestial bodies include all the known planets, stars, comets, asteroids, and even man-made satellites. The kind of information we are interesting in is called Ephemerides or Ephemeris (as singular form) and it basically refers to such information as: the celestial body's location in the sky, brightness, rise time, set time, velocity, distance, temperature, pressure, number of satellites, radius, orbital period, gravity, .. etc. As an OO designer you might want to think of those as simply properties of celestial bodies, but astronomers would of course not agree with the term ‘properties’ as it blows away that sense of scientific pomposity from the word ‘’’ephemeris’’’.

Shortcut

--Those properties or ephemerides mentioned above are stored and maintained by NASA. They provide a system called HORIZON that can be used to query the ephemeris of any celestial body the user wants. They also provide large files that contain this information. There are several ways of hooking into those information repositories and querying them for data. The OO design below basically tries to provide a Java framework that could be used for dealing with ephemerides regardless of the type and source of the repository. It could be used to hook into NASA’s system or any other system providing ephemeris info.

--You can now jump to the design description section, but if you run into any mystery then blame only yourself.

Complexities

As you might already have guessed, there is various numbers of complexities in reporting those ephemerides information. I list these complexities below:

• 1-Not all properties are applicable to each celestial body. For example, pressure is not applicable for a man-made satellite.

• 2-While some properties are static like number of satellites and radius, many of them are actually variable ones like location, rise and set time, distance... etc

• 3-Many of those properties are actually not absolute data points but are relative ones depending on the observer’s location. For instance, Mars location in the sky for someone standing on earth is different from its location for someone who is in space stations like the ISS. To complicate things further, Mars location in the sky would actually differ for observers depending on their exact location (longitude & latitude) on the observing site. It’s location for an observer in Christchurch is different from that for an observer in London. Similarly, distance and velocity are also relative to the observer’s location.

• 4-Many properties can be reported in various numbers of formats or standards. The most complicated property (or ephemeris) is actually the location. A celestial body’s location in the sky is reported in what’s called a coordinate system and there are different numbers of coordinate systems in use. The two most popular ones are ‘’’Right Ascension-Declination’’’ shortened as ‘’’(RA-DEC)’’’ and ‘’’Azimuth-Elevation’’’ shortened as ‘’’(AZ-EL)’’’. Each coordinate system can have more than one format of reporting, for example RA-DEC can be reported in degrees or in minutes and hours of an arc. The same coordinate system can also be reported according to different standard reference points known as Reference Frames. The ‘’’important’’’ thing to know here however is that once we have the location of a body’s location in a certain coordinate system, then we can use mathematical functions to convert that coordinate system to any other coordinate system we need.

• 5-Some properties are measured ones and astronomers actually re-measure them from time to time for accuracy reasons. Some (like a body’s location) are also interpolated using known mathematical functions.

Reporting the Ephemerides

For the reasons above, astronomers used to have long tables that list those ephemerides for the major planets for several months ahead. Today, NASA provides a ‘’’Repository’’’ that astronomers could hook into and query the ephemeris of any celestial body they want. ‘’’To query the repository you would usually have to specify the celestial body, the date, time, and observer’s location and then the system would provide you with all known ephemeris info about that celestial body for the date, time you provided’’’. Of course, this is only the basic and most common query; the system still provides various advanced ways of queries and options to specify.

JPL’s HORIZON SYSTEM

The system that we talked about above is called ‘’’HORIZON’’’ and it operated by the Jet Propulsion Laboratory (JPL) of NASA. It appears that it is currently the only system of its kind in the world and I assume it is used worldwide by all astronomers and space agencies around the world. They provide ‘’’two’’’ ways of querying the system; a full featured ‘’’telnet service’’’ (full featured in terms of the options provided and possible ways of querying the system) and simple ‘’’web interface’’’ one. Moreover, they also provide large files containing the data in raw format. Those files are released continuously and only contain data for specific period of time (e.g. from 1990-2020) and are meant to be used by professionals who want to extract the data and report it in their own way. The files also come in different standards.

Definitions

Ephemeris:

Coordinate System:

Step & Step Identifier:

Users

The API will obviously be most useful for astronomers and amateur sky observers. They can use it to exactly locate and pinpoint any celestial object of interest in the sky. Nowadays observers are well equipped with electronic and computerized telescopes that can automatically navigate to any object in the sky with the press of a button. All of that is done by internally looking up the object's ephemeris data in the device's internal database. In fact, any kind of spacecraft can't navigate in space without being equipped with some means to calculate ephemerides information.

Still, the users of this API are not limited to astronomers only. Many scientific disciplines do require such ephemerides information, especially those of the Sun's and Moon's since they are close to our planet and impose various effects on our planet that different scientific disciplines might be interested in. For example, a scientist studying how the Sun's position in the sky help birds finding their way during long distance migration, will find such a tool invaluable.

Description of the Design

The Request Handler Class

This class is a singleton one and it is the main class that clients would be interacting with. It has a single method called sendReq that a client use to send a request and receive a response. The client supplies an instance of EphServiceAdapter object and an instance of Request object and receives an instance of Response object.

The Program to the interface not the implementation maxim has been followed strictly here. The two parameters of sendReq and the response are all of abstract types. This is important in our desing since we want to make sure that this singleton class can keep up with future changes and will work for any type of Request, Response, and EphServiceAdapter.

The Liskov Substitution Principle (Design by Contract) has also been followed here in implementing the sendReq method. The implementation of this method looks like the following:

public Response sendReq(EphServiceAdapter serv, Request req) 
{ 
  Response res = serv.getEphemerides(req);  
  return res;
}

Hence, any concrete of Request would be substitutable here without requiring any change in our sendReq method. The same applies to EphServiceAdapter & Response, as well.

The sendReq method has also been declared final to ensure that future subclassed can't break this contract. It's also declared as synchronized to ensure it is multi-thread safe.

The Ephemeris Service Adapter Interface

This interface plays a key role in the design. The Adapter Pattern is used here to enable us to have a standard reliable interface to our client (the RequestHandler class) for accessing what are rather different services with different interfaces.

To put this in context, in the UML diagram below, the "JPL Telnet Service" is an Adaptee, the "JPLTelnetServiceAdapter" is an Adapter, the "EphServiceAdapter" is the Target Interface, while the "RequestHandler" is the client.

Again, this interface class is itself also following both the Program to the interface not the implementation and the LSP princibles.

Initial OO Design

Here is my initial design up to now. I think it is quite simple now, but this is just the beginning :) This is right now only an overview of how I imagine the api to be. I expect to actually implement The JPL's Telnet Service Adapter (or maybe the CD-ROM?) so that should also have its own design!!

Please feel free to add any comments below or any questions. Comments and ideas will be greatly appreciated.

Class Diagram- Phase 1 (2 August, 2010)

Final Design

Here is a draft version of what should be the final design. It has gone through lots and lots of iterations and refinements and is now as such I don't expect any major changes to it. A detailed write up and explanations should follow soon along with some diagrams of older versions.

Comments

 Please add your comments here!!

Questions

 Please add your questions here!!