| java.lang.Object org.geotools.coverage.io.MetadataBuilder
MetadataBuilder | public class MetadataBuilder (Code) | | Helper class for creating OpenGIS's object from a set of metadata. Metadata are
key-value pairs, for example
"Units=meters" . There is a wide
variety of ways to contruct OpenGIS's objects from key-value pairs, and
supporting them is not always straightforward. The
MetadataBuilder class
tries to make the work easier. It defines a set of format-neutral keys (i.e. keys not
related to any specific file format). Before parsing a file, the mapping between
format-neutral keys and "real" keys used in a particuler file format must
be specified. This mapping is constructed with calls to
MetadataBuilder.addAlias . For example,
one may want to parse the following informations:
XMinimum = 217904.31
YMaximum = 5663495.1
XResolution = 1000.0000
YResolution = 1000.0000
Units = meters
Projection = Mercator_1SP
Central meridian = -15.2167
Latitude of origin = 28.0667
False easting = 0.00000000
False northing = 0.00000000
Ellipsoid = Clarke 1866
Datum = Clarke 1866
Before to be used for parsing such informations, a
MetadataBuilder object
must be setup using the following code:
addAlias(
MetadataBuilder.X_MINIMUM , "XMinimum");
addAlias(
MetadataBuilder.Y_MAXIMUM , "YMaximum");
addAlias(
MetadataBuilder.X_RESOLUTION , "XResolution");
addAlias(
MetadataBuilder.Y_RESOLUTION , "YResolution");
// etc...
Once the mapping is etablished,
MetadataBuilder provides a set of
getXXX() methods for constructing various objects from those informations. For example, the
MetadataBuilder.getCoordinateReferenceSystem method constructs a
CoordinateReferenceSystem object using available informations.
version: $Id: MetadataBuilder.java 25699 2007-05-31 15:55:07Z desruisseaux $ author: Martin Desruisseaux since: 2.2 |
Inner Class :public static class Key implements Serializable | |
Field Summary | |
final public static Key | CENTRAL_MERIDIAN Key for the
"central_meridian" projection parameter. | final public static Key | COORDINATE_REFERENCE_SYSTEM Key for the
. | final public static Key | DATUM Key for the coordinate reference system's
. | final public static Key | DEPTH Key for the image's "depth" in pixels. | final public static Key | ELLIPSOID Key for the coordinate reference system
. | final public static Key | FALSE_EASTING Key for the
"false_easting" projection parameter. | final public static Key | FALSE_NORTHING Key for the
"false_northing" projection parameter. | final public static Key | HEIGHT Key for the image's height in pixels. | final public static Key | LATITUDE_OF_ORIGIN Key for the
"latitude_of_origin" projection parameter. | final public static Key | OPERATION_METHOD Key for the
. | final public static Key | PROJECTION Key for the
. | final public static Key | SEMI_MAJOR Key for the
"semi_major" projection parameter. | final public static Key | SEMI_MINOR Key for the
"semi_minor" projection parameter. | final public static Key | UNITS Key for the
units.
The
MetadataBuilder.getUnit method looks for this metadata. | final public static Key | WIDTH Key for the image's width in pixels. | final public static Key | X_MAXIMUM Key for the maximal x value (eastern limit). | final public static Key | X_MINIMUM Key for the minimal x value (western limit). | final public static Key | X_RESOLUTION Key for the resolution among the x axis. | final public static Key | Y_MAXIMUM Key for the maximal y value (northern limit). | final public static Key | Y_MINIMUM Key for the minimal y value (southern limit).
This is usually the latitude coordinate of the bottom right corner.
The
MetadataBuilder.getEnvelope method looks for this metadata. | final public static Key | Y_RESOLUTION Key for the resolution among the y axis. | final public static Key | Z_MAXIMUM Key for the maximal z value. | final public static Key | Z_MINIMUM Key for the minimal z value. | final public static Key | Z_RESOLUTION Key for the resolution among the z axis. |
Constructor Summary | |
public | MetadataBuilder() Constructs a new
MetadataBuilder using default factories. | public | MetadataBuilder(FactoryGroup factories) Constructs a new
MetadataBuilder using the specified factories. |
Method Summary | |
public synchronized void | add(GridCoverage coverage) Add all metadata from the specified grid coverage. | public synchronized void | add(RenderedImage image) Add all metadata from the specified image. | public synchronized void | add(PropertySource properties, String prefix) Add metadata from the specified property source.
Parameters: properties - The properties source. Parameters: prefix - The prefix for properties to add, of null to addall properties. | public synchronized void | add(String alias, Object value) Add a metadata for the specified key. | public synchronized void | addAlias(Key key, String alias) Add an alias to a key. | public synchronized void | clear() Clears this metadata set. | public synchronized boolean | contains(Key key) Checks if this
MetadataBuilder contains a value for the specified key.
Invoking
MetadataBuilder.get will thrown a
MissingMetadataException if and only
if
MetadataBuilder.contains returns
false for the same key.
Parameters: key - The key to test for inclusion in this MetadataBuilder . | public synchronized Object | get(Key key) Returns the metadata for the specified key. | public synchronized String[] | getAlias(Key key) Returns the list of alias for the specified key, or
null if the key has no alias. | public synchronized Date | getAsDate(Key key) Returns a metadata as a
Date value. | public synchronized double | getAsDouble(Key key) Returns a metadata as a
double value. | public synchronized int | getAsInt(Key key) Returns a metadata as a
int value. | public synchronized CoordinateReferenceSystem | getCoordinateReferenceSystem() Returns the coordinate reference system. | public synchronized Ellipsoid | getEllipsoid() Returns the ellipsoid. | public synchronized Envelope | getEnvelope() Returns the envelope. | public String | getFormatPattern(Class type) Returns the pattern used for parsing and formatting values of the specified type.
The type should be either
Number.class or
Date.class .
- if
type is assignable to
Number.class , then this method
returns the number pattern as specified by
DecimalFormat .
- Otherwise, if
type is assignable to
Date.class , then this method
returns the date pattern as specified by
SimpleDateFormat .
In any case, this method returns
null if this object should use the default
pattern for the
.
Parameters: type - The data type ( Number.class or Date.class ). | public synchronized GeodeticDatum | getGeodeticDatum() Returns the geodetic datum. | public synchronized GeographicBoundingBox | getGeographicBoundingBox() Convenience method returning the envelope in geographic coordinate system using WGS
1984 datum.
throws: MetadataException - if the operation failed. | public synchronized GridRange | getGridRange() Returns the grid range. | public Locale | getLocale() Returns the locale to use when parsing metadata values as numbers, angles or dates. | public synchronized Conversion | getProjection() Returns the projection. | public GridSampleDimension[] | getSampleDimensions() Returns the sample dimensions for each band of the
GridCoverage to be read. | public String | getSeparator() Returns the characters to use as separator between keys and values. | public String | getSource() Returns the source file name or URL. | public synchronized Unit | getUnit() Returns the units. | public synchronized void | listMetadata(Writer out) List all metadata to the specified stream. | public synchronized void | load(File header) Reads all metadata from a text file. | public synchronized void | load(URL header) Reads all metadata from an URL. | protected void | load(BufferedReader in) Reads all metadata from a stream. | protected boolean | parseLine(String line) Parses a line and add the key-value pair to this metadata set. | public synchronized void | setFormatPattern(Class type, String pattern) Set the pattern to use for parsing and formatting values of the specified type. | public synchronized void | setSeparator(String separator) Set the characters to use as separator between keys and values. | final synchronized void | setUserLocale(Locale locale) Sets the current
Locale of this
MetadataBuilder to the given value. | public String | toString() Returns a string representation of this metadata set. | static String | trim(String str, String separator) Trim a character string. |
MetadataBuilder | public MetadataBuilder()(Code) | | Constructs a new
MetadataBuilder using default factories.
|
MetadataBuilder | public MetadataBuilder(FactoryGroup factories)(Code) | | Constructs a new
MetadataBuilder using the specified factories.
|
add | public synchronized void add(GridCoverage coverage) throws AmbiguousMetadataException(Code) | | Add all metadata from the specified grid coverage. This method can be used together with
MetadataBuilder.listMetadata as a way to format the metadata for an arbitrary grid coverage.
The default implementation performs the following step:
|
addAlias | public synchronized void addAlias(Key key, String alias) throws AmbiguousMetadataException(Code) | | Add an alias to a key. After this method has been invoked, calls to
MetadataBuilder.get get (key) will really looks for metadata named
alias .
Alias are mandatory in order to get various
getXXX() methods to work for a
particular file format.
For example if the file to be parsed uses the names
"ULX" and
"ULY" for the
coordinate of the upper left corner, then the
MetadataBuilder.getEnvelope method will not work
unless the following alias are set:
addAlias(
, "ULX");
addAlias(
, "ULY");
An arbitrary number of alias can be set for the same key. For example,
addAlias(Y_MAXIMUM, ...) could be invoked twice with
"ULY" and
"Limit North" alias. The
getXXX() methods will try alias in the order they
were added and use the first value found.
The same alias can also be set to more than one key. For example, the following code is
legal. It means that pixel are square with the same horizontal and vertical resolution:
addAlias(
, "Resolution");
addAlias(
, "Resolution");
Parameters: key - The key to add an alias. This key is format neutral. Parameters: alias - The alias to add. This is the name actually used in the file to be parsed.Alias are case insensitive and ignore multiple whitespace, like keys. Ifthis alias is already bound to the specified key, then this method do nothing. throws: AmbiguousMetadataException - if the addition of the supplied aliaswould introduce an ambiguity in the current set of metadata.This occurs if the key has already an alias mapping to a different value. See Also: MetadataBuilder.getAlias See Also: MetadataBuilder.contains See Also: MetadataBuilder.get |
clear | public synchronized void clear()(Code) | | Clears this metadata set. If the same
MetadataBuilder object is used for parsing
many files, then
clear() should be invoked prior any
load(...) method.
Note that
clear() do not remove any alias, so this
MetadataBuilder can
been immediately reused for parsing new files of the same kind.
|
getAlias | public synchronized String[] getAlias(Key key)(Code) | | Returns the list of alias for the specified key, or
null if the key has no alias. Alias are the names used in the underlying
metadata file, and are format dependent.
Parameters: key - The format neutral key. The alias for the specified key, or null if none. See Also: MetadataBuilder.addAlias |
getFormatPattern | public String getFormatPattern(Class type)(Code) | | Returns the pattern used for parsing and formatting values of the specified type.
The type should be either
Number.class or
Date.class .
- if
type is assignable to
Number.class , then this method
returns the number pattern as specified by
DecimalFormat .
- Otherwise, if
type is assignable to
Date.class , then this method
returns the date pattern as specified by
SimpleDateFormat .
In any case, this method returns
null if this object should use the default
pattern for the
.
Parameters: type - The data type ( Number.class or Date.class ). The format pattern for the specified data type, or null forthe default locale-dependent pattern. throws: IllegalArgumentException - if type is not valid. |
getProjection | public synchronized Conversion getProjection() throws MetadataException(Code) | | Returns the projection. The default implementation performs the following steps:
- Gets the projection classification with
(
) , or with
(
) if no value were
defined for the former.
- Gets the list of projection parameters for the above classification.
- Gets the metadata values for each parameters in the above step. If a parameter is not
defined in this
MetadataBuilder , then it will be left to its (projection
dependent) default value. Parameters are projection dependent, but will typically
include
"semi_major" ,
"semi_minor" ,
"central_meridian" ,
"latitude_of_origin" ,
"false_easting" and
"false_northing" .
The names actually used in the metadata file to be parsed must be declared as usual,
e.g.
(
, ...)
- If no value was defined for
"semi-major" and/or
"semi-minor" parameters, then invokes
MetadataBuilder.getEllipsoid and uses its semi-axis length.
- If a value exists for the optional key
MetadataBuilder.PROJECTION , then takes it as
the projection name. The projection name is for documentation purpose only and do
not affect any computation. If there is no value for
MetadataBuilder.PROJECTION , then
the projection name will be the same than the operation method name (the first step
above).
The projection. throws: MissingMetadataException - if no value exists for the MetadataBuilder.PROJECTION or theMetadataBuilder.OPERATION_METHOD keys. throws: MetadataException - if the operation failed for some other reason(for example if a parameter value can't be parsed as a double ). See Also: MetadataBuilder.getCoordinateReferenceSystem See Also: MetadataBuilder.SEMI_MAJOR See Also: MetadataBuilder.SEMI_MINOR See Also: MetadataBuilder.LATITUDE_OF_ORIGIN See Also: MetadataBuilder.CENTRAL_MERIDIAN See Also: MetadataBuilder.FALSE_EASTING See Also: MetadataBuilder.FALSE_NORTHING |
getSampleDimensions | public GridSampleDimension[] getSampleDimensions() throws MetadataException(Code) | | Returns the sample dimensions for each band of the
GridCoverage to be read. If sample dimensions are not know, then this method returns
null . The default implementation always returns
null .
throws: MetadataException - if the operation failed. |
getSource | public String getSource() throws MetadataException(Code) | | Returns the source file name or URL. This is the path specified
during the last call to a
load(...) method.
The source file name or URL. throws: MetadataException - if this information can't be fetched. #load(File) #load(URL) |
listMetadata | public synchronized void listMetadata(Writer out) throws IOException(Code) | | List all metadata to the specified stream. The default implementation list the
metadata as key = value pairs. Each pair is formatted on
its own line, and the caracter '=' is inserted between keys and values.
A question mark ('?' ) is put in front of any unknow name (i.e. any name
not specified with
MetadataBuilder.addAlias ).
Parameters: out - Stream to write metadata to. throws: IOException - if an error occured while listing metadata. See Also: MetadataBuilder.add(GridCoverage) See Also: MetadataBuilder.toString() |
parseLine | protected boolean parseLine(String line) throws IIOException(Code) | | Parses a line and add the key-value pair to this metadata set. The default implementation
takes the substring on the left side of the first occurence of the
(usually the '=' character) as the key, and the substring on the right side of
the separator as the value. For example, if
line has the following value:
Ellipsoid = WGS 1984
Then, the default implementation will translate this line in
the following call:
MetadataBuilder.add(String,Object) add ("Ellipsoid", "WGS 1984");
This method returns
true if it has consumed the line, or
false otherwise.
A line is "consumed" if
parseLine(...) has either added the key-value pair (using
MetadataBuilder.add ), or determined that the line must be ignored (for example because
parseLine(...) detected a character announcing a comment line). A "consumed" line
will not receive any further treatment. The line is not consumed (i.e. this method returns
false ) if
parseLine(...) don't know what to do with it. Non-consumed line
will typically go up in a chain of
parseLine(...) methods (if
MetadataBuilder has been subclassed) until someone consume it.
Parameters: line - The line to parse. true if this method has consumed the line. throws: IIOException - if the line is badly formatted. throws: AmbiguousMetadataException - if a different value was already defined for the samemetadata name. See Also: MetadataBuilder.load(File) See Also: MetadataBuilder.load(URL) See Also: MetadataBuilder.add(String,Object) |
setFormatPattern | public synchronized void setFormatPattern(Class type, String pattern)(Code) | | Set the pattern to use for parsing and formatting values of the specified type.
The type should be either
Number.class or
Date.class .
- If
type is assignable to
.class ,
then
pattern should be a
DecimalFormat pattern (example:
"#0.###" ).
- If
type is assignable to
.class ,
then
pattern should be a
SimpleDateFormat pattern
(example:
"yyyy/MM/dd HH:mm" ).
Parameters: type - The data type ( Number.class or Date.class ). Parameters: pattern - The format pattern for the specified data type, or null for the default locale-dependent pattern. throws: IllegalArgumentException - if type is not valid. |
setSeparator | public synchronized void setSeparator(String separator)(Code) | | Set the characters to use as separator between keys and values.
|
setUserLocale | final synchronized void setUserLocale(Locale locale)(Code) | | Sets the current
Locale of this
MetadataBuilder to the given value. A value of
null removes any previous
setting, and indicates that the parser should localize as it sees fit.
Note: this is the locale to use for formatting error messages,
not the locale to use for parsing the file. The locale for parsing is specified
by
MetadataBuilder.getLocale .
|
trim | static String trim(String str, String separator)(Code) | | Trim a character string. Leading and trailing spaces are removed. Any succession of
one ore more unicode whitespace characters (as of
Character.isSpaceChar(char) are replaced by a single '_' character. Example:
"This is a test"
will be returned as "This_is_a_test"
Parameters: str - The string to trim (may be null ). Parameters: separator - The separator to insert in place of succession of whitespaces.Usually "_" for keys and " " for values. The trimed string, or null if str was null. |
|
|