MetadataAccessor (Geotoolkit.org 3.x-SNAPSHOT API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.geotoolkit.image.io.metadata
Class MetadataAccessor

Object
  MetadataAccessor

All Implemented Interfaces:: WarningProducer, Localized

public class MetadataAccessor
extends Object
implements WarningProducer
extends Object
implements WarningProducer

Convenience class for extracting attribute values from a SpatialMetadata object. This class is used by SpatialMetadata and usually don't need to be created explicitly. It is available in public API for users who need more flexibility than what SpatialMetadata provides.

The metadata object is specified at construction time, together with a path to the element of interest. Examples of valid paths:

"RectifiedGridDomain/CRS/Datum"   (assuming the image metadata format)
"RectifiedGridDomain/CRS/CoordinateSystem"   (assuming the image metadata format)
"DiscoveryMetadata/Extent/GeographicElement"   (assuming the stream metadata format)

If no node exists for the given path, then the node will be created at MetadataAccessor construction time. For example the last line in the above list will ensure that the metadata tree contains at least the nodes below, creating the missing ones if needed:

<root>
└───DiscoveryMetadata
    └───Extent
        └───GeographicElement

Note: the value of <root> depends on the metadata format, but is typically "geotk-coverageio_3.07"

After a MetadataAccessor instance has been created, the getAttributeAs<Type>(String) methods can be invoked for fetching any attribute values, taking care of conversions to String, Double, Integer or Date. Corresponding setter methods are also provided.

Accessing child elements
If order to access a child element when the child policy is CHILD_POLICY_ALL, CHILD_POLICY_SOME or CHILD_POLICY_CHOICE, create a new MetadataAccessor with the complete path to that element.

If the child policy of the node is CHILD_POLICY_REPEAT, then this class provides convenience methods for accessing the attributes of the childs. The path to unique legal child elements shall be specified to the constructor, as in the examples below:

new MetadataAccessor(..., "RectifiedGridDomain/CRS/CoordinateSystem", "Axis")
new MetadataAccessor(..., "ImageDescription/Dimensions", "Dimension")

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

Note that this mechanism is not suitable to nested childs, i.e. MetadataAccessor gives access only to the attributes of child elements. If an access to the childs nested in a child element is wanted, then the users may find more convenient to parse the XML tree by an other way than this convenience class.

Example reading attributes
The example below creates an accessor for a node called "CoordinateSystem" which is expected to have an arbitrary amount of childs called "Axis". The name of the first axis is fetched.

IIOMetadata metadata = new SpatialMetadata(SpatialMetadataFormat.IMAGE);
MetadataAccessor accessor = new MetadataAccessor(metadata, null,
        "RectifiedGridDomain/CRS/CoordinateSystem", "Axis");

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

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

Example adding childs and writing attributes
The example below uses the same accessor than above, but this time for adding a new child under the "CoordinateSystem" node:

accessor.selectChild(accessor.appendChild());
accessor.setAttribute("name", "The name of a new axis");

Getting ISO 19115-2 instances
This class can provide implementations of the ISO 19115-2 interfaces. Each getter method in an interface is implemented as a call to a getAttribute(String) method, or as the creation of a nested ISO 19115-2 object. See newProxyInstance(Class) for more details.

While this mechanism is primarily targeted at ISO 19115-2 interfaces, it can be used with other set of interfaces as well.

Since:

2.5

Version:

3.19

Author:

Martin Desruisseaux (Geomatys), Cédric Briançon (Geomatys)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Field Summary
`protected IIOMetadata`	`metadata` The Image I/O metadata for which this accessor is a wrapper.

Fields inherited from interface WarningProducer
`LOGGER`

Constructor Summary
`MetadataAccessor(IIOMetadata metadata, String parentPath)` Creates an accessor for the element at the given path relative to the root.
`MetadataAccessor(IIOMetadata metadata, String formatName, Class<?> objectClass)` Creates an accessor for the element accepting a user object of the given type.
`MetadataAccessor(IIOMetadata metadata, String formatName, String parentPath, String childPath)` Creates an accessor for the element at the given path relative to the root.
`MetadataAccessor(MetadataAccessor clone)` Creates an accessor with the same parent and childs than the specified one.
`MetadataAccessor(MetadataAccessor parent, Class<?> objectClass)` Creates an accessor for the element accepting a user object of the given type.
`MetadataAccessor(MetadataAccessor parent, String path, String childPath)` Creates an accessor for the element at the given path relative to the given parent.

Method Summary

int appendChild()
Adds a new child element at the path given at construction time.

int childCount()
Returns the number of child elements.

String getAttribute(String attribute)
Returns an attribute as a string for the selected element, or null if none.

Boolean getAttributeAsBoolean(String attribute)
Returns an attribute as a boolean for the selected element, or null if none.

Citation getAttributeAsCitation(String attribute)
Returns an attribute as a citation for the selected element, or null if none.





<T extends CodeList<T>> 


T

getAttributeAsCode(String attribute,
                   Class<T> codeType)

Returns an attribute as a code for the selected element, or null if none.

Date getAttributeAsDate(String attribute)
Returns an attribute as a date for the selected element, or null if none.

Double getAttributeAsDouble(String attribute)
Returns an attribute as a floating point for the selected element, or null if none.

double[] getAttributeAsDoubles(String attribute, boolean unique)
Returns an attribute as an array of floating point for the selected element, or null if none.

Float getAttributeAsFloat(String attribute)
Returns an attribute as a floating point values for the selected element, or null if none.

float[] getAttributeAsFloats(String attribute, boolean unique)
Returns an attribute as an array of floating point values for the selected element, or null if none.

Integer getAttributeAsInteger(String attribute)
Returns an attribute as an integer for the selected element, or null if none.

int[] getAttributeAsIntegers(String attribute, boolean unique)
Returns an attribute as an array of integers for the selected element, or null if none.

NumberRange<?> getAttributeAsRange(String attribute)
Returns an attribute as a range of numbers for the selected element, or null if none.

String[] getAttributeAsStrings(String attribute, boolean unique)
Returns an attribute as an array of strings for the selected element, or null if none.





<Q extends Quantity> 


Unit<Q>

getAttributeAsUnit(String attribute,
                   Class<Q> quantity)

Returns an attribute as a unit for the selected element, or null if none.

Locale getLocale()
Returns the locale to use for formatting warnings and error messages.

Object getUserObject()
Returns the user object associated with the selected element, or null if none.





<T> T

getUserObject(Class<? extends T> type)
Returns the user object as an instance of the specified class.

Level getWarningLevel()
Returns the level at which warnings are emitted, or Level.OFF if they are disabled.

boolean isEmpty()
Returns true if this node contains no child and no attribute.

boolean isReadOnly()
Returns true if this accessor is read-only.

static List<String> listPaths(IIOMetadataFormat format, Class<?> objectClass)
Returns the paths to every elements declared in the given format which accept a user object of the given type.

String name()
Returns the name of the element for which this accessor will fetch attribute values.





<T> T

newProxyInstance(Class<T> type)
Returns a view of the parent element as an implementation of the given interface.





<T> List<T>

newProxyList(Class<T> type)
Returns a view of the child elements as a list of implementations of the given type.

void selectChild(int index)
Selects the element at the given index.

void selectParent()
Selects the parent of child elements.

void setAttribute(String attribute, boolean value)
Sets the attribute to the specified boolean value.

void setAttribute(String attribute, Citation value)
Sets the attribute to the specified citation value, or remove the attribute if the value is null.

void setAttribute(String attribute, CodeList<?> value)
Sets the attribute to the specified code value, or remove the attribute if the value is null.

void setAttribute(String attribute, Date value)
Sets the attribute to the specified value, or remove the attribute if the value is null.

void setAttribute(String attribute, double... values)
Set the attribute to the specified array of values, or remove the attribute if the array is null.

void setAttribute(String attribute, double value)
Sets the attribute to the specified floating point value, or remove the attribute if the value is NaN or infinity.

void setAttribute(String attribute, float... values)
Set the attribute to the specified array of values, or remove the attribute if the array is null.

void setAttribute(String attribute, float value)
Sets the attribute to the specified floating point value, or remove the attribute if the value is NaN or infinity.

void setAttribute(String attribute, int... values)
Set the attribute to the specified array of values, or remove the attribute if the array is null.

void setAttribute(String attribute, int value)
Sets the attribute to the specified integer value.

void setAttribute(String attribute, NumberRange<?> value)
Sets the attribute to the specified range value.

void setAttribute(String attribute, String... values)
Sets the attribute to the specified array of values, or remove the attribute if the array is null.

void setAttribute(String attribute, String value)
Sets the attribute to the specified value, or remove the attribute if the value is null.

void setAttribute(String attribute, Unit<?> value)
Sets the attribute to the specified unit value.

void setUserObject(Object value)
Sets the user object associated with the selected element.

Level setWarningLevel(Level level)
Sets the warning level, or disable warnings.

String toString()
Returns a string representation of the wrapped IIOMetadata as a tree.

boolean warningOccurred(LogRecord record)
Invoked when a warning occurred.

Methods inherited from class Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

metadata

protected final IIOMetadata metadata

The Image I/O metadata for which this accessor is a wrapper. An instance of the SpatialMetadata subclass is recommended, but not mandatory.

Since:: 3.06

Constructor Detail

MetadataAccessor

public 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 initially selected child and warnings level are the same than the given accessor.

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

Parameters:: clone - The accessor to clone.

MetadataAccessor

public MetadataAccessor(MetadataAccessor parent,
                        String path,
                        String childPath)
                 throws IllegalArgumentException,
                        NoSuchElementException

Creates an accessor for the element at the given path relative to the given parent. In the example below, the complete path to the child accessor is "DiscoveryMetadata/Extent/GeographicElement":

MetadataAccessor parent = new MetadataAccessor(..., "DiscoveryMetadata/Extent", ...);
MetadataAccessor child  = new MetadataAccessor(parent, "GeographicElement", null);

Auto-detection of children
If the metadata node has no child, then childPath shall be null. If the caller does not know whatever the node has childs or not, then the "#auto" special value can be used. Note that this auto-detection may throw an IllegalArgumentException if the node is not defined by the IIOMetadataFormat. It is preferable to specify explicitly the child element name when this name is known.

Parameters:: parent - The accessor for which the path is relative.; path - The path to the node of interest.; childPath - The path to the child elements, or null if none, or "#auto" for auto-detection.
Throws:: IllegalArgumentException - if childPath is "#auto" but the childs can not be inferred from the metadata format.; NoSuchElementException - If this accessor is is read only and the given metadata doesn't contains a node for the element to fetch.
Since:: 3.06

MetadataAccessor

public MetadataAccessor(MetadataAccessor parent,
                        Class<?> objectClass)
                 throws IllegalArgumentException,
                        NoSuchElementException

Creates an accessor for the element accepting a user object of the given type. This method is convenient for fetching an object of some known type without regards to its location in the sub-tree.

Parameters:: parent - The accessor from which to start the search for an element accepting the given type.; objectClass - The class of user object to locate.
Throws:: IllegalArgumentException - If no element accepting the given type was found, or if more than one element accepting that type was found.; NoSuchElementException - If this accessor is is read only and the given metadata doesn't contains a node for the element to fetch.
Since:: 3.06
See Also:: listPaths(IIOMetadataFormat, Class)

MetadataAccessor

public MetadataAccessor(IIOMetadata metadata,
                        String parentPath)
                 throws NoSuchElementException

Creates an accessor for the element at the given path relative to the root. This is a convenience method for the constructor below with formatName and childPath argument set to "#auto" value.

Parameters:: metadata - The Image I/O metadata. An instance of the SpatialMetadata sub-class is recommended, but not mandatory.; parentPath - The path to the node of interest, or null if the metadata root node is directly the node of interest.
Throws:: NoSuchElementException - If this accessor is is read only and the given metadata doesn't contains a node for the element to fetch.
Since:: 3.06

MetadataAccessor

public MetadataAccessor(IIOMetadata metadata,
                        String formatName,
                        String parentPath,
                        String childPath)
                 throws NoSuchElementException

Creates an accessor for the element at the given path relative to the root. The paths can contain many elements separated by the '/' character. See the class javadoc for more details.

Auto-detection of children and format
The childPath argument can be "#auto", which is processed as documented in the above constructor.

The formatName can be null or "#auto", in which case a format is selected automatically:

If metadata is an instance of SpatialMetadata, then the format given at SpatialMetadata construction time is used.
Otherwise the first format returned by IIOMetadata.getMetadataFormatNames() is used. This is usually in preference order: the native format, the standard format or the first extra format.

Parameters:: metadata - The Image I/O metadata. An instance of the SpatialMetadata sub-class is recommended, but not mandatory.; formatName - The name of the format to use, or null or "#auto" for an automatic selection.; 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, or "#auto" for auto-detection.
Throws:: NoSuchElementException - If this accessor is is read only and the given metadata doesn't contains a node for the element to fetch.

MetadataAccessor

public MetadataAccessor(IIOMetadata metadata,
                        String formatName,
                        Class<?> objectClass)
                 throws IllegalArgumentException,
                        NoSuchElementException

Creates an accessor for the element accepting a user object of the given type. This method is convenient for fetching an object of some known type without regards to its location in the tree. For example if the metadata format is SpatialMetadataFormat.STREAM then:

new MetadataAccessor(metadata, formatName, GeographicElement.class);

is equivalent to:

new MetadataAccessor(metadata, formatName, "DiscoveryMetadata/Extent/GeographicElement", "#auto");

Parameters:: metadata - The Image I/O metadata. An instance of the SpatialMetadata sub-class is recommended, but not mandatory.; formatName - The name of the format to use, or null or "#auto" for an automatic selection.; objectClass - The class of user object to locate.
Throws:: IllegalArgumentException - If no element accepting the given type was found, or if more than one element accepting that type was found.; NoSuchElementException - If this accessor is is read only and the given metadata doesn't contains a node for the element to fetch.
Since:: 3.06
See Also:: listPaths(IIOMetadataFormat, Class)

Method Detail

listPaths

public static List<String> listPaths(IIOMetadataFormat format,
                                     Class<?> objectClass)

Returns the paths to every elements declared in the given format which accept a user object of the given type. If no path is found, returns an empty list.

Collection handling
In the particular case where the element is the child of a node having having CHILD_POLICY_REPEAT, then the path to the parent node is returned. In other words, if the given type is the type of elements in a collection, then the path to the whole collection is returned instead than the path to a single element in that collection.

Parameters:: format - The metadata format in which to search.; objectClass - The class of user object to locate.
Returns:: The list of paths to elements that accept user objects of the given type.
Since:: 3.06
See Also:: MetadataAccessor(MetadataAccessor, Class), MetadataAccessor(IIOMetadata, String, Class)

name

public String name()

Returns the name of the element for which this accessor will fetch attribute values. This is the last part of the parentPath argument given at construction time. For example if the given path was "DiscoveryMetadata/Extent/GeographicElement", then the name returned by this method is "GeographicElement".

Returns:: The name of the metadata element.
Since:: 3.06

isReadOnly

public boolean isReadOnly()

Returns true if this accessor is read-only. The default implementation returns the read-only state of the wrapped metadata object. Subclasses can override this method if they need more control about whatever this accessor is allowed to add child elements in the metadata object.

If this method returns true, then every setFoo(…) methods in this class will thrown an UnsupportedOperationException when they are invoked.

Returns:: true if this accessor is read-only, or false if it allows write operations.
Since:: 3.19
See Also:: IIOMetadata.isReadOnly()

isEmpty

public boolean isEmpty()

Returns true if this node contains no child and no attribute.

Returns:: true if this node is empty, or false if it contains at least one child or one attribute.
Since:: 3.13

childCount

public 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

public int appendChild()
                throws UnsupportedOperationException

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.
Throws:: UnsupportedOperationException - If this accessor does not allow children.
See Also:: childCount(), selectChild(int)

selectChild

public void selectChild(int index)
                 throws 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:: IndexOutOfBoundsException - if the specified index is out of bounds.
See Also:: childCount(), appendChild(org.w3c.dom.Node, java.lang.String), selectParent()

selectParent

public void selectParent()
                  throws NoSuchElementException

Selects the parent of child elements. Every subsequent calls to get or set methods will apply to this parent element.

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

getUserObject

public Object getUserObject()

Returns the user object associated with the selected element, or null if none. This method returns the first of the following methods which return a non-null value:

IIOMetadataNode.getUserObject() (only if the node is an instance of IIOMetadata)
Node.getNodeValue()

The node value fallback is consistent with setUserObject(Object) implementation, and allows processing of nodes that are not IIOMetadataNode instances.

Note: This getUserObject() method and the getUserObject(Class) method below are the only getters that do not fetch the string to parse by a call to getAttribute.

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

getUserObject

public <T> T getUserObject(Class<? extends T> type)
                throws ClassCastException

Returns the user object as an instance of the specified class. This method first invokes getUserObject(), then checks the type of the returned object. The type shall be the requested one - this method does not attempt conversions.

A special processing is performed if the type of the user object is assignable to CharSequence. This special processing is performed because if the node is not an instance of IIOMetadataNode, then getUserObject() fallbacks on Node.getNodeValue(), which can return only a String. In such case, this method will attempt a parsing of the string if the requested type is a subclass of Number, Date, double[] or int[].

Type Parameters:: T - The expected class.
Parameters:: type - The expected class.
Returns:: The user object, or null if none.
Throws:: NumberFormatException - If attempt to parse the user object as a number failed.; IllegalArgumentException - If attempt to parse the user object as a date failed.; ClassCastException - If the user object can not be casted to the specified type.
See Also:: getUserObject(), setUserObject(Object), SpatialMetadata.getInstanceForType(Class)

newProxyInstance

public <T> T newProxyInstance(Class<T> type)
                   throws IllegalArgumentException

Returns a view of the parent element as an implementation of the given interface. This method returns an instance of the given interface where each getter method is implemented like the following pseudo-code, where <T> is the type given in argument to this method, <RT1> is the return type of the first method and <RT2> is the return type of the second method:

class Proxy implements <T> {
    public <RT1> getBanana() {
        return Accessor.this.getAttributeAs<RT1>("banana");
    }

    public <RT2> getApple() {
        return Accessor.this.getAttributeAs<RT2>("apple");
    }

    // etc. for every getter methods declared in the interface.
}

The <T> type is typically one of the types given to the SpatialMetadataFormat.addTree(...) method, but this is not mandatory. This <T> is usually an interface from the ISO 19115-2 standard, but this is not mandatory neither. However all getter methods declared in that type shall comply with the Java Beans conventions.

Example
Assume a metadata format conforms to the Stream metadata format documented here. There is an extract of that format:

DiscoveryMetadata
└───SpatialResolution
    └───distance

In the following code, every call to the Resolution.getDistance() method on the instance returned by this newProxyInstance(type) method will be implemented as a call to the getAttributeAsDouble("distance") method on this MetadataAccessor instance:

IIOMetadata       metadata   = new SpatialMetadata(SpatialMetadataFormat.STREAM);
MetadataAccessor  accessor   = new MetadataAccessor(metadata, "#auto", "DiscoveryMetadata/SpatialResolution", null);
SpatialResolution resolution = accessor.newProxyInstance(SpatialResolution.class);

// From this point, we can forget that the metadata are stored in an IIOMetadata object.
// The following line delegates the work to accessor.getAttributeAsDouble("distance");
Double distance = resolution.getDistance();
System.out.println("The resolution is " + distance);

Changes to the underlying IIOMetadata attributes are immediately reflected in the Resolution instance:

accessor.setAttribute("distance", 20);
distance = resolution.getDistance(); // Should now return 20.

Nested proxies
If the return type of a getter method (the <RT1> and <RT2> types in the above example) is not assignable from String, Double or other types for which a getAttribute method is defined in this MetadataAccessor class (see here for a complete list), then that type is assumed to be an other metadata interface. In such case, a new MetadataAccessor is created for that element and a new proxy created by this newProxyInstance method is returned.

Type Parameters:: T - The compile-time type specified as the type argument.
Parameters:: type - The interface for which to create a proxy instance.
Returns:: An implementation of the given interface with getter methods that fetch their return values from the attribute values.
Throws:: IllegalArgumentException - If the given type is not a valid interface.
Since:: 3.06
See Also:: SpatialMetadata.getInstanceForType(Class), Proxy

newProxyList

public <T> List<T> newProxyList(Class<T> type)
                     throws IllegalArgumentException

Returns a view of the child elements as a list of implementations of the given type. This method performs the same work than newProxyInstance(Class) for every childs of the element represented by this accessor.

Type Parameters:: T - The compile-time type specified as the type argument.
Parameters:: type - The interface for which to create proxy instances.
Returns:: A list of implementations of the given interface with getter methods that fetch their return values from the attribute values.
Throws:: IllegalArgumentException - If the given type is not a valid interface.
Since:: 3.06
See Also:: SpatialMetadata.getListForType(Class)

getAttribute

public String getAttribute(String attribute)

Returns an attribute as a string for the selected element, or null if none. This method never returns an empty string.

Every getAttribute methods in this class invoke this method first. Consequently, this method provides a single overriding point for subclasses that 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.
See Also:: setAttribute(String, String), IIOMetadataFormat.DATATYPE_STRING

getAttributeAsStrings

public String[] getAttributeAsStrings(String attribute,
                                      boolean unique)

Returns an attribute as an array of strings for the selected element, or null if none. This method gets the attribute as a single string, then splits that string on the ordinary space separator. If some items in the resulting strings contain the no-break space ('\\u00A0'), then those characters are replaced by ordinary spaces after the split.

Parameters:: attribute - The attribute to fetch (e.g. "keywords").; 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.
Since:: 3.06
See Also:: setAttribute(String, String[])

getAttributeAsCode

public <T extends CodeList<T>> T getAttributeAsCode(String attribute,
                                                    Class<T> codeType)

Returns an attribute as a code for the selected element, or null if none. If the code stored in the given attribute is not a known element, then this method logs a warning and returns null.

Type Parameters:: T - The type of the code list.
Parameters:: attribute - The attribute to fetch (e.g. "imagingCondition").; codeType - The type of the code list. This is used for determining the expected values.
Returns:: The attribute value, or null if none or unknown.
Since:: 3.06
See Also:: setAttribute(String, CodeList)

getAttributeAsBoolean

public Boolean getAttributeAsBoolean(String attribute)

Returns an attribute as a boolean for the selected element, or null if none. If the attribute can't be parsed as a boolean, then this method logs a warning and returns null.

Parameters:: attribute - The attribute to fetch (e.g. "inclusion").
Returns:: The attribute value, or null if none or unparseable.
Since:: 3.06
See Also:: setAttribute(String, boolean), IIOMetadataFormat.DATATYPE_BOOLEAN

getAttributeAsInteger

public Integer getAttributeAsInteger(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.
See Also:: setAttribute(String, int), IIOMetadataFormat.DATATYPE_INTEGER

getAttributeAsIntegers

public int[] getAttributeAsIntegers(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.
See Also:: setAttribute(String, int[])

getAttributeAsFloat

public Float getAttributeAsFloat(String attribute)

Returns an attribute as a floating point values 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.
Since:: 3.06
See Also:: setAttribute(String, float), IIOMetadataFormat.DATATYPE_FLOAT

getAttributeAsFloats

public float[] getAttributeAsFloats(String attribute,
                                    boolean unique)

Returns an attribute as an array of floating point values 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.
Since:: 3.06
See Also:: setAttribute(String, float[])

getAttributeAsDouble

public Double getAttributeAsDouble(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.
See Also:: setAttribute(String, double), IIOMetadataFormat.DATATYPE_DOUBLE

getAttributeAsDoubles

public double[] getAttributeAsDoubles(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.
See Also:: setAttribute(String, double[])

getAttributeAsDate

public Date getAttributeAsDate(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.
See Also:: setAttribute(String, Date)

getAttributeAsRange

public NumberRange<?> getAttributeAsRange(String attribute)

Returns an attribute as a range of numbers for the selected element, or null if none. If the attribute can't be parsed as a range of numbers, then this method logs a warning and returns null.

Parameters:: attribute - The attribute to fetch (e.g. "validSampleValues").
Returns:: The attribute value, or null if none or unparseable.
Since:: 3.06
See Also:: setAttribute(String, NumberRange)

getAttributeAsUnit

public <Q extends Quantity> Unit<Q> getAttributeAsUnit(String attribute,
                                                       Class<Q> quantity)

Returns an attribute as a unit for the selected element, or null if none. If the attribute can't be parsed as a unit of the given quantity, then this method logs a warning and returns null.

Type Parameters:: Q - The compile-time type of the quantity argument.
Parameters:: attribute - The attribute to fetch (e.g. "axisUnit").; quantity - The quantity of the unit to be returned, or null for any.
Returns:: The attribute value, or null if none or unparseable.
Since:: 3.07
See Also:: setAttribute(String, Unit)

getAttributeAsCitation

public Citation getAttributeAsCitation(String attribute)

Returns an attribute as a citation for the selected element, or null if none.

Parameters:: attribute - The attribute to fetch (e.g. "authority").
Returns:: The attribute value, or null if none.
Since:: 3.06
See Also:: setAttribute(String, Citation)

setUserObject

public void setUserObject(Object value)
                   throws UnsupportedImplementationException

Sets the user object associated with the selected element. At the difference of every setAttribute methods defined in this class, this method does not delegate to setAttribute(String, String).

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

setAttribute

public void setAttribute(String attribute,
                         String value)

Sets the attribute to the specified value, or remove the attribute if the value is null.

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

Parameters:: attribute - The attribute name.; value - The attribute value, or null for removing the attribute.
See Also:: getAttribute(String), IIOMetadataFormat.DATATYPE_STRING

setAttribute

public void setAttribute(String attribute,
                         String... values)

Sets the attribute to the specified array of values, or remove the attribute if the array is null. The given items are formatted in a single string with an ordinary space used as the item separator, as mandated by IIOMetadataFormat.VALUE_LIST. If some of the given items contain spaces, then those spaces are replaced by a no-break space ('\\u00A0') for avoiding confusion with the space separator.

Parameters:: attribute - The attribute name.; values - The attribute values, or null for removing the attribute.
Since:: 3.06
See Also:: getAttributeAsStrings(String, boolean)

setAttribute

public void setAttribute(String attribute,
                         CodeList<?> value)

Sets the attribute to the specified code value, or remove the attribute if the value is null.

Parameters:: attribute - The attribute name.; value - The attribute value, or null for removing the attribute.
Since:: 3.06
See Also:: getAttributeAsCode(String, Class)

setAttribute

public void setAttribute(String attribute,
                         boolean value)

Sets the attribute to the specified boolean value.

Parameters:: attribute - The attribute name.; value - The attribute value.
Since:: 3.06
See Also:: getAttributeAsBoolean(String), IIOMetadataFormat.DATATYPE_BOOLEAN

setAttribute

public void setAttribute(String attribute,
                         int value)

Sets the attribute to the specified integer value.

Parameters:: attribute - The attribute name.; value - The attribute value.
See Also:: getAttributeAsInteger(String), IIOMetadataFormat.DATATYPE_INTEGER

setAttribute

public void setAttribute(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.; values - The attribute values, or null for removing the attribute.
See Also:: getAttributeAsIntegers(String, boolean)

setAttribute

public void setAttribute(String attribute,
                         float value)

Sets the attribute to the specified floating point value, or remove the attribute if the value is NaN or infinity.

Parameters:: attribute - The attribute name.; value - The attribute value.
Since:: 3.06
See Also:: getAttributeAsFloat(String), IIOMetadataFormat.DATATYPE_FLOAT

setAttribute

public void setAttribute(String attribute,
                         float... values)

Set the attribute to the specified array of values, or remove the attribute if the array is null.

Parameters:: attribute - The attribute name.; values - The attribute values, or null for removing the attribute.
Since:: 3.06
See Also:: getAttributeAsDoubles(String, boolean)

setAttribute

public void setAttribute(String attribute,
                         double value)

Sets the attribute to the specified floating point value, or remove the attribute if the value is NaN or infinity.

Parameters:: attribute - The attribute name.; value - The attribute values.
See Also:: getAttributeAsDouble(String), IIOMetadataFormat.DATATYPE_DOUBLE

setAttribute

public void setAttribute(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.; values - The attribute values, or null for removing the attribute.
See Also:: getAttributeAsDoubles(String, boolean)

setAttribute

public void setAttribute(String attribute,
                         Date value)

Sets the attribute to the specified value, or remove the attribute if the value is null.

Parameters:: attribute - The attribute name.; value - The attribute value, or null for removing the attribute.
See Also:: getAttributeAsDate(String)

setAttribute

public void setAttribute(String attribute,
                         NumberRange<?> value)

Sets the attribute to the specified range value.

Parameters:: attribute - The attribute name.; value - The attribute value, or null for removing the attribute.
Since:: 3.06
See Also:: getAttributeAsRange(String)

setAttribute

public void setAttribute(String attribute,
                         Unit<?> value)

Sets the attribute to the specified unit value.

Parameters:: attribute - The attribute name.; value - The attribute value.
Since:: 3.07
See Also:: getAttributeAsUnit(String, Class)

setAttribute

public void setAttribute(String attribute,
                         Citation value)

Sets the attribute to the specified citation value, or remove the attribute if the value is null.

Parameters:: attribute - The attribute name.; value - The attribute value, or null for removing the attribute.
Since:: 3.06
See Also:: getAttributeAsCitation(String)

warningOccurred

public boolean warningOccurred(LogRecord record)

Invoked when a warning occurred. This method is invoked when some inconsistency has been detected in the spatial metadata. The default implementation tries to send the message to the warning listeners, if possible. The record is actually logged only if no listener can be reached.

More specifically, the typical chain of method calls is as below. Note that the actual chain may be different since any of those methods can be overridden, and the ImageReader can be an ImageWriter instead.

MetadataAccessor.warningOccurred(LogRecord)
SpatialMetadata.warningOccurred(LogRecord)
SpatialImageReader.warningOccurred(LogRecord)
ImageReader.processWarningOccurred(String)
IIOReadWarningListener.warningOccurred(ImageReader, String)

Specified by:: warningOccurred in interface WarningProducer

Parameters:: record - The logging record to log.
Returns:: true if the message has been sent to at least one warning listener, or false otherwise (either the message has been sent to the logging system as a fallback, or the warning level if OFF).

getWarningLevel

public Level getWarningLevel()

Returns the level at which warnings are emitted, or Level.OFF if they are disabled. The default value is Level.WARNING.

Note that the warnings are effectively sent to the logging framework only if there is no registered Image I/O warning listeners. See the warningOccurred(LogRecord) javadoc for details.

Returns:: The current level at which warnings are emitted.

setWarningLevel

public Level setWarningLevel(Level level)

Sets the warning level, or disable warnings. By default, warnings are enabled and set to the WARNING level. Subclasses way want to temporarily disable the warnings (using the Level.OFF argument value) when failures are expected as the normal behavior. For example a subclass may invoke getAttributeAsInteger(String) and fallback on getAttributeAsDouble(String) if the former failed. In such case, the warnings should be disabled for the integer parsing, but not for the floating point parsing.

Note that a low warning level like Level.FINE may prevent the warnings to be sent to the console logger, but does not prevent the warnings to be sent to the Image I/O warning listeners (see warningOccurred(LogRecord) javadoc). Only Level.OFF really disables warnings.

Parameters:: level - Level.OFF for disabling warnings, or an other value for enabling them.
Returns:: The previous state before this method has been invoked.

getLocale

public Locale getLocale()

Returns the locale to use for formatting warnings and error messages. This method delegates to SpatialMetadata.getLocale() if possible, or returns null otherwise.

Specified by:: getLocale in interface Localized

Returns:: The locale to use for formatting the warnings, or null.
Since:: 3.07

toString

public String toString()

Returns a string representation of the wrapped IIOMetadata as a tree. The root of the tree contains the class of this accessor and the value defined in the name() javadoc. Attributes are leafs formatted as key="value", while elements and child branches.

This method is useful for visual check of the IIOMetadata content and should be used only for debugging purpose. Note that the output may span many lines.

Overrides:: toString in class Object

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

`"RectifiedGridDomain/CRS/Datum"`	(assuming the image metadata format)
`"RectifiedGridDomain/CRS/CoordinateSystem"`	(assuming the image metadata format)
`"DiscoveryMetadata/Extent/GeographicElement"`	(assuming the stream metadata format)

org.geotoolkit.image.io.metadata Class MetadataAccessor

metadata

MetadataAccessor

MetadataAccessor

MetadataAccessor

MetadataAccessor

MetadataAccessor

MetadataAccessor

listPaths

name

isReadOnly

isEmpty

childCount

appendChild

selectChild

selectParent

getUserObject

getUserObject

newProxyInstance

newProxyList

getAttribute

getAttributeAsStrings

getAttributeAsCode

getAttributeAsBoolean

getAttributeAsInteger

getAttributeAsIntegers

getAttributeAsFloat

getAttributeAsFloats

getAttributeAsDouble

getAttributeAsDoubles

getAttributeAsDate

getAttributeAsRange

getAttributeAsUnit

getAttributeAsCitation

setUserObject

setAttribute

setAttribute

setAttribute

setAttribute

setAttribute

setAttribute

setAttribute

setAttribute

setAttribute

setAttribute

setAttribute

setAttribute

setAttribute

setAttribute

warningOccurred

getWarningLevel

setWarningLevel

getLocale

toString

org.geotoolkit.image.io.metadata
Class MetadataAccessor