org.geotools.image.io.metadata
Class MetadataAccessor

java.lang.Object
  extended by org.geotools.image.io.metadata.MetadataAccessor
Direct Known Subclasses:
Axis, Band, ImageGeometry, ImageReferencing, Parameter

public class MetadataAccessor
extends java.lang.Object

Base class for geographic metadata parsers. This class provides convenience methods for encoding and decoding metadata information. A metadata root node is specified at construction time, together with a path to the element of interest. Example of valid paths:

In addition, some elements contains an arbitrary amount of childs. The path to child elements can also be specified to the constructor. Examples (note that the constructor expects paths relative to the parent; we show absolute paths below for completness):

The get and set methods defined in this class will operate on the selected element, which may be either the one specified at construction time, or one of its childs. The element can be selected by selectParent() (the default) or selectChild(int).

The example below creates an accessor for a node called "CoordinateSystem" which is expected to have childs called "Axis":

 MetadataAccessor accessor = new MetadataAccessor(metadata,
         "CoordinateReferenceSystem/CoordinateSystem", "Axis");

 accessor.selectParent();
 String csName = accessor.getAttributeAsString("name");

 accessor.selectChild(0);
 String firstAxisName = accessor.getAttributeAsString("name");
 

Since:
2.4
Version:
$Id: MetadataAccessor.java 30965 2008-07-09 10:04:21Z cedricbr $
Author:
Martin Desruisseaux, Cédric Briançon

Constructor Summary
protected MetadataAccessor(GeographicMetadata metadata, java.lang.String parentPath, java.lang.String childPath)
          Creates an accessor for the element at the given path.
protected MetadataAccessor(MetadataAccessor clone)
          Creates an accessor with the same parent and childs than the specified one.
 
Method Summary
protected  int appendChild()
          Adds a new child element at the path given at construction time.
protected  int childCount()
          Returns the number of child elements.
protected  java.util.Date getAttributeAsDate(java.lang.String attribute)
          Returns an attribute as a date for the selected element, or null if none.
protected  java.lang.Double getAttributeAsDouble(java.lang.String attribute)
          Returns an attribute as a floating point for the selected element, or null if none.
protected  double[] getAttributeAsDoubles(java.lang.String attribute, boolean unique)
          Returns an attribute as an array of floating point for the selected element, or null if none.
protected  java.lang.Integer getAttributeAsInteger(java.lang.String attribute)
          Returns an attribute as an integer for the selected element, or null if none.
protected  int[] getAttributeAsIntegers(java.lang.String attribute, boolean unique)
          Returns an attribute as an array of integers for the selected element, or null if none.
protected  java.lang.String getAttributeAsString(java.lang.String attribute)
          Returns an attribute as a string for the selected element, or null if none.
protected  java.lang.Object getUserObject()
          Returns the user object associated with the selected element, or null if none.
protected
<T> T
getUserObject(java.lang.Class<? extends T> type)
          Returns the user object associated as an instance of the specified class.
protected  void selectChild(int index)
          Selects the element at the given index.
protected  void selectParent()
          Selects the parent of child elements.
protected  void setAttributeAsDate(java.lang.String attribute, java.util.Date value)
          Set the attribute to the specified value, or remove the attribute if the value is null.
protected  void setAttributeAsDouble(java.lang.String attribute, double value)
          Set the attribute to the specified floating point value, or remove the attribute if the value is NaN.
protected  void setAttributeAsDoubles(java.lang.String attribute, double[] values)
          Set the attribute to the specified array of values, or remove the attribute if the array is null.
protected  void setAttributeAsInteger(java.lang.String attribute, int value)
          Set the attribute to the specified integer value.
protected  void setAttributeAsIntegers(java.lang.String attribute, int[] values)
          Set the attribute to the specified array of values, or remove the attribute if the array is null.
protected  void setAttributeAsString(java.lang.String attribute, java.lang.String value)
          Set the attribute to the specified value, or remove the attribute if the value is null.
protected  void setUserObject(java.lang.Object value)
          Sets the user object associated with the selected element.
protected  boolean setWarningsEnabled(boolean enabled)
          Enables or disables the warnings.
 java.lang.String toString()
          Returns a string representation of metadata, mostly for debugging purpose.
static java.lang.String trimFractionalPart(java.lang.String value)
          Trims the factional part of the given string, provided that it doesn't change the value.
protected  void warningOccurred(java.util.logging.LogRecord record)
          Invoked when a warning occured.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

MetadataAccessor

