org.geotoolkit.image.io.metadata
Class SpatialMetadataFormatBuilder

Object
  Builder<SpatialMetadataFormat>
      SpatialMetadataFormatBuilder

public class SpatialMetadataFormatBuilder
extends Builder<SpatialMetadataFormat>

Creates new spatial metadata format instances. This class infers the tree structure from metadata objects defined by some metadata standard, typically ISO 19115-2. New metadata elements are declared by calls to the generic addTree method, or one of its specialized variants like addTreeForImage(String).

This builder is used for creating the default trees documented here. Users can leverage this builder for creating trees based on interfaces from other standards.

Since:

3.20 (derived from 3.05)

Version:

3.20

Author:

Martin Desruisseaux (Geomatys)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Constructor Summary

SpatialMetadataFormatBuilder(Class<? extends SpatialMetadataFormat> type)
Creates a builder for a metadata format of the given type.

SpatialMetadataFormatBuilder(String rootName)
Creates a builder for a metadata format of the given name.

Method Summary

void	addTree(MetadataStandard standard, Class<?> type) Adds a new optional element or attribute of the given type as a child of the root.
void	addTree(MetadataStandard standard, Class<?> type, String elementName, String parentName, boolean mandatory) Adds a new element or attribute of the given type and name as a child of the given node.
protected void	addTreeForCRS(String addToElement) Adds the tree structure for a Coordinate Reference System object.
void	addTreeForImage(String addToElement) Adds the tree structure for image metadata.
protected void	addTreeForISO19115(String addToElement) Adds the tree structure for an ISO-19115 metadata object.
void	addTreeForStream(String addToElement) Adds the tree structure for stream metadata.
SpatialMetadataFormat	build() Returns the metadata format instance which has been build.
Map<Class<?>,Class<?>>	substitutions() The map of children types to substitute by other types.

Methods inherited from class Object

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

Constructor Detail

SpatialMetadataFormatBuilder

public SpatialMetadataFormatBuilder(String rootName)

Creates a builder for a metadata format of the given name. The metadata format will be an instance of SpatialMetadataFormat.

Parameters:

rootName - the name of the root element.

SpatialMetadataFormatBuilder

public SpatialMetadataFormatBuilder(Class<? extends SpatialMetadataFormat> type)
                             throws InstantiationException,
                                    IllegalAccessException

Creates a builder for a metadata format of the given type. The given implementation class must have an accessible no-argument constructor.

Note: We do not provide a constructor accepting directly an instance, because it would provide a way to alter an already published SpatialMetadataFormat instance.

Parameters:

type - The type of the metadata format to instantiate.

Throws:

IllegalAccessException - If the class or its no-argument constructor is not accessible.

InstantiationException - If the instantiation fails.

Method Detail

substitutions

public Map<Class<?>,Class<?>> substitutions()

The map of children types to substitute by other types. This map is initially empty. Users can add or remove entries in this map before to invoke any addTree method.

If this map is non empty, then every occurrence of a class in the set of keys is replaced by the associated class in the collection of values. The purpose of this map is to:

• Replace a base class by some specialized subclass. Since IIOMetadata is about grided data (not generic Features), the exact subtype is often known at compile time, and we want the additional attributes to be declared unconditionally. Example:

  substitutions().put(RangeDimension.class, Band.class);

• Exclude a particular class by setting the replacement to null. This is used for excluding large tree of metadata which may not be applicable. Example:

  substitutions().put(Objective.class, null);

• Replace an element class (including the whole tree behind it) by a single attribute. This simplification is especially useful for Citation because they typically appear in many different places with the same name ("citation"), while Image I/O does not allow many elements to have the same name (actually this is not strictly forbidden, but the getter methods return information only about the first occurrence of a given name). Converting an element to an attribute allow it to appear with the same name under different nodes, and can make the tree considerably simpler (at the cost of losing all the sub-tree below the converted element). Example:

  substitutions().put(Citation.class, String.class);

• Replace a collection by a singleton, by setting the source type to an array and the target type to the element of that array. This is useful when a collection seems an overkill for the specific case of stream or image metadata. Example:

  substitutions().put(Identification[].class, Identification.class);

Returns:

The substitution map (never null).

addTree

public void addTree(MetadataStandard standard,
                    Class<?> type)

Adds a new optional element or attribute of the given type as a child of the root. This method performs the same work than addTree(MetadataStandard, Class, String, String, boolean), except that the element is added at the root and the name is inferred from the given type for convenience.

Parameters:

standard - The metadata standard of the element or attribute to be added.

type - The type of the element or attribute to be added.

addTree

public void addTree(MetadataStandard standard,
                    Class<?> type,
                    String elementName,
                    String parentName,
                    boolean mandatory)

Adds a new element or attribute of the given type and name as a child of the given node.

• If the given type is a metadata, then it is added as an element and all its children are added recursively.
• Otherwise the type is added as an attribute.

Element type
This method expects a type argument, which can be a CodeList subclass, one of the interfaces member of the given metadata standard, or a simple JSE type (boolean, number of String). Do not specify collection types, since the type of collection elements can not be inferred easily. To specify a multi-occurrence, use the array type instead (e.g. CoordinateSystemAxis[].class).

Substitution map
The substitution map applies only to children (if any), not to the type given directly to this method.

Parameters:

standard - The metadata standard of the element or attribute to be added.

type - The type of the element or attribute to be added (see javadoc).

elementName - The name of the element or attribute node to be added.

parentName - The name of the parent node to where to add the child.

mandatory - true if the element should be mandatory, or false if optional.

addTreeForISO19115

protected void addTreeForISO19115(String addToElement)

Adds the tree structure for an ISO-19115 metadata object. Warning: this tree is big and is supported only for a few plugins like NetcdfImageReader.

Parameters:

addToElement - The name of the element where to add the tree, or null for adding the tree at the root.

Since:

3.20

See Also:

SpatialMetadataFormat.ISO_FORMAT_NAME

addTreeForStream

public void addTreeForStream(String addToElement)

Adds the tree structure for stream metadata. The default implementation adds the tree structure documented in the "Stream metadata" column of the SpatialMetadataFormat javadoc.

Parameters:

addToElement - The name of the element where to add the tree, or null for adding the tree at the root.

See Also:

SpatialMetadataFormat.getStreamInstance(String)

addTreeForImage

public void addTreeForImage(String addToElement)

Adds the tree structure for image metadata. The default implementation adds the tree structure documented in the "Image metadata" column of the class javadoc.

The Coordinate Reference System branch is not included by this method. For including CRS information, the addTreeForCRS(String) method shall be invoked explicitly.

Parameters:

addToElement - The name of the element where to add the tree, or null for adding the tree at the root.

See Also:

SpatialMetadataFormat.getImageInstance(String)

addTreeForCRS

protected void addTreeForCRS(String addToElement)

Adds the tree structure for a Coordinate Reference System object.

Parameters:

addToElement - The name of the element where to add the tree, or null for adding the tree at the root.

build

public SpatialMetadataFormat build()

Returns the metadata format instance which has been build. This builder can not be used anymore after this method has been invoked.

Specified by:

build in class Builder<SpatialMetadataFormat>

Returns:

The metadata format instance.