org.jscience.ml.om
Interface IObservation

All Superinterfaces:
ISchemaElement
All Known Implementing Classes:
Observation

public interface IObservation
extends ISchemaElement

An IObservation describes an astronomical oberservation of exactly one celestial object (target).
The observation must have one start date to be correct, but does not have to have an end date (as the end date might be lost in older observations).
Inside the XML Schema the Observation is the central entry point for accessing all other kinds of data. (See: XML Schema Doc) Therefore the IObservation provides access to almost all other XML Schema elements.

Since:
1.0

Field Summary
static java.lang.String XML_ELEMENT_ACCESSORIES
          Constant for XML representation: RootElement accessories (filters, ...).
static java.lang.String XML_ELEMENT_BEGIN
          Constant for XML representation: RootElement begin date element name.
static java.lang.String XML_ELEMENT_END
          Constant for XML representation: RootElement end date element name.
static java.lang.String XML_ELEMENT_FAINTESTSTAR
          Constant for XML representation: RootElement faintest star element name.
static java.lang.String XML_ELEMENT_IMAGE
          Constant for XML representation: Image made during observation.
static java.lang.String XML_ELEMENT_MAGNIFICATION
          Constant for XML representation: RootElement magnification.
static java.lang.String XML_ELEMENT_OBSERVATION
          Constant for XML representation: IObservation element name.
static java.lang.String XML_ELEMENT_SEEING
          Constant for XML representation: RootElement seeing.
 
Fields inherited from interface org.jscience.ml.om.ISchemaElement
XML_ELEMENT_ATTRIBUTE_ID
 
Method Summary
 void addImage(java.lang.String imagePath)
          Adds a new image (path) to this observation.
 boolean addImages(java.util.List images)
          Adds a List of image paths (String) to this observation.
 void addResult(IFinding result)
          Adds a new result to this observation.
 boolean addResults(java.util.List results)
          Adds a List of results for this observation.
 org.w3c.dom.Element addToXmlElement(org.w3c.dom.Element parent)
          Adds the IObservation implementation to an given parent XML DOM Element.
 java.lang.String getAccessories()
          Returns the accessories used for this observation.
 java.util.Calendar getBegin()
          Returns the start date of the observation.
 java.util.Calendar getEnd()
          Returns the end date of the observation.
 IEyepiece getEyepiece()
          Returns the eyepiece with which the observation was made.
 float getFaintestStar()
          Returns the magnitude of the faintest star that could be seen during observation time with the unaided eye.
 IImager getImager()
          Returns the imager that was used for this observation.
 java.util.List getImages()
          Returns a list of images (relativ path to images), taken at this observation.
 float getMagnification()
          Returns the magnification used for this observation.
 IObserver getObserver()
          Returns the observer who made the observation.
 java.util.List getResults()
          Returns a List with one or more results of the observation.
 IScope getScope()
          Returns the scope that was used for the observation.
 int getSeeing()
          Returns the seeing during this observation.
 ISession getSession()
          Returns the session this observation belongs to.
 ISite getSite()
          Returns the site where the observation took place.
 ITarget getTarget()
          Returns the target which was observed.
 void setAccessories(java.lang.String accessories)
          Sets the accessories used during the observation.
 void setBegin(java.util.Calendar begin)
          Sets the start date of the observation.
 void setEnd(java.util.Calendar end)
          Sets the end date of the observation.
 void setEyepiece(IEyepiece eyepiece)
          Sets the eyepiece of the observation.
 void setFaintestStar(float faintestStar)
          Sets the magnitude value of the faintest star which could be seen with the unaided eye during the observation.
 void setImager(IImager imager)
          Sets an imager used for this observation.
 boolean setImages(java.util.List imagesList)
          Sets a List of images (path as String) for this observation.
 void setMagnification(float magnification)
          Sets the magnification used at the observation.
 void setObserver(IObserver observer)
          Sets the observer of the observation.
 boolean setResult(IFinding result)
          Sets a single IFinding as result for this observation.
 boolean setResults(java.util.List results)
          Sets a List of results for this observation.
 void setScope(IScope scope)
          Sets the scope of the observation.
 void setSeeing(int seeing)
          Sets the seeing during this observation.
 void setSession(ISession session)
          Sets the session which this observation belongs to.
 void setSite(ISite site)
          Sets the site where this observation took place.
 void setTarget(ITarget target)
          Sets the target of this observation.
 
