org.jscience.ml.om
Class Observation

java.lang.Object
  extended by org.jscience.ml.om.SchemaElement
      extended by org.jscience.ml.om.Observation
All Implemented Interfaces:
IObservation, ISchemaElement

public class Observation
extends SchemaElement
implements IObservation

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
 
Fields inherited from interface org.jscience.ml.om.IObservation
XML_ELEMENT_ACCESSORIES, XML_ELEMENT_BEGIN, XML_ELEMENT_END, XML_ELEMENT_FAINTESTSTAR, XML_ELEMENT_IMAGE, XML_ELEMENT_MAGNIFICATION, XML_ELEMENT_OBSERVATION, XML_ELEMENT_SEEING
 
Fields inherited from interface org.jscience.ml.om.ISchemaElement
XML_ELEMENT_ATTRIBUTE_ID
 
Constructor Summary
Observation(java.util.Calendar begin, java.util.Calendar end, float faintestStar, int seeing, float magnification, ITarget target, IObserver observer, ISite site, IScope scope, java.lang.String accessories, IEyepiece eyepiece, IImager imager, ISession session, IFinding result)
          Constructs a new instance of an Observation.
Observation(java.util.Calendar begin, java.util.Calendar end, float faintestStar, int seeing, float magnification, ITarget target, IObserver observer, ISite site, IScope scope, java.lang.String accessories, IEyepiece eyepiece, IImager imager, ISession session, java.util.List results)
          Constructs a new instance of an Observation.
Observation(java.util.Calendar begin, java.util.Calendar end, ITarget target, IObserver observer, IFinding result)
          Constructs a new instance of an Observation.
Observation(java.util.Calendar begin, java.util.Calendar end, ITarget target, IObserver observer, java.util.List results)
          Constructs a new instance of an Observation.
Observation(java.util.Calendar begin, ITarget target, IObserver observer, IFinding result)
          Constructs a new instance of an Observation.
Observation(java.util.Calendar begin, ITarget target, IObserver observer, java.util.List results)
          Constructs a new instance of an Observation.
Observation(org.w3c.dom.Node observation, ITarget[] targets, IObserver[] observers, ISite[] sites, IScope[] scopes, ISession[] sessions, IEyepiece[] eyepieces, IImager[] imagers)
          Constructs a new Observation instance from a given XML Schema Node.
 
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 this Observation to a given parent XML DOM Element.
 boolean equals(java.lang.Object obj)
          Overwrittes equals(Object) method from java.lang.Object.
 java.lang.String getAccessories()
          Returns the accessories used for this observation.
 java.util.Calendar getBegin()
          Returns the start date of the observation.
 java.lang.String getDisplayName()
          Returns a display name for this element.
 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.
 java.lang.String toString()
          Overwrittes toString() method from java.lang.Object.
 
Methods inherited from class org.jscience.ml.om.SchemaElement
getID, setID
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.jscience.ml.om.ISchemaElement
getID
 

Constructor Detail

Observation

public Observation(org.w3c.dom.Node observation,
                   ITarget[] targets,
                   IObserver[] observers,
                   ISite[] sites,
                   IScope[] scopes,
                   ISession[] sessions,
                   IEyepiece[] eyepieces,
                   IImager[] imagers)
            throws SchemaException,
                   java.lang.IllegalArgumentException
Constructs a new Observation instance from a given XML Schema Node. Normally this constructor is only used by org.jscience.ml.om.util.SchemaLoader
Please mind: As a Observation can have multiple subelements (e.g. ,,...) that link to their implementing elements somewhere else in the xml. Because of that this constructor requires several arrays of these subelements to check whether their implementing element exists. If a Observation Node has no subelement of a specific type (cause its optional by XML Schema specification), the according array parameter can be empty or null.

Parameters:
observation - the XML Schema Node that represents this Observation object
targets - Array of ITarget that might be linked from this observation
observers - Array of IObserver that might be linked from this observation
sites - Array of ISite that might be linked from this observation
scopes - Array of IScope that might be linked from this observation (as Site is optional by XML Schema, this parameter can be NULL if passed Observation Node has no subelement)
sessions - Array of ISession that might be linked from this observation (as Session is optional by XML Schema, this parameter can be NULL if passed Observation Node has no subelement)
eyepieces - Array of IEyepiece that might be linked from this observation (as Eyepiece is optional by XML Schema, this parameter can be NULL if passed Observation Node has no subelement)
imagers - Array of IImagers that might be linked from this observation (as Imager is optional by XML Schema, this parameter can be NULL if passed Observation Node has no subelement)
Throws:
java.lang.IllegalArgumentException - if parameter observation is null or Observation Node has subelements of which no according array was passed (or the passed array was empty).
SchemaException - if the given Node does not match the XML Schema specifications

Observation

