org.geotoolkit.image.io.metadata
Class SpatialMetadata

Object
  IIOMetadata
      SpatialMetadata

All Implemented Interfaces:

WarningProducer, Localized

public class SpatialMetadata
extends IIOMetadata
implements WarningProducer

Spatial (usually geographic) informations encoded in an image. This class converts the IIOMetadataNode elements and attribute values to ISO 19115-2 metadata objects. While ISO 19115-2 is the primary standard supported by this class, other standards can works if they are designed with the same rules than the org.opengis.metadata package.

ISO 19115-2 metadata instances are obtained by getInstanceForType(Class) (for a single instance) or getListForType(Class) (for a list of metadata instances) methods. The table below lists some common metadata elements. The "Format" and "Path to node" columns give the location of the metadata element in a tree conform to the spatial metadata format defined in this package.

Format	Path to node	Method call
STREAM	"DiscoveryMetadata"	getInstanceForType(DataIdentification.class)
STREAM	"DiscoveryMetadata/Extent/GeographicElement"	getInstanceForType(GeographicBoundingBox.class)
STREAM	"AcquisitionMetadata"	getInstanceForType(AcquisitionInformation.class)
IMAGE	"ImageDescription"	getInstanceForType(ImageDescription.class)
IMAGE	"ImageDescription/Dimensions"	getListForType(SampleDimension.class)
IMAGE	"RectifiedGridDomain"	getInstanceForType(RectifiedGrid.class)

The getInstanceForType(Class) and getListForType(Class) methods are tolerant to metadata located in other paths than the ones documented below, provided that the underlying metadata format declares exactly one element accepting a user object assignable to the given type. In case of ambiguity, an IllegalArgumentException is thrown.