protected MetadataAccessor(MetadataAccessor clone)
Creates an accessor with the same parent and childs than the specified one. The two accessors will share the same metadata nodes (including the list of childs), so change in one accessor will be immediately reflected in the other accessor. However each accessor can select their child independently.

The main purpose of this constructor is to create many views over the same list of childs, where each view select a different child.


MetadataAccessor

protected MetadataAccessor(GeographicMetadata metadata,
                           java.lang.String parentPath,
                           java.lang.String childPath)
Creates an accessor for the element at the given path. Paths are separated by the '/' character. See class javadoc for path examples.

Parameters:
metadata - The metadata node.
parentPath - The path to the node of interest, or null if the metadata root node is directly the node of interest.
childPath - The path (relative to parentPath) to the child elements, or null if none.
Method Detail

childCount

protected int childCount()
Returns the number of child elements. This is the upper value (exclusive) for selectChild(int).

Returns:
The child elements count.
See Also:
selectChild(int), appendChild(org.w3c.dom.Node, java.lang.String)

appendChild

protected int appendChild()
Adds a new child element at the path given at construction time. The child count will be increased by 1.

The new child is not automatically selected. In order to select this new child, the selectChild(int) method must be invoked explicitly.

Returns:
The index of the new child element.
See Also:
childCount(), selectChild(int)

selectChild

protected void selectChild(int index)
                    throws java.lang.IndexOutOfBoundsException
Selects the element at the given index. Every subsequent calls to get or set methods will apply to this selected child element.

Parameters:
index - The index of the element to select.
Throws:
java.lang.IndexOutOfBoundsException - if the specified index is out of bounds.
See Also:
childCount(), appendChild(org.w3c.dom.Node, java.lang.String), selectParent()

selectParent

protected void selectParent()
                     throws java.util.NoSuchElementException
Selects the parent of child elements. Every subsequent calls to get or set methods will apply to this parent element.

Throws:
java.util.NoSuchElementException - if there is no parent element.
See Also:
selectChild(int)

getUserObject

protected java.lang.Object getUserObject()
Returns the user object associated with the selected element, or null if none. If no user object is defined for the element, then the node value is returned as a fallback. This is consistent with setUserObject(java.lang.Object) implementation, and allows some parsing of nodes that are not IIOMetadataNode instances.

The getUserObject methods are the only ones to not parse the value returned by getAttributeAsString(java.lang.String).

Returns:
The user object, or null if none.
See Also:
getUserObject(Class), setUserObject(java.lang.Object)

getUserObject

protected <T> T getUserObject(java.lang.Class<? extends T> type)
                   throws java.lang.ClassCastException
Returns the user object associated as an instance of the specified class. If the value returned by getUserObject() is not of the expected type, then this method will tries to parse it as a string.

Parameters:
type - The expected class.
Returns:
The user object, or null if none.
Throws:
java.lang.ClassCastException - if the user object can not be casted to the specified type.
See Also:
getUserObject(), setUserObject(java.lang.Object)

setUserObject

protected void setUserObject(java.lang.Object value)
                      throws UnsupportedImplementationException
Sets the user object associated with the selected element. This is the only set method that doesn't invoke setAttributeAsString(java.lang.String, java.lang.String) with a formatted value.

If the specified value is formattable (i.e. is a character sequence, a number or an array of the above), then this method also sets the node value as a string. This is mostly a convenience for formatting purpose since IIOMetadataNode don't use the node value. But it may help some libraries that are not designed to work with with user objects, since they are particular to Image I/O metadata.

Parameters:
value - The user object, or null if none.
Throws:
UnsupportedImplementationException - if the selected element is not an instance of IIOMetadataNode.
See Also:
getUserObject()

getAttributeAsString

protected java.lang.String getAttributeAsString(java.lang.String attribute)
Returns an attribute as a string for the selected element, or null if none. This method never returns an empty string.

Every get methods in this class except getUserObject invoke this method first. Consequently, this method provides a single point for overriding if subclasses want to process the attribute before parsing.

Parameters:
attribute - The attribute to fetch (e.g. "name").
Returns:
The attribute value (never an empty string), or null if none.

setAttributeAsString

protected void setAttributeAsString(java.lang.String attribute,
                                    java.lang.String value)
Set the attribute to the specified value, or remove the attribute if the value is null.

Every set methods in this class except setUserObject invoke this method last. Consequently, this method provides a single point for overriding if subclasses want to process the attribute after formatting.

Parameters:
attribute - The attribute name.
value - The attribute value.

getAttributeAsInteger