Methods inherited from interface org.jscience.ml.om.ISchemaElement
getDisplayName, getID
 

Field Detail

XML_ELEMENT_OBSERVATION

static final java.lang.String XML_ELEMENT_OBSERVATION
Constant for XML representation: IObservation element name.
Example:
<observation>More stuff goes here</observation>

See Also:
Constant Field Values

XML_ELEMENT_BEGIN

static final java.lang.String XML_ELEMENT_BEGIN
Constant for XML representation: RootElement begin date element name.
Example:
<observation>
More stuff goes here <begin>Start date and time of observation</begin> More stuff goes here </observation>

See Also:
Constant Field Values

XML_ELEMENT_ACCESSORIES

static final java.lang.String XML_ELEMENT_ACCESSORIES
Constant for XML representation: RootElement accessories (filters, ...).
Example:
<observation>
More stuff goes here <accessories>Some accessories</accessories> More stuff goes here </observation>

See Also:
Constant Field Values

XML_ELEMENT_END

static final java.lang.String XML_ELEMENT_END
Constant for XML representation: RootElement end date element name.
Example:
<observation>
More stuff goes here <end>End date and time of observation</end> More stuff goes here </observation>

See Also:
Constant Field Values

XML_ELEMENT_FAINTESTSTAR

static final java.lang.String XML_ELEMENT_FAINTESTSTAR
Constant for XML representation: RootElement faintest star element name.
Example:
<observation>
More stuff goes here <faintestStar>Magnitude of faintest star</faintestStar> More stuff goes here </observation>

See Also:
Constant Field Values

XML_ELEMENT_SEEING

static final java.lang.String XML_ELEMENT_SEEING
Constant for XML representation: RootElement seeing.
Allowed values 1,2,3,4,5 .
Example:
<observation>
More stuff goes here <seeingType>Seeing during observation</seeingType> More stuff goes here </observation>

See Also:
Constant Field Values

XML_ELEMENT_MAGNIFICATION

static final java.lang.String XML_ELEMENT_MAGNIFICATION
Constant for XML representation: RootElement magnification.
Example:
<observation>
More stuff goes here <magnification>Magnification used for observation</magnification> More stuff goes here </observation>

See Also:
Constant Field Values

XML_ELEMENT_IMAGE

static final java.lang.String XML_ELEMENT_IMAGE
Constant for XML representation: Image made during observation.
Example:
<observation>
More stuff goes here <image>Relative path to image</image> More stuff goes here </observation>

See Also:
Constant Field Values
Method Detail

addToXmlElement

org.w3c.dom.Element addToXmlElement(org.w3c.dom.Element parent)
Adds the IObservation implementation to an given parent XML DOM Element. The observation Element will be set as a child element of the passed element.
Example:
<parentElement>
<observation>
More stuff goes here
</observation>
</parentElement>

Parameters:
parent - The parent element for the IObservation implementation
Returns:
Returns the Element given as parameter with the IObservation implementation as child element.
See Also:
Element

getBegin

java.util.Calendar getBegin()
Returns the start date of the observation.

Returns:
The start date of the observation

getEnd

java.util.Calendar getEnd()
Returns the end date of the observation.
Might return null if no end date was given.

Returns:
The end date of the observation or null if no end date was given

getAccessories

java.lang.String getAccessories()
Returns the accessories used for this observation.
Might return null if no accessories have been used.

Returns:
Accessories used for this observation or null if no accessories were used

getEyepiece

IEyepiece getEyepiece()
Returns the eyepiece with which the observation was made.
Might return null if no eyepiece was used at all.

Returns:
The eyepiece used for the observation or null if no eyepiece was used.

getFaintestStar

float getFaintestStar()
Returns the magnitude of the faintest star that could be seen during observation time with the unaided eye. Might return Float.NaN if no value was set at all.

Returns:
The magnitude of the faintest star as float value, or Float.NaN if no value was set.

getMagnification

float getMagnification()
Returns the magnification used for this observation. Might return Float.NaN if no value was set at all.

Returns:
The magnification or Float.NaN if no value was set.

getImages

