org.jscience.ml.om
Class Scope

java.lang.Object
  extended by org.jscience.ml.om.SchemaElement
      extended by org.jscience.ml.om.Scope
All Implemented Interfaces:
IExtendableSchemaElement, ISchemaElement, IScope

public class Scope
extends SchemaElement
implements IScope

A Scope describes an optical instrument which can be used for astronomical observations.
A Scope must have an aperture and a model name, as well as either a magnification or a focalLength. (magnification should be set if the optical instrument does not allow to change eyepieces).

Since:
1.0

Field Summary
 
Fields inherited from interface org.jscience.ml.om.IScope
XML_ELEMENT_APERTURE, XML_ELEMENT_FOCALLENGTH, XML_ELEMENT_LIGHTGRASP, XML_ELEMENT_MAGNIFICATION, XML_ELEMENT_MODEL, XML_ELEMENT_ORENTATION, XML_ELEMENT_ORENTATION_ATTRIBUTE_ERECT, XML_ELEMENT_ORENTATION_ATTRIBUTE_TRUESIDED, XML_ELEMENT_SCOPE, XML_ELEMENT_TRUEFIELD, XML_ELEMENT_TYPE, XML_ELEMENT_VENDOR
 
Fields inherited from interface org.jscience.ml.om.ISchemaElement
XML_ELEMENT_ATTRIBUTE_ID
 
Fields inherited from interface org.jscience.ml.om.IExtendableSchemaElement
XML_XSI_TYPE
 
Constructor Summary
Scope(float aperture, float magnification, java.lang.String model)
          Constructs a new instance of a Scope.
Scope(org.w3c.dom.Node scope)
          Constructs a new instance of a Scope from a given XML Schmea Node.
Scope(java.lang.String model, float aperture, float focalLength)
          Constructs a new instance of a Scope.
 
Method Summary
 org.w3c.dom.Element addAsLinkToXmlElement(org.w3c.dom.Element element)
          Adds the scope link to an given XML DOM Element The scope element itself will be attached to given elements ownerDocument.
 org.w3c.dom.Element addToXmlElement(org.w3c.dom.Element element)
          Adds this Scope to a given parent XML DOM Element.
 boolean equals(java.lang.Object obj)
          Overwrittes equals(Object) method from java.lang.Object.
 float getAperture()
          Returns the aperture of the scope.
 java.lang.String getDisplayName()
          Returns a display name for this element.
 float getFocalLength()
          Returns the focal length of the scope.
 float getLightGrasp()
          Returns the light grasp value of the scope.
 float getMagnification()
          Returns the magnification of the scope.
 java.lang.String getModel()
          Returns the scopes model name.
 Angle getTrueFieldOfView()
          Returns the true field of view, if set.
 java.lang.String getType()
          Returns the scope type.
 java.lang.String getVendor()
          Returns the scope's vendor name.
 java.lang.String getXSIType()
          Returns the XML schema instance type of the implementation.
 boolean isOrientationErected()
          Returns the scopes picture vertical orientation.
 boolean isOrientationTruesided()
          Returns the scopes picture horizontal orientation.
 void setAperture(float aperture)
          Sets the aperture of the scope.
 void setFocalLength(float focalLength)
          Sets the focal length of the scope.
 boolean setLightGrasp(float lightGrasp)
          Sets the light grasp value of the scope.
 void setMagnification(float magnification)
          Sets the magnification of the scope.
 void setModel(java.lang.String model)
          Sets the model name of the scope.
 void setOrientation(boolean errected, boolean truesided)
          Sets the orientation of the scope.
 void setTrueFieldOfView(Angle tfov)
          Sets the true field of view, if magnification is given.
 void setType(java.lang.String type)
          Sets the type of the scope.
 void setVendor(java.lang.String vendor)
          Sets the vendor name of the scope.
 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

Scope

public Scope(org.w3c.dom.Node scope)
      throws SchemaException,
             java.lang.IllegalArgumentException
Constructs a new instance of a Scope from a given XML Schmea Node. Normally this constructor is only used by org.jscience.ml.om.util.SchemaLoader

Parameters:
scope - The XML Schema Node that represents this Scope Object
Throws:
java.lang.IllegalArgumentException - if the parameter is
SchemaException - if the given Node does not match the XML Schema secifications

Scope

public Scope(java.lang.String model,
             float aperture,
             float focalLength)
      throws java.lang.IllegalArgumentException
Constructs a new instance of a Scope.

