org.geotoolkit.image.io.metadata
Class ReferencingBuilder

Object
  Builder<CoordinateReferenceSystem>
      ReferencingBuilder

public class ReferencingBuilder
extends Builder<CoordinateReferenceSystem>

Builds referencing objects from an IIOMetadata object. This class uses a MetadataAccessor for reading and writing the attribute values in the IIOMetadata object given at construction time. By default, this class uses an accessor for the "RectifiedGridDomain/CoordinateReferenceSystem" node of the "geotk-coverageio_3.07" format. However a different accessor can be given to the constructor.

Note: This class exists because we do not use the reflection mechanism like what we do for ISO 19115-2 metadata. Dedicated code is needed because the mapping between Image I/O metadata and the referencing objects is more indirect. For example the kind of object to create depends on the value of the "type" attribute.

The main methods in this class are build() for reading, and setCoordinateReferenceSystem(...) for writing. The other getter methods are provided mostly as hooks that subclasses can override. The table below summarizes them:

Class	Getter	Setter
CoordinateReferenceSystem	build()
CoordinateReferenceSystem	getCoordinateReferenceSystem(Class)	setCoordinateReferenceSystem(CoordinateReferenceSystem)
CoordinateSystem	getCoordinateSystem(Class)	setCoordinateSystem(CoordinateSystem)
Datum	getDatum(Class)	setDatum(Datum)
Ellipsoid	getEllipsoid(MetadataAccessor)
PrimeMeridian	getPrimeMeridian(MetadataAccessor)

Since:

3.08 (derived from 3.07)

Version:

3.20

Author:

Martin Desruisseaux (Geomatys)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Constructor Summary

ReferencingBuilder(IIOMetadata metadata)
Creates a new metadata helper for the given metadata.

ReferencingBuilder(MetadataAccessor accessor)
Creates a new metadata helper using the given accessor.

Method Summary

CoordinateReferenceSystem	build() Returns the coordinate reference system, or null if it can not be created.
protected MetadataAccessor	createMetadataAccessor(MetadataAccessor parent, String path, String childPath) Creates the accessor for a child element.
<T extends CoordinateReferenceSystem> T	getCoordinateReferenceSystem(Class<T> baseType) Gets the coordinate reference system.
<T extends CoordinateSystem> T	getCoordinateSystem(Class<T> baseType) Gets the coordinate system.
<T extends Datum> T	getDatum(Class<T> baseType) Gets the datum.
protected <T extends IdentifiedObject> T	getDefault(Class<T> type) Returns a default object of the given class.
protected Ellipsoid	getEllipsoid(MetadataAccessor datumAccessor) Gets the ellipsoid.
boolean	getIgnoreUserObject() Returns true if this helper class should not get or set the User Object node property.
CoordinateReferenceSystem	getOptionalCRS() Deprecated. Renamed build().
protected PrimeMeridian	getPrimeMeridian(MetadataAccessor datumAccessor) Gets the prime meridian.
void	setCoordinateReferenceSystem(CoordinateReferenceSystem crs) Sets the coordinate reference system to the given value.
void	setCoordinateSystem(CoordinateSystem cs) Sets the coordinate system to the given value.
void	setDatum(Datum datum) Sets the datum to the given value.
void	setIgnoreUserObject(boolean ignore) Sets whatever this helper class is allowed to get or set the User Object node property.

Methods inherited from class Object

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

Constructor Detail

ReferencingBuilder

public ReferencingBuilder(IIOMetadata metadata)
                   throws NoSuchElementException

Creates a new metadata helper for the given metadata.

Parameters:

metadata - The Image I/O metadata. An instance of the SpatialMetadata sub-class is recommended, but not mandatory.

Throws:

NoSuchElementException - If the underlying IIOMetadata is read only and doesn't contains a node for the element to fetch.

ReferencingBuilder

public ReferencingBuilder(MetadataAccessor accessor)

Creates a new metadata helper using the given accessor. Accessors for child elements will be derived from the given accessor. Subclasses can control the name of child elements by overriding the createMetadataAccessor method.

Parameters:

accessor - The accessor to the Coordinate Reference System node.

Method Detail

getIgnoreUserObject

public boolean getIgnoreUserObject()

Returns true if this helper class should not get or set the User Object node property. The default value is false, in which case:

• Every call to a setter method in this ReferencingBuilder class will set the user object to the given value, if possible.
• Every call to a getter method in this ReferencingBuilder class will get the user object and return it if it exist.

If this method returns true, then the above steps are skipped. This implies that every call to a getter method will create a new object from the values declared in node attributes.

Returns:

true if user objects should be ignored.

Since:

3.09

See Also:

IIOMetadataNode.getUserObject(), MetadataAccessor.getUserObject()

setIgnoreUserObject

public void setIgnoreUserObject(boolean ignore)

Sets whatever this helper class is allowed to get or set the User Object node property. See getIgnoreUserObject() for more information.

Parameters:

ignore - true if user objects should be ignored.

Since:

3.09

build

public CoordinateReferenceSystem build()

Returns the coordinate reference system, or null if it can not be created. This method delegates to getCoordinateReferenceSystem(Class) and catch the exception. If an exception has been thrown, the exception is logged and this method returns null.

Specified by:

build in class Builder<CoordinateReferenceSystem>

Returns:

The CRS, or null if none.

Since:

3.20 (derived from 3.07)

getOptionalCRS

@Deprecated
public CoordinateReferenceSystem getOptionalCRS()

Deprecated. Renamed build().

getCoordinateReferenceSystem

public <T extends CoordinateReferenceSystem> T getCoordinateReferenceSystem(Class<T> baseType)
                                                                 throws FactoryException

Gets the coordinate reference system. If no CRS is explicitly defined, then a warning is logged and a default CRS is returned, which is null in the default implementation.

Type Parameters:

T - The compile-time type of baseType.

Parameters:

baseType - The expected CRS type.

Returns:

The coordinate reference system, or null if the CRS can not be parsed and there is no default value.

Throws:

FactoryException - If the coordinate reference system can not be created.

setCoordinateReferenceSystem

public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs)

Sets the coordinate reference system to the given value.

Parameters:

crs - The coordinate reference system.

TODO:

The base CRS is not yet declared for the DerivedCRS case.

getCoordinateSystem

public <T extends CoordinateSystem> T getCoordinateSystem(Class<T> baseType)
                                               throws FactoryException

Gets the coordinate system. If no coordinate system is explicitly defined, then a warning is logged and a default coordinate system is returned, which is DefaultEllipsoidalCS.GEODETIC_2D, DefaultCartesianCS.GENERIC_2D or null (depending on the baseType argument) in the default implementation.

Type Parameters:

T - The compile-time type of baseType.

Parameters:

baseType - The expected coordinate system type.

Returns:

The coordinate system, or null if the coordinate system can not be parsed and there is no default value.

Throws:

FactoryException - If the coordinate system can not be created.

setCoordinateSystem

public void setCoordinateSystem(CoordinateSystem cs)

Sets the coordinate system to the given value.

Parameters:

cs - The coordinate system, or null if none.

getDatum

public <T extends Datum> T getDatum(Class<T> baseType)
                         throws FactoryException

Gets the datum. If no datum is explicitly defined, then a warning is logged and a default datum is returned, which is DefaultGeodeticDatum.WGS84 in the default implementation.

Type Parameters:

T - The compile-time type of baseType.

Parameters:

baseType - The expected datum type.

Returns:

The datum, or null if the datum can not be parsed and there is no default value.

Throws:

FactoryException - If the datum can not be created.

TODO:

VerticalDatum, TemporalDatum and ImageDatum are not yet implemented.

setDatum

public void setDatum(Datum datum)

Sets the datum to the given value.

Parameters:

datum - The datum, or null if none.

getEllipsoid

protected Ellipsoid getEllipsoid(MetadataAccessor datumAccessor)
                          throws FactoryException

Gets the ellipsoid. If no ellipsoid is explicitly defined, then a warning is logged and a default ellipsoid is returned, which is DefaultEllipsoid.WGS84 in the default implementation.

Parameters:

datumAccessor - The accessor of the datum enclosing the ellipsoid.

Returns:

The ellipsoid, or null if the ellipsoid can not be parsed and there is no default value.

Throws:

FactoryException - If the ellipsoid can not be created.

getPrimeMeridian

protected PrimeMeridian getPrimeMeridian(MetadataAccessor datumAccessor)
                                  throws FactoryException

Gets the prime meridian. If no prime meridian is explicitly defined, then a warning is logged and a default prime meridian is returned, which is DefaultPrimeMeridian.GREENWICH in the default implementation.

Parameters:

datumAccessor - The accessor of the datum enclosing the prime meridian.

Returns:

The prime meridian, or null if the prime meridian can not be parsed and there is no default value.

Throws:

FactoryException - If the prime meridian can not be created.

getDefault

protected <T extends IdentifiedObject> T getDefault(Class<T> type)
                                         throws FactoryException

Returns a default object of the given class. This method is invoked automatically when the object was not explicitly defined in the metadata, or can not be parsed.

The default implementation delegates to SpatialMetadataFormat.getDefaultValue(Class) for every types except CoordinateReferenceSystem. The later method is preferred to IIOMetadataFormat.getObjectDefaultValue(String) because the default value may depend on the "type" attribute in the enclosing element. For example if the CRS type is "geographic", then the default coordinate system shall be a EllipsoidalCS. But if the CRS type is "projected" instead, then the default coordinate system shall rather be a CartesianCS.

Subclasses can override this method if they want to provide different default values.

Type Parameters:

T - The compile-time type of the type argument.

Parameters:

type - The type of the object to be returned.

Returns:

The default object of the given type, or null if none.

Throws:

FactoryException - If the default object can not be created.

See Also:

SpatialMetadataFormat.getDefaultValue(Class), IIOMetadataFormat.getObjectDefaultValue(String)

createMetadataAccessor

protected MetadataAccessor createMetadataAccessor(MetadataAccessor parent,
                                                  String path,
                                                  String childPath)

Creates the accessor for a child element. This method is invoked automatically when a new accessor needs to be created for a child element, for example the "Datum" element inside the "CoordinateReferenceSystem" element.

The default implementation is implemented as below:

return new MetadataAccessor(parent, path, childPath);

Subclasses can override this method in order to create different accessors, for example in order to use different names for the child elements.

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.

Returns:

The accessor to use.

See Also:

MetadataAccessor.MetadataAccessor(MetadataAccessor, String, String)