java.util.List getImages()
Returns a list of images (relativ path to images), taken at this observation. Might return null if images were set.

Returns:
List of images or null if no images were set.

getSeeing

int getSeeing()
Returns the seeing during this observation.
Values can reach from 1 to 5, where 1 is best seeing and 5 the worst seeing.
Might return -1 if no value was set at all.

Returns:
A int between 1-5 representing the seeing, or -1 if no value was set for seeing.

getObserver

IObserver getObserver()
Returns the observer who made the observation.

Returns:
The observer who made this observation.

getResults

java.util.List getResults()
Returns a List with one or more results of the observation.
Every observation has at least one result.

Returns:
A List containing the results of the observation.

getScope

IScope getScope()
Returns the scope that was used for the observation.
Might return null if the observation was not made with any scope.

Returns:
The scope which was used for the observation, or null if no scope was used at all.

getSession

ISession getSession()
Returns the session this observation belongs to.
Might return null if the observation is not part of any observation session.

Returns:
The session this observation belongs to, or null if the observation does not belong to any session.

getSite

ISite getSite()
Returns the site where the observation took place.

Returns:
The site of the observation.

getTarget

ITarget getTarget()
Returns the target which was observed.

Returns:
The target which was observed.

getImager

IImager getImager()
Returns the imager that was used for this observation.

Returns:
The imager used at this observation.

setResult

boolean setResult(IFinding result)
                  throws java.lang.IllegalArgumentException
Sets a single IFinding as result for this observation.
The old list of results will be overwritten. If you want to add one ore more results to the existing ones use addResults(java.util.List) or addResult(IFinding).
If the passed IFinding was successfully attached to this observation, the method will return true.
If the passed IFinding is null, an IllegalArgumentException is thrown.

Parameters:
result - A new result for this observation
Returns:
true if the given result was successfully attached to this observation, while the old result list was deleted.
Throws:
java.lang.IllegalArgumentException - if the new result is null
See Also:
org.jscience.ml.om.IObservation#addResults(java.util.Listresults), org.jscience.ml.om.IObservation#addResult(IFindingresult), org.jscience.ml.om.IObservation#setResults(Listresults), IFinding

setResults

boolean setResults(java.util.List results)
                   throws java.lang.IllegalArgumentException
Sets a List of results for this observation.
The old list of results will be overwritten. If you want to add one ore more results to the existing ones use addResults(java.util.List) or addResult(IFinding).
If the new list of results was successfully attached to this observation, the method will return true. If one of the elements in the list does not implement the IFinding interface false is returned.
If the new list is empty or null, an IllegalArgumentException is thrown.

Parameters:
results - The new list of results for this observation
Returns:
true if the given list was successfully attached to this observation. false if one of the new result elements in the list did not implement the the IFinding interface.
Throws:
java.lang.IllegalArgumentException - if new results list is null or empty
See Also:
org.jscience.ml.om.IObservation#addResults(java.util.Listresults), org.jscience.ml.om.IObservation#addResult(IFindingresult), IFinding

addResults

boolean addResults(java.util.List results)
Adds a List of results for this observation.
The new list of results will be added to the existing list of results belonging to this observation. If you want to replace the old result list use setResults(java.util.List).
If the new list of results was successfully added to the old result list, the method will return true. If the list is empty or null, the old result list will remain unchanged.

Parameters:
results - A list with more results for this observation
Returns:
true if the given list was successfully added to this observations result list. false if the new list could not be added and the old list remains unchanged.
See Also:
org.jscience.ml.om.IObservation#setResults(java.util.Listresults)

addResult

void addResult(IFinding result)
Adds a new result to this observation.

Parameters:
result - A new result for this observation

addImages

boolean addImages(java.util.List images)
Adds a List of image paths (String) to this observation.
The new list of images will be added to the existing list of images belonging to this observation. If you want to replace the old images list use setImages(java.util.List).
If the new list of images was successfully added to the old images list, the method will return true. If the list is empty or null, the old result list will remain unchanged.

Parameters:
images - A list (containing Strings) with additional images (path) for this observation
Returns:
true if the given list was successfully added to this observations images list. false if the new list could not be added and the old list remains unchanged.
See Also:
org.jscience.ml.om.IObservation#setResults(java.util.Listimages)

addImage