public Observation(java.util.Calendar begin,
                   ITarget target,
                   IObserver observer,
                   IFinding result)
            throws java.lang.IllegalArgumentException
Constructs a new instance of an Observation.
Simplest constructor as all parameters are mandatory.

Parameters:
begin - Start date of observation
target - The target of the observation
observer - The observer who made the observation
result - The result of this observation
Throws:
java.lang.IllegalArgumentException - if one of the parameters is null

Observation

public Observation(java.util.Calendar begin,
                   ITarget target,
                   IObserver observer,
                   java.util.List results)
            throws java.lang.IllegalArgumentException
Constructs a new instance of an Observation.

Parameters:
begin - Start date of observation
target - The target of the observation
observer - The observer who made the observation
results - The results of this observation as List
Throws:
java.lang.IllegalArgumentException - if one of the parameters is null or the result list is empty

Observation

public Observation(java.util.Calendar begin,
                   java.util.Calendar end,
                   ITarget target,
                   IObserver observer,
                   java.util.List results)
            throws java.lang.IllegalArgumentException
Constructs a new instance of an Observation.

Parameters:
begin - Start date of observation
end - End date of observation
target - The target of the observation
observer - The observer who made the observation
results - The results of this observation as List
Throws:
java.lang.IllegalArgumentException - if one of the parameters, except end date, is null, or the result list is empty

Observation

public Observation(java.util.Calendar begin,
                   java.util.Calendar end,
                   ITarget target,
                   IObserver observer,
                   IFinding result)
            throws java.lang.IllegalArgumentException
Constructs a new instance of an Observation.

Parameters:
begin - Start date of observation
end - End date of observation
target - The target of the observation
observer - The observer who made the observation
result - The result of this observation
Throws:
java.lang.IllegalArgumentException - if one of the parameters, except end date, is null

Observation

public Observation(java.util.Calendar begin,
                   java.util.Calendar end,
                   float faintestStar,
                   int seeing,
                   float magnification,
                   ITarget target,
                   IObserver observer,
                   ISite site,
                   IScope scope,
                   java.lang.String accessories,
                   IEyepiece eyepiece,
                   IImager imager,
                   ISession session,
                   IFinding result)
            throws java.lang.IllegalArgumentException
Constructs a new instance of an Observation.

Parameters:
begin - Start date of observation
end - End date of observation
faintestStar - Faintest star visible with the naked eye (in magnitude)
seeing - The seeing during observation (1=best, 5=worst)
magnification - Magnification used at the observation
target - The target of the observation
observer - The observer who made the observation
site - The place where the observation took place
scope - The scope used for this observation
eyepiece - The eyepiece used for this observation
imager - The imager used for this observation
session - The session this observation belongs to
result - The result of this observation
Throws:
java.lang.IllegalArgumentException - if one of the follwing parameters, is null: begin, target, observer, site, result or seeing is < 1 or > 5

Observation

public Observation(java.util.Calendar begin,
                   java.util.Calendar end,
                   float faintestStar,
                   int seeing,
                   float magnification,
                   ITarget target,
                   IObserver observer,
                   ISite site,
                   IScope scope,
                   java.lang.String accessories,
                   IEyepiece eyepiece,
                   IImager imager,
                   ISession session,
                   java.util.List results)
            throws java.lang.IllegalArgumentException
Constructs a new instance of an Observation.

Parameters:
begin - Start date of observation
end - End date of observation
faintestStar - Faintest star visible with the naked eye (in magnitude)
seeing - The seeing during observation (1=best, 5=worst)
magnification - Magnification used at the observation
target - The target of the observation
observer - The observer who made the observation
site - The place where the observation took place
scope - The scope used for this observation
eyepiece - The eyepiece used for this observation
imager - The imager used for this observation
session - The session this observation belongs to
results - The results of this observation as List
Throws:
java.lang.IllegalArgumentException - if one of the follwing parameters, is null: begin, target, observer, site, results or result list is empty. Also if seeing is < 1 or > 5
Method Detail

getDisplayName

public java.lang.String getDisplayName()
Returns a display name for this element.
The method differs from the toString() method as toString() shows more technical information about the element. Also the formating of toString() can spread over several lines.
This method returns a string (in one line) that can be used as displayname in e.g. a UI dropdown box.

Specified by:
getDisplayName in interface ISchemaElement
Specified by:
getDisplayName in class SchemaElement
Returns:
Returns a String with a one line display name
See Also:
java.lang.Object.toString();

toString

public java.lang.String toString()
Overwrittes toString() method from java.lang.Object.
Returns the field values of this Observation.

Overrides:
toString in class java.lang.Object
Returns:
This Observation field values
See Also:
Object

equals

public boolean equals(java.lang.Object obj)
Overwrittes equals(Object) method from java.lang.Object.
Checks if this Observation and the given Object are equal. The given object is equal with this Observation, if it derives from IObservation and if its start date, target, observer and result list is equal to this Observation.

