org.jscience.ml.om
Interface IScope

All Superinterfaces:
IExtendableSchemaElement, ISchemaElement
All Known Implementing Classes:
Scope

public interface IScope
extends ISchemaElement, IExtendableSchemaElement

An IScope describes an optical instrument which can be used for astronomical observations.
An IScope 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
static java.lang.String XML_ELEMENT_APERTURE
          Constant for XML representation: Scopes aperture element name.
static java.lang.String XML_ELEMENT_FOCALLENGTH
          Constant for XML representation: Scopes focalLength element name.
static java.lang.String XML_ELEMENT_LIGHTGRASP
          Constant for XML representation: Scopes lightGrasp element name.
static java.lang.String XML_ELEMENT_MAGNIFICATION
          Constant for XML representation: Scopes magnification element name.
static java.lang.String XML_ELEMENT_MODEL
          Constant for XML representation: Scopes model element name.
static java.lang.String XML_ELEMENT_ORENTATION
          Constant for XML representation: Orientation of scope.
static java.lang.String XML_ELEMENT_ORENTATION_ATTRIBUTE_ERECT
          Constant for XML representation: Orientation attribute erect.
static java.lang.String XML_ELEMENT_ORENTATION_ATTRIBUTE_TRUESIDED
          Constant for XML representation: Orientation attribute truesided.
static java.lang.String XML_ELEMENT_SCOPE
          Constant for XML representation: IScope element name.
static java.lang.String XML_ELEMENT_TRUEFIELD
          Constant for XML representation: If magnification is given, the true field of view can be passed additionally.
static java.lang.String XML_ELEMENT_TYPE
          Constant for XML representation: Scopes type element name.
static java.lang.String XML_ELEMENT_VENDOR
          Constant for XML representation: Scopes vendor element name.
 
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
 
Method Summary
 org.w3c.dom.Element addAsLinkToXmlElement(org.w3c.dom.Element parent)
          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.
 float getAperture()
          Returns the aperture of the scope.
 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.
 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.
 
Methods inherited from interface org.jscience.ml.om.ISchemaElement
getDisplayName, getID
 
Methods inherited from interface org.jscience.ml.om.IExtendableSchemaElement
getXSIType
 

Field Detail

XML_ELEMENT_SCOPE

static final java.lang.String XML_ELEMENT_SCOPE
Constant for XML representation: IScope element name.
Example:
<scope>More stuff goes here</scope>

See Also:
Constant Field Values

XML_ELEMENT_MODEL

static final java.lang.String XML_ELEMENT_MODEL
Constant for XML representation: Scopes model element name.
Example:
<scope>
More stuff goes here <model>Scopes model name goes here</model> More stuff goes here </scope>

See Also:
Constant Field Values

XML_ELEMENT_TYPE

static final java.lang.String XML_ELEMENT_TYPE
Constant for XML representation: Scopes type element name.
Example:
<scope>
More stuff goes here <type>Scopes type goes here</type> More stuff goes here </scope>

See Also:
Constant Field Values

XML_ELEMENT_VENDOR

static final java.lang.String XML_ELEMENT_VENDOR
Constant for XML representation: Scopes vendor element name.
Example:
<scope>
More stuff goes here <vendor>Scopes vendor goes here</vendor> More stuff goes here </scope>

See Also:
Constant Field Values

XML_ELEMENT_APERTURE

static final java.lang.String XML_ELEMENT_APERTURE
Constant for XML representation: Scopes aperture element name.
Example:
<scope>
More stuff goes here <aperture>Scopes aperture goes here</aperture> More stuff goes here </scope>

See Also:
Constant Field Values

XML_ELEMENT_FOCALLENGTH

static final java.lang.String XML_ELEMENT_FOCALLENGTH
Constant for XML representation: Scopes focalLength element name.
Example:
<scope>
More stuff goes here <focalLength>Scopes focalLength goes here</focalLength> More stuff goes here </scope>

See Also:
Constant Field Values

XML_ELEMENT_MAGNIFICATION

static final java.lang.String XML_ELEMENT_MAGNIFICATION
Constant for XML representation: Scopes magnification element name.
Example:
<scope>
More stuff goes here <magnification>Scopes magnification goes here</magnification> More stuff goes here </scope>

See Also:
Constant Field Values

XML_ELEMENT_LIGHTGRASP

static final java.lang.String XML_ELEMENT_LIGHTGRASP
Constant for XML representation: Scopes lightGrasp element name.
Example:
<scope>
More stuff goes here <lightGrasp>Scopes lightGrasp goes here</lightGrasp> More stuff goes here </scope>

See Also:
Constant Field Values

XML_ELEMENT_ORENTATION

static final java.lang.String XML_ELEMENT_ORENTATION
Constant for XML representation: Orientation of scope.
Example:
<scope>
More stuff goes here <orientation erect=true truesided=true /> More stuff goes here </scope>

See Also:
Constant Field Values

XML_ELEMENT_ORENTATION_ATTRIBUTE_ERECT

static final java.lang.String XML_ELEMENT_ORENTATION_ATTRIBUTE_ERECT
Constant for XML representation: Orientation attribute erect.
Example:
<scope>
More stuff goes here <orientation erect=true truesided=true /> More stuff goes here </scope>

See Also:
Constant Field Values

XML_ELEMENT_ORENTATION_ATTRIBUTE_TRUESIDED

static final java.lang.String XML_ELEMENT_ORENTATION_ATTRIBUTE_TRUESIDED
Constant for XML representation: Orientation attribute truesided.
Example:
<scope>
More stuff goes here <orientation erect=true truesided=true /> More stuff goes here </scope>

See Also:
Constant Field Values

XML_ELEMENT_TRUEFIELD

static final java.lang.String XML_ELEMENT_TRUEFIELD
Constant for XML representation: If magnification is given, the true field of view can be passed additionally.
Example:
<scope>
More stuff goes here <magnification>Scopes magnification goes here</magnification> <trueField>True field of view goes here</trueField> More stuff goes here </scope>

See Also:
Constant Field Values
Method Detail

addToXmlElement

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.

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

org.w3c.dom.Element addAsLinkToXmlElement(org.w3c.dom.Element parent)
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>

Parameters:
parent - 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

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

Returns:
Returns the aperture of the scope

getFocalLength

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.

Returns:
Returns the focal length of the scope, or Float.NaN if the value does not suit this scope

getLightGrasp

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.

Returns:
Returns the light grasp value of the scope, or Float.NaN if the value was never set.

getMagnification

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.

Returns:
Returns the magnification of the scope, or Float.NaN if the value does not suit this scope

getModel

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

Returns:
Returns the model name of the scope

getType

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.

Returns:
Returns the scope type, or null if the type was never set.

getTrueFieldOfView

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

Returns:
Returns the true field of view of the scope, or NULL if the value was never set.

getVendor

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.

Returns:
Returns the scope's vendor name, or null if the type was never set.

isOrientationErected

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

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

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

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

setTrueFieldOfView

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

Parameters:
tfov - The true field of view of the scope
Throws:
java.lang.IllegalArgumentException - if focal length is set.

setAperture

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

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

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.

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

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

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

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.

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.

setModel

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

Parameters:
model - The new model name of the scope
Throws:
java.lang.IllegalArgumentException - if the given model name is null

setType

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

Parameters:
type - The new type of the scope

setVendor

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

Parameters:
vendor - The new vendor name of the scope

setOrientation

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

Parameters:
errected - true if the scope produces errected pictures
truesided - true if the scope produces truesided pictures