edu.nrao.sss.astronomy
Class EphemerisTable

java.lang.Object
  edu.nrao.sss.astronomy.EphemerisTable

All Implemented Interfaces:

SkyPosition, SphericalPosition, Cloneable

public class EphemerisTable
extends Object

A table of position entries for an astronomical source.

Version Info:

$Revision: 1707 $

$Date: 2008-11-14 10:23:59 -0700 (Fri, 14 Nov 2008) $

$Author: dharland $

Since:

2006-06-07

Author:

David M. Harland

Constructor Summary

EphemerisTable()
Creates a new instance.

Method Summary

void	addFrom(InputStream in, String tableType) Reads data from in and adds it to this table.
void	addFrom(String fileName, String tableType) Reads data from fileName and adds it to this table.
EphemerisTable	clone() Returns a copy of this table.
static EphemerisTable	createFrom(InputStream in, String tableType) Creates a new ephemeris table and tries to load it with data from the given stream.
static EphemerisTable	createFrom(String fileName, String tableType) Creates a new ephemeris table and tries to load it with data from the given file.
boolean	equals(Object o) Returns true if o is equal to this table.
static EphemerisTable	fromXml(Reader reader) Creates a new ephemeris table based on the XML data read from reader.
static EphemerisTable	fromXml(String xmlFile) Creates a new ephemeris table from the XML data in the given file.
Angle	getAngularSeparation(SphericalPosition other) Calculates the current angular separation between this position and other.
Angle	getAngularSeparation(SphericalPosition other, Date time) Calculates current angular separation between this position and other at the given time.
CelestialCoordinateSystem	getCoordinateSystem() Returns the coordinate system to use when interpreting the latitude and longitude values of this position.
Distance	getDistance() Returns the current distance of this position.
Distance	getDistance(Date time) Returns the distance of this position at the given point in time.
Distance	getDistanceUncertainty() Returns the uncertainty in the distance of this position.
Epoch	getEpoch() Returns the epoch on which this position is based.
Latitude	getLatitude() Returns the current latitude of this position.
Latitude	getLatitude(Date time) Returns the latitude of this position at the given point in time.
Latitude	getLatitudeUncertainty() Returns the uncertainty in the latitude of this position.
Longitude	getLongitude() Returns the current longitude of this position.
Longitude	getLongitude(Date time) Returns the longitude of this position at the given point in time.
Longitude	getLongitudeUncertainty() Returns the uncertainty in the longitude of this position.
String	getOriginOfInformation() Returns the origin of this position's information.
SkyPositionType	getType() Provides a hint as to how this position stores its information.
TimeInterval	getValidTime() Returns the interval of time for which this table is valid.
LinearVelocity	getVelocity(Date time) Returns the radial velocity of this position at the given point in time.
int	hashCode() Returns a hash code value for this table.
boolean	isEmpty() Returns true if this table has no entries.
boolean	isMoving() Returns true if this position has different properties at time T than it does at time U ≠ T.
boolean	isValidFor(Date time) Returns true if this position is valid for the given point in time.
void	reset() Clears all entries from this table.
void	setCoordinateSystem(CelestialCoordinateSystem newSystem) Sets the system of latitude and longitude on which this position is based.
void	setEpoch(Epoch newEpoch) Sets the epoch on which this position is based.
void	setInterpolatorClass(Class<? extends Interpolator> interpClass) Sets the implementation of Interpolator that this table will use for calculating positional values.
void	setOriginOfInformation(String origin) Sets the origin of this position's information.
int	size() Returns the number of entries in this table.
SkyPosition	toPosition(CelestialCoordinateSystem system, Epoch epoch, EarthPosition observer, LocalSiderealTime lst) Returns a new position expressed in the given coordinate system and epoch that is equivalent to this position.
SkyPosition	toPosition(CelestialCoordinateSystem system, Epoch epoch, EarthPosition observer, LocalSiderealTime lst, CelestialCoordinateConverter converter) Returns a new position expressed in the given coordinate system and epoch that is equivalent to this position.
String	toString() Returns a text representation of this table.
String	toXml() Returns an XML representation of this ephemeris table.
void	writeAsXmlTo(Writer writer) Writes an XML representation of this ephemeris table to writer.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