void addImage(java.lang.String imagePath)
Adds a new image (path) to this observation.

Parameters:
imagePath - A new image for this observation

setImages

boolean setImages(java.util.List imagesList)
                  throws java.lang.IllegalArgumentException
Sets a List of images (path as String) for this observation.
The old list of images will be overwritten. If you want to add one ore more images to the existing ones use addImages(java.util.List) or addImage(String).
If the new list of images was successfully attached to this observation, the method will return true. If one of the elements in the list isn't a java.lang.String object false is returned.
If the new list is empty or null, an IllegalArgumentException is thrown.

Parameters:
imagesList - The new (String) list of images for this observation
Returns:
true if the given list was successfully set to this observation. false if one of the lists elements wasn't a String
Throws:
java.lang.IllegalArgumentException - if new image list is null or empty
See Also:
org.jscience.ml.om.IObservation#addImages(java.util.Listimages), org.jscience.ml.om.IObservation#addImage(Stringimage)

setImager

void setImager(IImager imager)
Sets an imager used for this observation.

Parameters:
imager - The imager used for this observation

setBegin

void setBegin(java.util.Calendar begin)
              throws java.lang.IllegalArgumentException
Sets the start date of the observation.
The start date is a mandatory field, as the end date is not.

Parameters:
begin - The start date of the observation
Throws:
java.lang.IllegalArgumentException - if new begin date is null

setEnd

void setEnd(java.util.Calendar end)
Sets the end date of the observation.
The end date is an optional field, as for example old observations might not have an precise end date.

Parameters:
end - The end date of the observation

setEyepiece

void setEyepiece(IEyepiece eyepiece)
Sets the eyepiece of the observation.
If there was already an eyepiece attached to this observation, the old one will be replaced with the new one.

Parameters:
eyepiece - The eyepiece of the observation

setAccessories

void setAccessories(java.lang.String accessories)
Sets the accessories used during the observation.
If there was already an accessories list attached to this observation, the old one will be replaced with the new one.

Parameters:
accessories - The accessories of the observation

setFaintestStar

void setFaintestStar(float faintestStar)
Sets the magnitude value of the faintest star which could be seen with the unaided eye during the observation.
If there was already a value set for this observation, the old one will be replaced with the new one.

Parameters:
faintestStar - The faintestStar of the observation in magnitude

setMagnification

void setMagnification(float magnification)
Sets the magnification used at the observation.
If there was already a value set for this observation, the old one will be replaced with the new one.

Parameters:
magnification - The magnification used at the observation

setSeeing

void setSeeing(int seeing)
               throws java.lang.IllegalArgumentException
Sets the seeing during this observation.
Values can reach from 1 to 5, where 1 is best seeing and 5 the worst seeing.

Parameters:
seeing - A int between 1-5 representing the seeing
Throws:
java.lang.IllegalArgumentException - DOCUMENT ME!

setObserver

void setObserver(IObserver observer)
                 throws java.lang.IllegalArgumentException
Sets the observer of the observation.
If there was already an observer attached to this observation, the old one will be replaced with the new one.

Parameters:
observer - The observer of the observation
Throws:
java.lang.IllegalArgumentException - if new observer is null

setScope

void setScope(IScope scope)
Sets the scope of the observation.
If there was already a scope attached to this observation, the old one will be replaced with the new one.

Parameters:
scope - The scope of the observation

setSession

void setSession(ISession session)
                throws java.lang.IllegalArgumentException
Sets the session which this observation belongs to.
This observations start date must be between the sessions start and end date.
If there was already a session attached to this observation, the old one will be replaced with the new one.

Parameters:
session - The session this observation belongs to
Throws:
java.lang.IllegalArgumentException - if this observations start date is not between the session start and end date

setSite

void setSite(ISite site)
             throws java.lang.IllegalArgumentException
Sets the site where this observation took place.
If there was already a site attached to this observation, the old one will be replaced with the new one.

Parameters:
site - The site this observation took place
Throws:
java.lang.IllegalArgumentException - if new site is null

setTarget

void setTarget(ITarget target)
               throws java.lang.IllegalArgumentException
Sets the target of this observation.
If there was already a target attached to this observation, the old one will be replaced with the new one.

Parameters:
target - The target of this observation
Throws:
java.lang.IllegalArgumentException - if new target is null