Overrides:
equals in class java.lang.Object
Parameters:
obj - The Object to compare this Observation with.
Returns:
true if the given Object is an instance of IObservation and its start date, target, observer and result list is equal to this observation.
*
See Also:
Object

addToXmlElement

public org.w3c.dom.Element addToXmlElement(org.w3c.dom.Element parent)
Adds this Observation to a given parent XML DOM Element. The Observation element will be set as a child element of the passed element.

Specified by:
addToXmlElement in interface IObservation
Parameters:
parent - The parent element for this Observation
Returns:
Returns the element given as parameter with this Observation as child element.
* Might return null if parent was null.
See Also:
Element

getBegin

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

Specified by:
getBegin in interface IObservation
Returns:
The start date of the observation

getAccessories

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

Specified by:
getAccessories in interface IObservation
Returns:
Accessories used for this observation or null if no accessories were used

getEnd

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

Specified by:
getEnd in interface IObservation
Returns:
The end date of the observation or null if no end date was given

getEyepiece

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

Specified by:
getEyepiece in interface IObservation
Returns:
The eyepiece used for the observation or null if no eyepiece was used.

getImager

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

Specified by:
getImager in interface IObservation
Returns:
The imager used at this observation.

getMagnification

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

Specified by:
getMagnification in interface IObservation
Returns:
The magnification or Float.NaN if no value was set.

getFaintestStar

public 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.

Specified by:
getFaintestStar in interface IObservation
Returns:
The magnitude of the faintest star as float value, or Float.NaN if no value was set.

getImages

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

Specified by:
getImages in interface IObservation
Returns:
List of images or null if no images were set.

getSeeing

public 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.

Specified by:
getSeeing in interface IObservation
Returns:
A int between 1-5 representing the seeing, or -1 if no value was set for seeing.

getObserver

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

Specified by:
getObserver in interface IObservation
Returns:
The observer who made this observation.

setResult

public 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.

Specified by:
setResult in interface IObservation
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

public 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.

Specified by:
setResults in interface IObservation
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

setAccessories

public 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.

Specified by:
setAccessories in interface IObservation
Parameters:
accessories - The accessories of the observation

setImages

public 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.

Specified by:
setImages in interface IObservation
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

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

Specified by:
setImager in interface IObservation
Parameters:
imager - The imager used for this observation

addResults

public 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.

Specified by:
addResults in interface IObservation
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

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

Specified by:
addResult in interface IObservation
Parameters:
result - A new result for this observation

addImages

public 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.

Specified by:
addImages in interface IObservation
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

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

Specified by:
addImage in interface IObservation
Parameters:
imagePath - A new image for this observation

getResults

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

Specified by:
getResults in interface IObservation
Returns:
A List containing the results of the observation.

getScope

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

Specified by:
getScope in interface IObservation
Returns:
The scope which was used for the observation, or null if no scope was used at all.

getSession

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

Specified by:
getSession in interface IObservation
Returns:
The session this observation belongs to, or null if the observation does not belong to any session.

getSite

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

Specified by:
getSite in interface IObservation
Returns:
The site of the observation, or null if the observation has no site

getTarget

public ITarget getTarget()
Returns the target which was observed.

Specified by:
getTarget in interface IObservation
Returns:
The target which was observed.

setBegin

public 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.

Specified by:
setBegin in interface IObservation
Parameters:
begin - The start date of the observation
Throws:
java.lang.IllegalArgumentException - if new begin date is null

setEnd

public 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.

Specified by:
setEnd in interface IObservation
Parameters:
end - The end date of the observation

setEyepiece

public 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.

Specified by:
setEyepiece in interface IObservation
Parameters:
eyepiece - The eyepiece of the observation

setFaintestStar

public 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.

Specified by:
setFaintestStar in interface IObservation
Parameters:
faintestStar - The faintestStar of the observation in magnitude

setMagnification

public 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.

Specified by:
setMagnification in interface IObservation
Parameters:
magnification - The magnification used at the observation

setSeeing

public 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.

Specified by:
setSeeing in interface IObservation
Parameters:
seeing - A int between 1-5 representing the seeing
Throws:
java.lang.IllegalArgumentException - DOCUMENT ME!

setObserver

public 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.

Specified by:
setObserver in interface IObservation
Parameters:
observer - The observer of the observation
Throws:
java.lang.IllegalArgumentException - if new observer is null

setScope

public 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.

Specified by:
setScope in interface IObservation
Parameters:
scope - The scope of the observation

setSession

public 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.

Specified by:
setSession in interface IObservation
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

public void setSite(ISite site)
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.

Specified by:
setSite in interface IObservation
Parameters:
site - The site this observation took place

setTarget

public 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.

Specified by:
setTarget in interface IObservation
Parameters:
target - The target of this observation
Throws:
java.lang.IllegalArgumentException - if new Target is null