Errors handling
If some inconsistency are found while reading (for example if the coordinate system dimension doesn't match the envelope dimension), then the default implementation logs a warning. We do not throw an exception because minor errors are not uncommon in geographic data, and we want to process the data on a "best effort" basis. However because every warnings are logged through the warningOccurred method, subclasses can override this method if they want to treat some warnings as fatal errors.

Since:

3.04 (derived from 2.4)

Version:

3.08

Author:

Martin Desruisseaux (Geomatys)

See Also:

SpatialMetadataFormat

Module:

coverage/geotk-coverageio (download)

View source code for this class

Field Summary

static SpatialMetadata	EMPTY An empty SpatialMetadata with no data and no format.
IIOMetadataFormat	format The metadata format given at construction time.

Fields inherited from class IIOMetadata

controller, defaultController, extraMetadataFormatClassNames, extraMetadataFormatNames, nativeMetadataFormatClassName, nativeMetadataFormatName, standardFormatSupported

Fields inherited from interface WarningProducer

LOGGER

Constructor Summary

SpatialMetadata(IIOMetadataFormat format)
Creates an initially empty metadata instance for the given format.

SpatialMetadata(IIOMetadataFormat format, ImageReader reader, IIOMetadata fallback)
Creates an initially empty metadata instance for the given format and reader.

SpatialMetadata(IIOMetadataFormat format, ImageWriter writer, IIOMetadata fallback)
Creates an initially empty metadata instance for the given format and writer.

Method Summary

protected <T> LoggedFormat<T>	createLoggedFormat(Format format, Class<T> type) Wraps the specified format in order to either parse fully a string, or log a warning.
Node	getAsTree(String formatName) Returns the root of a tree of metadata contained within this object according to the conventions defined by a given metadata format.
<T> T	getInstanceForType(Class<T> type) Returns an instance of the given type extracted from this IIOMetadata.
<T> T	getInstanceForType(Class<T> type, String path) Returns an instance of the given type extracted from this IIOMetadata at the given path.
<T> List<T>	getListForType(Class<T> type) Returns a list of instances of the given type extracted from this IIOMetadata.
<T> List<T>	getListForType(Class<T> type, String path, String children) Returns a list of instances of the given type extracted from this IIOMetadata at the given path.
Locale	getLocale() Returns the language to use when formatting messages, or null for the default.
IIOMetadataFormat	getMetadataFormat(String formatName) Returns an object describing the given metadata format, or null if no description is available.
Level	getWarningLevel() Returns the level at which warnings are emitted.
boolean	isReadOnly() Returns true if this object does not allows modification.
void	mergeTree(String formatName, Node root) Alters the internal state of this metadata from a tree whose syntax is defined by the given metadata format.
void	reset() Resets all the data stored in this object to default values.
void	setReadOnly(boolean ro) Sets whatever this SpatialMetadata should be read-only.
void	setWarningLevel(Level level) Sets the warning level.
String	toString() Returns a string representation of this metadata, mostly for debugging purpose.
boolean	warningOccurred(LogRecord record) Invoked when some inconsistency has been detected in the spatial metadata.

Methods inherited from class IIOMetadata

activateController, getController, getDefaultController, getExtraMetadataFormatNames, getMetadataFormatNames, getNativeMetadataFormatName, getStandardChromaNode, getStandardCompressionNode, getStandardDataNode, getStandardDimensionNode, getStandardDocumentNode, getStandardTextNode, getStandardTileNode, getStandardTransparencyNode, getStandardTree, hasController, isStandardMetadataFormatSupported, setController, setFromTree

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY

public static final SpatialMetadata EMPTY

An empty SpatialMetadata with no data and no format. This constant is an alternative to null for meaning that no metadata are available.

Since:

3.06

format

public final IIOMetadataFormat format

The metadata format given at construction time. This is typically SpatialMetadataFormat.IMAGE or SpatialMetadataFormat.STREAM.

Constructor Detail

SpatialMetadata

public SpatialMetadata(IIOMetadataFormat format)

Creates an initially empty metadata instance for the given format. The format argument is usually one of the SpatialMetadataFormat STREAM or IMAGE constants, but other formats are allowed.

Parameters:

format - The metadata format.

SpatialMetadata

public SpatialMetadata(IIOMetadataFormat format,
                       ImageReader reader,
                       IIOMetadata fallback)

Creates an initially empty metadata instance for the given format and reader. The format argument is usually one of the SpatialMetadataFormat STREAM or IMAGE constants, but other formats are allowed.

If the fallback argument is non-null, then any call to a getMetadataFormat, getAsTree, mergeTree or setFromTree method with a format name different than format.getRootName() will be delegated to that fallback. This is useful when the given ImageReader is actually a wrapper around an other ImageReader.

Parameters:

format - The metadata format.

reader - The source image reader, or null if none.

fallback - The fallback for any format name different than format.getRootName(), or null if none.

SpatialMetadata

public SpatialMetadata(IIOMetadataFormat format,
                       ImageWriter writer,
                       IIOMetadata fallback)

Creates an initially empty metadata instance for the given format and writer. The format argument is usually one of the SpatialMetadataFormat STREAM or IMAGE constants, but other formats are allowed.

If the fallback argument is non-null, then any call to a getMetadataFormat, getAsTree, mergeTree or setFromTree method with a format name different than format.getRootName() will be delegated to that fallback. This is useful when the given ImageWriter is actually a wrapper around an other ImageWriter.

Parameters:

format - The metadata format.

writer - The target image writer, or null if none.

fallback - The fallback for any format name different than format.getRootName(), or null if none.

Method Detail

getInstanceForType

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

Returns an instance of the given type extracted from this IIOMetadata. This method performs the following steps:

1. Invoke MetadataAccessor.listPaths(format, type):
   Search for an element declared in the format specified at construction time which accept a user object of the given type. Exactly one element is expected, otherwise an IllegalArgumentException is thrown.

2. Create a new MetadataAccessor(this, format.getRootName(), path, "#auto"):
   Create a new metadata accessor for the single path found at the previous step.

3. Invoke MetadataAccessor.getUserObject(type):
   If a user object was explicitly specified, return that object.

4. Invoke MetadataAccessor.newProxyInstance(type):
   If no explicit user object was found, create a proxy which will implement the getter methods by a code that fetch the value from the corresponding attribute.

If this SpatialMetadata does not contain a node for the given type, then this method returns null if this SpatialMetadata is read only, or create the missing nodes otherwise.

Type Parameters:

T - The compile-time type specified as the type argument.

Parameters:

type - The interface implemented by the instance to fetch.

Returns:

An implementation of the given interface, or null if none.

Throws:

IllegalArgumentException - If the given type is not a valid interface, or if no element or more than one element exist for the given type.

Since:

3.06

See Also:

MetadataAccessor.newProxyInstance(Class)

getInstanceForType

public <T> T getInstanceForType(Class<T> type,
                                String path)
                     throws IllegalArgumentException

Returns an instance of the given type extracted from this IIOMetadata at the given path. This method performs the same work than getInstanceForType(Class), except that the path is explicitly specified instead than automatically inferred from the type.

Example:

EnvironmentalRecord er = getInstanceForType(EnvironmentalRecord.class, "AcquisitionMetadata/EnvironmentalConditions");

If this SpatialMetadata does not contain a node for the given path, then this method returns null if this SpatialMetadata is read only, or create the missing nodes otherwise.

Note: At the opposite of getInstanceForType(Class), the current implementation of this method does not cache the returned proxy. Caching may be implemented in a future version.

Type Parameters:

T - The compile-time type specified as the type argument.

Parameters:

type - The interface implemented by the instance to fetch.

path - The path where to fetch the metadata.

Returns:

An implementation of the given interface, or null if none.

Throws:

IllegalArgumentException - If the given type is not a valid interface.

Since:

3.07

getListForType

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

Returns a list of instances of the given type extracted from this IIOMetadata. This method performs the same work than getInstanceForType(Class), but for a list.

If this SpatialMetadata does not contain a node for the given type, then this method returns null if this SpatialMetadata is read only, or create the missing nodes otherwise.

Note that a null return value has a different meaning than an empty list: an empty list means that the node exists but have no children, while a null value means that the parent node does not exist.

Type Parameters:

T - The compile-time type specified as the type argument.

Parameters:

type - The interface implemented by the elements of the list to fetch.

Returns:

A list of implementations of the given interface, or null if none.

Throws:

IllegalArgumentException - If the given type is not a valid interface, or if no element or more than one element exist for the given type.

Since:

3.06

See Also:

MetadataAccessor.newProxyList(Class)

getListForType

public <T> List<T> getListForType(Class<T> type,
                                  String path,
                                  String children)
                       throws IllegalArgumentException

Returns a list of instances of the given type extracted from this IIOMetadata at the given path. This method performs the same work than getListForType(Class), except that the path and the name of children are explicitly specified instead than automatically inferred from the type.

Example:

Instrument it = getListForType(Instrument.class, "AcquisitionMetadata/Platform/Instruments", "Instrument");

If this SpatialMetadata does not contain a node for the given path, then this method returns null if this SpatialMetadata is read only, or create the missing nodes otherwise.

Note that a null return value has a different meaning than an empty list: an empty list means that the node exists but have no children, while a null value means that the parent node does not exist.

Note: At the opposite of getListForType(Class), the current implementation of this method does not cache the returned proxy. Caching may be implemented in a future version.

Type Parameters:

T - The compile-time type specified as the type argument.

Parameters:

type - The interface implemented by the elements of the list to fetch.

path - The path of the parent node where to fetch the metadata.

children - The name of children under the parent node.

Returns:

A list of implementations of the given interface, or null if none.

Throws:

IllegalArgumentException - If the given type is not a valid interface.

Since:

3.07

getLocale

public Locale getLocale()

Returns the language to use when formatting messages, or null for the default. The default implementation delegates to ImageReader.getLocale() or ImageWriter.getLocale() if possible, or returns null otherwise.

Specified by:

getLocale in interface Localized

Returns:

The locale for formatting messages, or null.

getMetadataFormat

public IIOMetadataFormat getMetadataFormat(String formatName)
                                    throws IllegalArgumentException

Returns an object describing the given metadata format, or null if no description is available. The default implementation is as below:

• If formatName is equals, ignoring case, to format.getRootName() where format is the argument given at construction time, then return that format.
• Otherwise if a fallback has been specified at construction time, delegate to that fallback.
• Otherwise throw an IllegalArgumentException.

Overrides:

getMetadataFormat in class IIOMetadata

Parameters:

formatName - The desired metadata format.

Returns:

The desired metadata format, or null if none.

Throws:

IllegalArgumentException - If the specified format name is not recognized.

getAsTree

public Node getAsTree(String formatName)
               throws IllegalArgumentException

Returns the root of a tree of metadata contained within this object according to the conventions defined by a given metadata format.

Specified by:

getAsTree in class IIOMetadata

Parameters:

formatName - the desired metadata format.

Returns:

The node forming the root of metadata tree.

Throws:

IllegalArgumentException - if the format name is null or is not one of the names returned by IIOMetadata.getMetadataFormatNames().

mergeTree

public void mergeTree(String formatName,
                      Node root)
               throws IIOInvalidTreeException

Alters the internal state of this metadata from a tree whose syntax is defined by the given metadata format. The semantics of how a tree or subtree may be merged with another tree are format-specific. It may be simply replacing all existing state with the contents of the given tree.

Specified by:

mergeTree in class IIOMetadata

Parameters:

formatName - The desired metadata format.

root - An XML DOM Node object forming the root of a tree.

Throws:

IllegalStateException - If this metadata is read only.

IIOInvalidTreeException - If the tree cannot be parsed successfully using the rules of the given format.

isReadOnly

public boolean isReadOnly()

Returns true if this object does not allows modification. The default value is false. If the read-only state is set to true, then:

• Calls to mergeTree, setFromTree and reset methods will throw an IllegalStateException, as required by the standard IIOMetadata contract.

• Creation of MetadataAccessors will throw a NoSuchElementException if the named element does not exist in this SpatialMetadata object. Note that if the SpatialMetadata has not been declared read-only, then the default MetadataAccessor behavior is to create any missing nodes.

Specified by:

isReadOnly in class IIOMetadata

setReadOnly

public void setReadOnly(boolean ro)

Sets whatever this SpatialMetadata should be read-only.

Parameters:

ro - The new read-only state of this metadata object.

Since:

3.08

getWarningLevel

public Level getWarningLevel()

Returns the level at which warnings are emitted. The default implementation returns the last value given to the setWarningLevel(Level), or Level.WARNING if the level has not been explicitly defined.

Returns:

The current level at which warnings are emitted.

Since:

3.07

See Also:

MetadataAccessor.getWarningLevel()

setWarningLevel

public void setWarningLevel(Level level)

Sets the warning level. This logging level is given to all MetadataAccessor created by this SpatialMetadata instance. The default value is Level.WARNING.

Note that in the default implementation, warnings are logged only if this SpatialMetadata instance is not associated to an image reader or writer having warning listeners. See warningOccurred(LogRecord) for more details.

Parameters:

level - The new logging level.

Since:

3.07

See Also:

MetadataAccessor.setWarningLevel(Level)

warningOccurred

public boolean warningOccurred(LogRecord record)

Invoked when some inconsistency has been detected in the spatial metadata. The default implementation delegates to the first of the following choices which is applicable:

• SpatialImageReader.warningOccurred(LogRecord)
• SpatialImageWriter.warningOccurred(LogRecord)
• Send the record to the "org.geotoolkit.image.io" logger otherwise.

Subclasses can override this method if more processing is wanted, or for throwing exception if some warnings should be considered as fatal errors.

Specified by:

warningOccurred in interface WarningProducer

Parameters:

record - The warning record to log.

Returns:

true if the message has been sent to at least one warning listener, or false if it has been sent to the logging system as a fallback.

See Also:

MetadataAccessor.warningOccurred(LogRecord), IIOReadWarningListener

createLoggedFormat

protected <T> LoggedFormat<T> createLoggedFormat(Format format,
                                                 Class<T> type)

Wraps the specified format in order to either parse fully a string, or log a warning.

Type Parameters:

T - The expected type of parsed values.

Parameters:

format - The format to use for parsing and formatting.

type - The expected type of parsed values.

Returns:

A format that logs warnings when it can't parse fully a string.

reset

public void reset()

Resets all the data stored in this object to default values. All nodes below the root node are discarded.

Specified by:

reset in class IIOMetadata

Throws:

IllegalStateException - If this metadata is read only.

toString

public String toString()

Returns a string representation of this metadata, mostly for debugging purpose. The default implementation formats the metadata as a tree similar to the one formatted by MetadataAccessor.toString().

Overrides:

toString in class Object