Parameters:
model - The scopes model name
aperture - The aperture of the scope
focalLength - The focal length of the scope
Throws:
java.lang.IllegalArgumentException - if one of the parameters has an illegal value (see setModel(String), setAperture(float) and setFocalLength(float) for allowed values

Scope

public Scope(float aperture,
             float magnification,
             java.lang.String model)
      throws java.lang.IllegalArgumentException
Constructs a new instance of a Scope.

Parameters:
aperture - The scopes aperture
magnification - The magnification of the scope
model - The model name of the scope
Throws:
java.lang.IllegalArgumentException - if one of the parameters has an illegal value (see setModel(String), setAperture(float) and setMagnification(float) for allowed values
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();

getXSIType

public java.lang.String getXSIType()
Returns the XML schema instance type of the implementation.
Example:


Specified by:
getXSIType in interface IExtendableSchemaElement
Returns:
The xsi:type value of this implementation

toString

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

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

equals

public boolean equals(java.lang.Object obj)
Overwrittes equals(Object) method from java.lang.Object.
Checks if this Scope and the given Object are equal. The given object is equal with this Scope, if it implements the IScope interface and if model name, aperture and focalLength (or magnification) are equal to this Scopes values.

Overrides:
equals in class java.lang.Object
Parameters:
obj - The Object to compare this Scope with.
Returns:
true if the given Object is an instance of IScope and its model name, aperture and focalLength (or magnification) is equal to this Scope.
(Model name comparism is not casesensitive)
See Also:
Object

addToXmlElement

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

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

addAsLinkToXmlElement

public org.w3c.dom.Element addAsLinkToXmlElement(org.w3c.dom.Element element)
Adds the scope link to an given XML DOM Element The scope element itself will be attached to given elements ownerDocument. If the ownerDocument has no scope container, it will be created.
Example:
<parameterElement>
<scopeLink>123</scopeLink>
</parameterElement>
More stuff of the xml document goes here
<scopeContainer>
<scope id="123">
scope description goes here
</scope>
</scopeContainer>

Specified by:
addAsLinkToXmlElement in interface IScope
Parameters:
element - The element under which the the scope link is created
Returns:
Returns the Element given as parameter with a additional scope link, and the scope element under the scope container of the ownerDocument Might return null if element was null.
See Also:
Element

getAperture

public float getAperture()
Returns the aperture of the scope.
The aperture can be any positive float value.

Specified by:
getAperture in interface IScope
Returns:
Returns the aperture of the scope

getFocalLength

public float getFocalLength()
Returns the focal length of the scope.
This value might return Float.NaN in case the focal length is not set for this scope. In that case the magnification must return a value.

Specified by:
getFocalLength in interface IScope
Returns:
Returns the focal length of the scope, or Float.NaN if the value does not suit this scope

getLightGrasp

public float getLightGrasp()
Returns the light grasp value of the scope.
Allowed values are between 0.0 and 1.0 (including 0.0 and 1.0)
This value might return Float.NaN in case the light grasp was never set.

Specified by:
getLightGrasp in interface IScope
Returns:
Returns the light grasp value of the scope, or Float.NaN if the value was never set.

getTrueFieldOfView

public Angle getTrueFieldOfView()
Returns the true field of view, if set.
Might return NULL as the field is optional only if magnification is set.

Specified by:
getTrueFieldOfView in interface IScope
Returns:
Returns the true field of view of the scope, or NULL if the value was never set.

isOrientationErected

public boolean isOrientationErected()
                             throws java.lang.IllegalStateException
Returns the scopes picture vertical orientation.

Specified by:
isOrientationErected in interface IScope
Returns:
true if the scopes picture is errected
Throws:
java.lang.IllegalStateException - if orientation was not set by the user, so the class cannot return true or false

isOrientationTruesided

public boolean isOrientationTruesided()
                               throws java.lang.IllegalStateException
Returns the scopes picture horizontal orientation.

Specified by:
isOrientationTruesided in interface IScope
Returns:
true if the scopes picture is truesided
Throws:
java.lang.IllegalStateException - if orientation was not set by the user, so the class cannot return true or false

getMagnification

public float getMagnification()
Returns the magnification of the scope.
This value might return Float.NaN in case the magnification is not set for this scope. In that case the focal length must return a value.

Specified by:
getMagnification in interface IScope
Returns:
Returns the magnification of the scope, or Float.NaN if the value does not suit this scope

getModel

public java.lang.String getModel()
Returns the scopes model name.

Specified by:
getModel in interface IScope
Returns:
Returns the model name of the scope

getType

public java.lang.String getType()
Returns the scope type.
E.g. Newton, Binocular, Reflector...
If abbreviation is returned, here's the mapping: A: Naked eye
C: Cassegrain
B: Binoculars
S: Schmidt-Cassegrain
N: Newton
K: Kutter (Schiefspiegler)
R: Refractor
M: Maksutov

This method might return null if the type was never set.

Specified by:
getType in interface IScope
Returns:
Returns the scope type, or null if the type was never set.

getVendor

public java.lang.String getVendor()
Returns the scope's vendor name.
E.g. Celestron, TeleVue, Meade, Vixen...
This method might return null if the vendor was never set.

Specified by:
getVendor in interface IScope
Returns:
Returns the scope's vendor name, or null if the type was never set.

setAperture

public void setAperture(float aperture)
                 throws java.lang.IllegalArgumentException
Sets the aperture of the scope.
The aperture must be a positive float value.

Specified by:
setAperture in interface IScope
Parameters:
aperture - The new aperture of the scope
Throws:
java.lang.IllegalArgumentException - if the given aperture is smaller or equal 0.0 or if the aperture is Float.NaN

setFocalLength

public void setFocalLength(float focalLength)
                    throws java.lang.IllegalArgumentException
Sets the focal length of the scope.
Throws IllegalArgumentException if the given parameter is Float.NaN and magnification is not set. This mechanism should prevent that both values contain an invalid value at the same time. Either focal length or magnification must be set. Also if the new focal Length is smaller or equal 0.0 a IllegalArgumentException is thrown.

Specified by:
setFocalLength in interface IScope
Parameters:
focalLength - The new focal length of the scope
Throws:
java.lang.IllegalArgumentException - if the given focal length is smaller or equal 0.0 or if the new focal length is Float.NaN while magnification is also Float.NaN. Or magnification is already set.

setLightGrasp

public boolean setLightGrasp(float lightGrasp)
Sets the light grasp value of the scope.
The light grasp must be a positive float value between 0.0 and 1.0 (including 0.0 and 1.0).

Specified by:
setLightGrasp in interface IScope
Parameters:
lightGrasp - The new light grasp value of the scope
Returns:
true if new lightGrasp value could be set. If false is returned the new lightGrasp value was < 0.0 or > 1.0.

setMagnification

public void setMagnification(float magnification)
                      throws java.lang.IllegalArgumentException
Sets the magnification of the scope.
Throws IllegalArgumentException if the given parameter is Float.NaN and focal length is not set. This mechanism should prevent that both values contain an invalid value at the same time. Either focal length or magnification must be set.

Specified by:
setMagnification in interface IScope
Parameters:
magnification - The new magnification value of the scope
Throws:
java.lang.IllegalArgumentException - if the given focal length is Float.NaN while focal length is not set. Or focal length is already set.

setTrueFieldOfView

public void setTrueFieldOfView(Angle tfov)
                        throws java.lang.IllegalArgumentException
Sets the true field of view, if magnification is given.

Specified by:
setTrueFieldOfView in interface IScope
Parameters:
tfov - The true field of view of the scope
Throws:
java.lang.IllegalArgumentException - if focal length is set.

setModel

public void setModel(java.lang.String model)
              throws java.lang.IllegalArgumentException
Sets the model name of the scope.
The model name cannot be null.

Specified by:
setModel in interface IScope
Parameters:
model - The new model name of the scope
Throws:
java.lang.IllegalArgumentException - if the given model name is null

setType

public void setType(java.lang.String type)
Sets the type of the scope.
E.g. Newton, Reflector, Binocular... The type is optional but should be given if known!
When applicable, the following coding (according to the DSL) should be used:
A: Naked eye C: Cassegrain
B: Binoculars S: Schmidt-Cassegrain
N: Newton K: Kutter (Schiefspiegler)
R: Refractor M: Maksutov

Specified by:
setType in interface IScope
Parameters:
type - The new type of the scope

setVendor

public void setVendor(java.lang.String vendor)
Sets the vendor name of the scope.

Specified by:
setVendor in interface IScope
Parameters:
vendor - The new vendor name of the scope

setOrientation

public void setOrientation(boolean errected,
                           boolean truesided)
Sets the orientation of the scope.

Specified by:
setOrientation in interface IScope
Parameters:
errected - true if the scope produces errected pictures
truesided - true if the scope produces truesided pictures