EphemerisTable

public EphemerisTable()

Creates a new instance.

Method Detail

reset

public void reset()

Clears all entries from this table.

A reset table is equivalent to a new table created via the no-argument constructor. Note that this means that even the class used as an interpolator is reset by this method.

isMoving

public boolean isMoving()

Description copied from interface: SkyPosition

Returns true if this position has different properties at time T than it does at time U ≠ T.

The determination of motion will be made with respect to the coordinate system in which this position is expressed. For example, a position that is expressed in the equatorial system, and that is holding steady at its position in that system, will said to be not moving, even though in other coordinate systems it may be moving quite rapidly.

Returns:

true if this position is moving.

getValidTime

public TimeInterval getValidTime()

Returns the interval of time for which this table is valid.

Returns:

the interval of time for which this table is valid.

isValidFor

public boolean isValidFor(Date time)

Returns true if this position is valid for the given point in time.

Parameters:

time - the point in time to be checked.

getType

public SkyPositionType getType()

Description copied from interface: SkyPosition

Provides a hint as to how this position stores its information.

Returns:

a hint as to how this position stores its information.

getLongitude

public Longitude getLongitude(Date time)

Returns the longitude of this position at the given point in time.

If isValidFor(time) returns false this method will throw an IllegalArgumentException.

Parameters:

time - the point in time for which a value is requested.

Returns:

the longitude of this position at the given point in time.

Throws:

IllegalArgumentException - if param is not a valid time, as determined by isValidFor(Date).

getLatitude

public Latitude getLatitude(Date time)

Returns the latitude of this position at the given point in time.

If isValidFor(time) returns false this method will throw an IllegalArgumentException.

Parameters:

time - the point in time for which a value is requested.

Returns:

the latitude of this position at the given point in time.

Throws:

IllegalArgumentException - if param is not a valid time, as determined by isValidFor(Date).

getDistance

public Distance getDistance(Date time)

Returns the distance of this position at the given point in time.

If isValidFor(time) returns false this method will throw an IllegalArgumentException.

Parameters:

time - the point in time for which a value is requested.

Returns:

the distance of this position at the given point in time.

Throws:

IllegalArgumentException - if param is not a valid time, as determined by isValidFor(Date).

getVelocity

public LinearVelocity getVelocity(Date time)

Returns the radial velocity of this position at the given point in time.

If isValidFor(time) returns false this method will throw an IllegalArgumentException.

Parameters:

time - the point in time for which a value is requested.

Returns:

the radial velocity of this position at the given point in time.

Throws:

IllegalArgumentException - if param is not a valid time, as determined by isValidFor(Date).

addFrom

public void addFrom(String fileName,
                    String tableType)
             throws FileNotFoundException,
                    IOException

Reads data from fileName and adds it to this table.

Parameters:

fileName - the name of the file that holds the data.

tableType - the particular type of table data in the file. At the present time the only supported type is "JPL". See EphemerisTableReaderFactory.getNewReader(String) for more details.

Throws:

IllegalArgumentException - if tableType is cannot be understood.

FileNotFoundException - if no file can be found for fileName.

IOException - if anything goes wrong while reading the data.

See Also:

JplEphemerisTableReader

addFrom

public void addFrom(InputStream in,
                    String tableType)
             throws IOException,
                    IllegalArgumentException

Reads data from in and adds it to this table.

Parameters:

in - a stream that contains ephemeris data.

tableType - the particular type of table data in the stream. At the present time the only supported type is "JPL". See EphemerisTableReaderFactory.getNewReader(String) for more details.

Throws:

IllegalArgumentException - if tableType is cannot be understood.

IOException - if anything goes wrong while reading the data.

See Also:

JplEphemerisTableReader

createFrom

