org.jscience.ml.om
Class Observation

java.lang.Object
  org.jscience.ml.om.SchemaElement
      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