protected java.lang.Integer getAttributeAsInteger(java.lang.String attribute)
Returns an attribute as an integer for the selected element, or null if none. If the attribute can't be parsed as an integer, then this method logs a warning and returns null.

Parameters:
attribute - The attribute to fetch (e.g. "minimum").
Returns:
The attribute value, or null if none or unparseable.

setAttributeAsInteger

protected void setAttributeAsInteger(java.lang.String attribute,
                                     int value)
Set the attribute to the specified integer value.

Parameters:
attribute - The attribute name.
value - The attribute value.

getAttributeAsIntegers

protected int[] getAttributeAsIntegers(java.lang.String attribute,
                                       boolean unique)
Returns an attribute as an array of integers for the selected element, or null if none. If an element can't be parsed as an integer, then this method logs a warning and returns null.

Parameters:
attribute - The attribute to fetch (e.g. "minimum").
unique - true if duplicated values should be collapsed into unique values, or false for preserving duplicated values.
Returns:
The attribute values, or null if none.

setAttributeAsIntegers

protected void setAttributeAsIntegers(java.lang.String attribute,
                                      int[] values)
Set the attribute to the specified array of values, or remove the attribute if the array is null.

Parameters:
attribute - The attribute name.
value - The attribute value.

getAttributeAsDouble

protected java.lang.Double getAttributeAsDouble(java.lang.String attribute)
Returns an attribute as a floating point for the selected element, or null if none. If the attribute can't be parsed as a floating point, then this method logs a warning and returns null.

Parameters:
attribute - The attribute to fetch (e.g. "minimum").
Returns:
The attribute value, or null if none or unparseable.

setAttributeAsDouble

protected void setAttributeAsDouble(java.lang.String attribute,
                                    double value)
Set the attribute to the specified floating point value, or remove the attribute if the value is NaN.

Parameters:
attribute - The attribute name.
value - The attribute value.

getAttributeAsDoubles

protected double[] getAttributeAsDoubles(java.lang.String attribute,
                                         boolean unique)
Returns an attribute as an array of floating point for the selected element, or null if none. If an element can't be parsed as a floating point, then this method logs a warning and returns null.

Parameters:
attribute - The attribute to fetch (e.g. "fillValues").
unique - true if duplicated values should be collapsed into unique values, or false for preserving duplicated values.
Returns:
The attribute values, or null if none.

setAttributeAsDoubles

protected void setAttributeAsDoubles(java.lang.String attribute,
                                     double[] values)
Set the attribute to the specified array of values, or remove the attribute if the array is null.

Parameters:
attribute - The attribute name.
value - The attribute value.

getAttributeAsDate

protected java.util.Date getAttributeAsDate(java.lang.String attribute)
Returns an attribute as a date for the selected element, or null if none. If the attribute can't be parsed as a date, then this method logs a warning and returns null.

Parameters:
attribute - The attribute to fetch (e.g. "origin").
Returns:
The attribute value, or null if none or unparseable.

setAttributeAsDate

protected void setAttributeAsDate(java.lang.String attribute,
                                  java.util.Date value)
Set the attribute to the specified value, or remove the attribute if the value is null.

Parameters:
attribute - The attribute name.
value - The attribute value.

trimFractionalPart

public static java.lang.String trimFractionalPart(java.lang.String value)
Trims the factional part of the given string, provided that it doesn't change the value. More specifically, this method removes the trailing ".0" characters if any. This method is automatically invoked before to parse an integer or to parse a date (for simplifying fractional seconds).

Parameters:
value - The value to trim.
Returns:
The value without the trailing ".0" part.

warningOccurred

protected void warningOccurred(java.util.logging.LogRecord record)
Invoked when a warning occured. This method is invoked when some inconsistency has been detected in the geographic metadata. The default implementation delegates to GeographicMetadata.warningOccurred(java.util.logging.LogRecord).


setWarningsEnabled

protected boolean setWarningsEnabled(boolean enabled)
Enables or disables the warnings. Warnings are enabled by default. Subclasses way want to temporarily disable the warnings when failures are expected as the normal behavior. For example a subclass may invokes getAttributeAsInteger(java.lang.String) and fallbacks on getAttributeAsDouble(java.lang.String) if the former failed. In such case, the warnings should be disabled for the integer parsing, but not for the floating point parsing.

Parameters:
enabled - true for enabling warnings, or false for disabling.
Returns:
The previous state before this method has been invoked.

toString

public java.lang.String toString()
Returns a string representation of metadata, mostly for debugging purpose.

Overrides:
toString in class java.lang.Object


Copyright © 1996-2010 Geotools. All Rights Reserved.