public static EphemerisTable createFrom(String fileName,
                                        String tableType)
                                 throws FileNotFoundException,
                                        IOException

Creates a new ephemeris table and tries to load it with data from the given file.

Parameters:

fileName - the name of a file that contains ephemeris data.

tableType - the particular type of table data in the stream. At the present time the only supported type is "JPL". See EphemerisTableReaderFactory.getNewReader(String) for more details.

Returns:

a new ephemeris table.

Throws:

IllegalArgumentException - if tableType is cannot be understood.

FileNotFoundException - if no file can be found for fileName.

IOException - if anything goes wrong while reading the data.

See Also:

addFrom(String, String)

createFrom

public static EphemerisTable createFrom(InputStream in,
                                        String tableType)
                                 throws IOException

Creates a new ephemeris table and tries to load it with data from the given stream.

Parameters:

in - a stream that contains ephemeris data.

tableType - the particular type of table data in the stream. At the present time the only supported type is "JPL". See EphemerisTableReaderFactory.getNewReader(String) for more details.

Returns:

a new ephemeris table.

Throws:

IllegalArgumentException - if tableType is cannot be understood.

IOException - if anything goes wrong while reading the data.

See Also:

addFrom(InputStream, String)

size

public int size()

Returns the number of entries in this table.

Returns:

the number of entries in this table.

isEmpty

public boolean isEmpty()

Returns true if this table has no entries.

Returns:

true if this table has no entries, false otherwise.

setInterpolatorClass

public void setInterpolatorClass(Class<? extends Interpolator> interpClass)
                          throws IllegalAccessException,
                                 InstantiationException

Sets the implementation of Interpolator that this table will use for calculating positional values.

Parameters:

interpClass - a class that implements Interpolator.

Throws:

IllegalAccessException - if this method "does not have access to the definition of the specified class" (see Sun's documentation on this exception).

InstantiationException - if "the specified class object cannot be instantiated because it is an interface or is an abstract class" (see Sun's documentation on this exception).

toString

public String toString()

Returns a text representation of this table.

The form of the returned string is:

   time1;rightAscension1;declination1;distance1;velocity1;
   time2;rightAscension2;declination2;distance2;velocity2;
   ...
   timeN;rightAscensionN;declinationN;distanceN;velocityN;

Overrides:

toString in class Object

toXml

public String toXml()
             throws JAXBException

Returns an XML representation of this ephemeris table.

Returns:

an XML representation of this ephemeris table.

Throws:

JAXBException - if anything goes wrong during the conversion to XML.

writeAsXmlTo

public void writeAsXmlTo(Writer writer)
                  throws JAXBException

Writes an XML representation of this ephemeris table to writer.

Parameters:

writer - the device to which XML is written.

Throws:

JAXBException - if anything goes wrong during the conversion to XML.

fromXml

public static EphemerisTable fromXml(String xmlFile)
                              throws JAXBException,
                                     XMLStreamException,
                                     FileNotFoundException

Creates a new ephemeris table from the XML data in the given file.

Parameters:

xmlFile - the name of an XML file. This method will attempt to locate the file by using Class.getResource(String).

Returns:

a new ephemeris table from the XML data in the given file.

Throws:

FileNotFoundException - if the XML file cannot be found.

JAXBException - if the schema file used (if any) is malformed, if the XML file cannot be read, or if the XML file is not schema-valid.

XMLStreamException - if there is a problem opening the XML file, if the XML is not well-formed, or for some other "unexpected processing conditions".

fromXml

public static EphemerisTable fromXml(Reader reader)
                              throws JAXBException,
                                     XMLStreamException

Creates a new ephemeris table based on the XML data read from reader.

Parameters:

reader - the source of the XML data. If this value is null, null is returned.

Returns:

a new ephemeris table based on the XML data read from reader.

Throws:

XMLStreamException - if the XML is not well-formed, or for some other "unexpected processing conditions".

JAXBException - if anything else goes wrong during the transformation.

clone

public EphemerisTable clone()

Returns a copy of this table.

If anything goes wrong during the cloning procedure, a RuntimeException will be thrown.

Specified by:

clone in interface SkyPosition

Specified by:

clone in interface SphericalPosition

Returns:

a copy of this sky position.

equals

public boolean equals(Object o)

Returns true if o is equal to this table.

hashCode

public int hashCode()

Returns a hash code value for this table.

setCoordinateSystem

public void setCoordinateSystem(CelestialCoordinateSystem newSystem)

Sets the system of latitude and longitude on which this position is based. If newSystem is null, this method does nothing.

Parameters:

newSystem - the system of latitude and longitude on which this position is based.

getCoordinateSystem

public CelestialCoordinateSystem getCoordinateSystem()

Description copied from interface: SkyPosition

Returns the coordinate system to use when interpreting the latitude and longitude values of this position.

Specified by:

getCoordinateSystem in interface SkyPosition

Returns:

the system of latitude and longitude used by this position.

setEpoch

public void setEpoch(Epoch newEpoch)

Sets the epoch on which this position is based. If newEpoch is null, this method does nothing.

Parameters:

newEpoch - the epoch on which this position is based.

getEpoch

public Epoch getEpoch()

Description copied from interface: SkyPosition

Returns the epoch on which this position is based.

Specified by:

getEpoch in interface SkyPosition

Returns:

the epoch on which this position is based.

setOriginOfInformation

public void setOriginOfInformation(String origin)

Sets the origin of this position's information.

Parameters:

origin - the origin of this position's information. A value of null will be replaced by a non-null default value.

getOriginOfInformation

public String getOriginOfInformation()

Description copied from interface: SkyPosition

Returns the origin of this position's information.

Specified by:

getOriginOfInformation in interface SkyPosition

Returns:

the origin of this position's information.

getLongitude

public Longitude getLongitude()

Returns the current longitude of this position.

This is convenience method equivalent to getLongitude(new Date()). As such, whether or not the returned longitude is a reference to an internally held object depends upon the behavior of getLongitude(Date).

Specified by:

getLongitude in interface SphericalPosition

Returns:

the current longitude of this position.

getLatitude

public Latitude getLatitude()

Returns the current latitude of this position.

This is convenience method equivalent to getLatitude(new Date()). As such, whether or not the returned latitude is a reference to an internally held object depends upon the behavior of getLatitude(Date).

Specified by:

getLatitude in interface SphericalPosition

Returns:

the current latitude of this position.

getDistance

public Distance getDistance()

Returns the current distance of this position.

This is convenience method equivalent to getDistance(new Date()). As such, whether or not the returned distance is a reference to an internally held object depends upon the behavior of getDistance(Date).

Specified by:

getDistance in interface SphericalPosition

Returns:

the current distance of this position.

getLatitudeUncertainty

public Latitude getLatitudeUncertainty()

Returns the uncertainty in the latitude of this position. This value is guaranteed to be non-null.

Note that the object returned is not held internally by this position. This means that any changes made to the returned object by clients will not be reflected in this position.

Specified by:

getLatitudeUncertainty in interface SphericalPosition

Returns:

the uncertainty in the latitude of this position.

getLongitudeUncertainty

public Longitude getLongitudeUncertainty()

Returns the uncertainty in the longitude of this position. This value is guaranteed to be non-null.

Note that the object returned is not held internally by this position. This means that any changes made to the returned object by clients will not be reflected in this position.

Specified by:

getLongitudeUncertainty in interface SphericalPosition

Returns:

the uncertainty in the longitude of this position.

getDistanceUncertainty

public Distance getDistanceUncertainty()

Returns the uncertainty in the distance of this position. This value is guaranteed to be non-null.

Note that the object returned is not held internally by this position. This means that any changes made to the returned object by clients will not be reflected in this position.

Specified by:

getDistanceUncertainty in interface SphericalPosition

Returns:

the uncertainty in the distance of this position.

toPosition

public SkyPosition toPosition(CelestialCoordinateSystem system,
                              Epoch epoch,
                              EarthPosition observer,
                              LocalSiderealTime lst)
                       throws CoordinateConversionException

Description copied from interface: SkyPosition

Returns a new position expressed in the given coordinate system and epoch that is equivalent to this position. This position is not changed by this method.

Specified by:

toPosition in interface SkyPosition

Parameters:

system - the celestial coordinate system of the returned position.

epoch - the epoch of the returned position.

observer - the location of the observer. This value is used almost exclusively for conversions to or from the HORIZONTAL (az/el) coordinate system. If a given conversion does not require this parameter, a null value will do no harm.

lst - the local sidereal time at the observer's location. This parameter serves two purposes. First, it is integral in conversions to or from the HORIZONTAL (az/el) coordinate system. Second, even for conversions that do not depend on the observer's location, the conversion method will use the UTC time represented by this LST to determine the exact location of this position before converting it to another system. When used this way the location associated with the LST is immaterial. If this value is null it will be replaced with the current time. Using a null value is not recommended when dealing with the HORIZONTAL system because the LST may not be for the location of interest.

Returns:

a new position with a coordinate system of system, and epoch of epoch, and coordinates that represent a conversion from those of this position.

Throws:

CoordinateConversionException - if anything goes wrong with the conversion.

toPosition

public SkyPosition toPosition(CelestialCoordinateSystem system,
                              Epoch epoch,
                              EarthPosition observer,
                              LocalSiderealTime lst,
                              CelestialCoordinateConverter converter)
                       throws CoordinateConversionException

Description copied from interface: SkyPosition

Returns a new position expressed in the given coordinate system and epoch that is equivalent to this position. This position is not changed by this method.

Specified by:

toPosition in interface SkyPosition

Parameters:

system - the celestial coordinate system of the returned position.

epoch - the epoch of the returned position.

observer - the location of the observer. This value is used almost exclusively for conversions to or from the HORIZONTAL (az/el) coordinate system.

lst - the local sidereal time at the observer's location. This parameter serves two purposes. First, it is integral in conversions to or from the HORIZONTAL (az/el) coordinate system. Second, even for conversions that do not depend on the observer's location, the conversion method will use the UTC time represented by this LST to determine the exact location of this position before converting it to another system. When used this way the location associated with the LST is immaterial. If this value is null it will be replaced with the current time. Using a null value is not recommended when dealing with the HORIZONTAL system because the LST may not be for the location of interest.

converter - the converter used to perform the transformation.

Returns:

a new position with a coordinate system of system, and epoch of epoch, and coordinates that represent a conversion from those of this position.

Throws:

CoordinateConversionException - if anything goes wrong with the conversion.

getAngularSeparation

public Angle getAngularSeparation(SphericalPosition other)

Description copied from interface: SphericalPosition

Calculates the current angular separation between this position and other.

The distances of the positions from the center of the sphere are not considered. The returned angle is the smallest possible such angle. It is the angular size of the arc of a great circle that passes through both the ray from the orgin to this position and the ray from the origin to other.

The returned value is never negative. This means that the returned angle does not contain directional information. That is, the angle from A to B is exactly equal to the angle from B to A.

Specified by:

getAngularSeparation in interface SphericalPosition

Parameters:

other - a position from which this one is separated by the returned angle.

Returns:

the angle of separation between this position and other.

getAngularSeparation

public Angle getAngularSeparation(SphericalPosition other,
                                  Date time)

Description copied from interface: SkyPosition

Calculates current angular separation between this position and other at the given time.

The distances of the positions from the center of the sphere are not considered. The returned angle is the smallest possible such angle. It is the angular size of the arc of a great circle that passes through both the ray from the orgin to this position and the ray from the origin to other.

The returned value is never negative. This means that the returned angle does not contain directional information. That is, the angle from A to B is exactly equal to the angle from B to A.

Specified by:

getAngularSeparation in interface SkyPosition

Parameters:

other - a position from which this one is separated by the returned angle.

time - the point in time for which the separation is sought.

Returns:

the angle of separation between this position and other.