Package org.apache.sis.storage.landsat

Class MetadataReader

java.lang.Object

org.apache.sis.internal.storage.MetadataBuilder

org.apache.sis.storage.landsat.MetadataReader

final class MetadataReader
extends MetadataBuilder

Parses Landsat metadata as ISO 19115 Metadata object. This class reads the content of a given BufferedReader from buffer position until the first occurrence of the END keyword. Lines beginning with the # character (ignoring spaces) are treated as comment lines and ignored.

This class will parse properties found in the Landsat metadata file, except GROUP and END_GROUP. Example:

NOTE FOR MAINTAINER: if the work performed by this class is modified, consider updating ./doc-files/MetadataMapping.html accordingly.

Since:

0.8

Version:

1.1

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.sis.internal.storage.MetadataBuilder

MetadataBuilder.GridType, MetadataBuilder.PartyType, MetadataBuilder.Scope

Field Summary

Fields

Modifier and Type	Field	Description
private static final String	BAND_SUFFIX	The "_BAND" suffix added to attribute names that are followed by a band number.
private final BandName[]	bandEnumerations	BandName.values(), fetched once for avoiding multiple array creations.
(package private) final EnumMap<BandName,Band>	bands	The bands descriptions.
private final double[]	corners	Projected and geographic coordinate values, stocked temporarily before to be saved in the extent.
(package private) static final Pattern	CREDIT	The pattern determining if the value of ORIGIN key is of the form “Image courtesy of the U.S.
private CommonCRS	datum	The enumeration for the "DATUM" element, to be used for creating the Coordinate Reference System.
private static final String	END	The keyword for end of metadata file.
private final ReferencingFactoryContainer	factories	The referencing objects factories.
private String	filename	An identifier of the file being read, or null if unknown.
private static final int	GEOGRAPHIC	Index of projected and geographic coordinates in the corners array.
private final EnumMap<BandGroupName,Dimension>	gridSizes	Image width and height in pixels, as unsigned integers.
private String	group	Group in process of being parsed, or null if none.
private static final String	LINEAGE_SUFFIX	Suffix of groups that describe the processing done on the data instead of the data themselves.
private String	lineageGroup	The last group where we fetched lineage (history) information.
private final StoreListeners	listeners	Where to send the warnings.
private static final int	NUM_COORDINATES	Number of coordinates for the corners in a CRS type (geographic or projected).
private static final int	PROJECTED	Index of projected and geographic coordinates in the corners array.
private org.opengis.parameter.ParameterValueGroup	projection	The map projection parameters.
private Temporal	sceneTime	The acquisition time, or null if not yet known.
private final LandsatStore	store	The store for which metadata are read.
private short	utmZone	The Universal Transverse Mercator (UTM) zone as a number from 1 to 60 inclusive, or 0 if the zone has not yet been determined.

Constructor Summary

Constructors

Constructor	Description
MetadataReader(LandsatStore store, String filename, StoreListeners listeners)	Creates a new metadata parser.

Method Summary

Modifier and Type	Method	Description
private Optional<Band>	band(String key, int index)	Returns the band at the given index, creating it if needed.
private Errors	errors()	Returns the resources to use for formatting error messages.
private void	flushSceneTime()	Writes the value of sceneTime into the metadata object as a temporal extent.
private String	getFilename()	Returns the filename to show in error messages, or a localized "unnamed" word if none.
(package private) final org.opengis.metadata.Metadata	getMetadata()	Returns the metadata about the resources described in the Landsat file.
private void	parseCorner(int index, String value)	Parses the given value and stores it at the given index in the corners array.
private Double	parseDouble(String value)	Parses the given string as a double value, returning a shared instance if possible.
private void	parseGridSize(BandGroupName group, boolean isX, String value)	Parses the given value and stores it in the gridSizes map.
private void	parseKeyValuePair(String key, int band, String value)	Invoked for every key-value pairs found in the file for the main groups.
private void	parseLineage(String key, int band, String value)	Invoked for every key-value pairs found in a lineage group.
(package private) void	read(BufferedReader reader)	Parses the metadata from the given characters reader.
private Optional<DefaultSampleDimension>	sampleDimension(String key, int index)	Returns metadata about sample dimension at the given index.
private void	setProjectionParameter(String key, String name, String value, boolean isLinear)	Sets a map projection parameter.
private void	setTransferFunction(String key, int band, boolean reflectance, boolean isScale, String value)	Sets a component of the linear transfer function.
private boolean	toBoundingBox(int base)	Computes the bounding box for the 8 corners values starting at the given index.
private String	toLongName(String key)	Prepends the group name before the given key, if a group name exists.
private void	warning(String key, BufferedReader reader, Exception e)	Invoked when a non-fatal exception occurred while reading metadata.

Methods inherited from class org.apache.sis.internal.storage.MetadataBuilder

addAbstract, addAccessConstraint, addAcquisitionOperation, addAcquisitionRequirement, addAcquisitionTime, addAcquisitionTime, addAuthor, addBandDescription, addBandName, addBoundingPolygon, addCitationDate, addCitedResponsibleParty, addCompleteMetadata, addCompression, addContentType, addControlPoints, addCredits, addDefaultMetadata, addDefaultMetadata, addDefaultMetadata, addDistributor, addEdition, addEncoding, addExtent, addExtent, addExtent, addFeatureType, addFeatureType, addFormatName, addFromComponent, addGeolocation, addHostComputer, addIdentifier, addIdentifier, addInstrument, addKeywords, addLanguage, addLineage, addMaximumSampleValue, addMinimumSampleValue, addNewBand, addOtherCitationDetails, addPage, addPage, addPlatform, addPointOfContact, addProcessDescription, addProcessing, addPurpose, addReferenceSystem, addResolution, addResourceScope, addSampleValueDescription, addSeries, addSoftwareReference, addSource, addSource, addSource, addSpatialRepresentation, addSpatialRepresentation, addSupplementalInformation, addTemporalExtent, addTitle, addTitleOrIdentifier, addTopicCategory, addUseLimitation, addVerticalExtent, build, buildAndFreeze, hasSampleValueRange, mergeMetadata, newAcquisition, newCoverage, newDistribution, newFeatureTypes, newGridRepresentation, newIdentification, newLineage, newParty, newSampleDimension, parseLegalNotice, setAxisName, setAxisResolution, setAxisSize, setBandIdentifier, setBandIdentifier, setBitPerSample, setCellGeometry, setCloudCoverPercentage, setFormatEdition, setGeoreferencingAvailability, setGridToCRS, setIlluminationAzimuthAngle, setIlluminationElevationAngle, setISOStandards, setPointInPixel, setPredefinedFormat, setProcessingLevelCode, setSampleUnits, setTransferFunction, shared, shared

Methods inherited from class java.lang.Object

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

Field Details

CREDIT

static final Pattern CREDIT

The pattern determining if the value of ORIGIN key is of the form “Image courtesy of the U.S. Geological Survey”.

LINEAGE_SUFFIX

private static final String LINEAGE_SUFFIX

Suffix of groups that describe the processing done on the data instead of the data themselves.

See Also:

• Constant Field Values

BAND_SUFFIX

private static final String BAND_SUFFIX

The "_BAND" suffix added to attribute names that are followed by a band number. This band suffix is itself followed by the '_' character, then the band number. Example: "REFLECTANCE_ADD_BAND_1".

See Also:

• Constant Field Values

END

private static final String END

The keyword for end of metadata file.

See Also:

• Constant Field Values

store

private final LandsatStore store

The store for which metadata are read.

listeners

private final StoreListeners listeners

Where to send the warnings.

filename

private String filename

An identifier of the file being read, or null if unknown. This is used mostly for formatting error messages.

See Also:

• getFilename()

group

private String group

Group in process of being parsed, or null if none.

lineageGroup

private String lineageGroup

The last group where we fetched lineage (history) information. The same file may contain many lineage groups.

See Also:

• parseLineage(String, int, String)

sceneTime

private Temporal sceneTime

The acquisition time, or null if not yet known. This needs to be parsed in two steps: first by parsing the "DATE_ACQUIRED" attribute, then "SCENE_CENTER_TIME".

See Also:

• flushSceneTime()

corners

private final double[] corners

Projected and geographic coordinate values, stocked temporarily before to be saved in the extent. Values are in (x,y) or (lon,lat) order. The first 8 values are the projected ones. The next 8 values are the geographic ones. Corner order is UL, UR, LL, LR.

NUM_COORDINATES

private static final int NUM_COORDINATES

Number of coordinates for the corners in a CRS type (geographic or projected). This is 4 corners multiplied by the number of dimensions, which is 2.

See Also:

• Constant Field Values

PROJECTED

private static final int PROJECTED

Index of projected and geographic coordinates in the corners array. Each kind of coordinates are stored as 4 corners of coordinate values.

See Also:

• Constant Field Values

GEOGRAPHIC

private static final int GEOGRAPHIC

Index of projected and geographic coordinates in the corners array. Each kind of coordinates are stored as 4 corners of coordinate values.

See Also:

• Constant Field Values

gridSizes

private final EnumMap<BandGroupName,Dimension> gridSizes

Image width and height in pixels, as unsigned integers. Values are (width,height) tuples. Tuples in this array are for #PANCHROMATIC, #REFLECTIVE or #THERMAL bands, in that order.

bands

final EnumMap<BandName,Band> bands

The bands descriptions. The bands can be, in this exact order:

1. Coastal Aerosol
2. Blue
3. Green
4. Red
5. Near-Infrared
6. Short Wavelength Infrared (SWIR) 1
7. Short Wavelength Infrared (SWIR) 2
8. Panchromatic
9. Cirrus
10. Thermal Infrared Sensor (TIRS) 1
11. Thermal Infrared Sensor (TIRS) 2

See Also:

• band(String, int)

bandEnumerations

private final BandName[] bandEnumerations

BandName.values(), fetched once for avoiding multiple array creations.

datum

private CommonCRS datum

The enumeration for the "DATUM" element, to be used for creating the Coordinate Reference System.

utmZone

private short utmZone

The Universal Transverse Mercator (UTM) zone as a number from 1 to 60 inclusive, or 0 if the zone has not yet been determined. If the parser determined that the projection is Polar Stereographic, then this field is set to -1.

projection

private org.opengis.parameter.ParameterValueGroup projection

The map projection parameters. This is used only for the polar stereographic case.

factories

private final ReferencingFactoryContainer factories

The referencing objects factories.

Constructor Details

MetadataReader

MetadataReader(LandsatStore store,
 String filename,
 StoreListeners listeners)

Creates a new metadata parser.

Parameters:

store - the store for which metadata are read.

filename - an identifier of the file being read, or null if unknown.

listeners - where to sent warnings that may occur during the parsing process.

Method Details

read

void read(BufferedReader reader)
   throws IOException,
DataStoreException

Parses the metadata from the given characters reader. The parsing stop after the first "END" keyword. See class javadoc for more information on the expected format.

Parameters:

reader - a reader opened on the Landsat file. It is caller's responsibility to close this reader.

Throws:

IOException - if an I/O error occurred while reading the given stream.

DataStoreException - if the content is not a Landsat file.

parseDouble

private Double parseDouble(String value)
                    throws NumberFormatException

Parses the given string as a double value, returning a shared instance if possible.

Parameters:

value - the string value to parse.

Returns:

the parsed value.

Throws:

NumberFormatException - if the given value cannot be parsed.

parseCorner

private void parseCorner(int index,
 String value)
                  throws NumberFormatException

Parses the given value and stores it at the given index in the corners array. The given index must be one of the PROJECTED or GEOGRAPHIC constants plus the coordinate index.

Throws:

NumberFormatException

parseGridSize

private void parseGridSize(BandGroupName group,
 boolean isX,
 String value)
                    throws NumberFormatException

Parses the given value and stores it in the gridSizes map.

Parameters:

value - the value to parse.

Throws:

NumberFormatException

parseKeyValuePair

private void parseKeyValuePair(String key,
 int band,
 String value)
                        throws IllegalArgumentException,
DateTimeException,
DataStoreException

Invoked for every key-value pairs found in the file for the main groups. A mean group is any group other than lineage. Leading and trailing spaces, if any, have been removed from given argument.

Parameters:

key - the key in upper cases.

band - the band number, or 0 if none.

value - the value, without quotes if those quotes existed.

Throws:

NumberFormatException - if the value was expected to be a string but the parsing failed.

DateTimeException - if the value was expected to be a date but the parsing failed, or if the result of the parsing was not of the expected type.

IllegalArgumentException - if the value is out of range.

DataStoreException

parseLineage

private void parseLineage(String key,
 int band,
 String value)

Invoked for every key-value pairs found in a lineage group. This method does a work similar to parseKeyValuePair(String, int, String) except that the result is stored in a section about data history. Note that the file can contains many distinct lineage sections.

setTransferFunction

private void setTransferFunction(String key,
 int band,
 boolean reflectance,
 boolean isScale,
 String value)

Sets a component of the linear transfer function.

Parameters:

key - the key without its band number. Used only for formatting warning messages.

band - index of the band to set.

reflectance - true if the parameter is about reflectance instead of radiance.

isScale - true for setting the scale factor, or false for setting the offset.

value - the value to set.

band

private Optional<Band> band(String key,
 int index)

Returns the band at the given index, creating it if needed. If the given index is out of range, then this method logs a warning and returns an empty value.

Parameters:

key - the key without its band number. Used only for formatting warning messages.

index - the band index.

Returns:

information about the band, or null if none.

sampleDimension

private Optional<DefaultSampleDimension> sampleDimension(String key,
 int index)

Returns metadata about sample dimension at the given index.

setProjectionParameter

private void setProjectionParameter(String key,
 String name,
 String value,
 boolean isLinear)

Sets a map projection parameter. The parameter is ignored if the projection has not been set.

Parameters:

key - the Landsat key, for formatting error message if needed.

name - the projection parameter name.

value - the parameter value.

isLinear - true for value in metres, or false for value in degrees.

flushSceneTime

private void flushSceneTime()

Writes the value of sceneTime into the metadata object as a temporal extent.

Throws:

DateTimeException - if sceneTime is an instance of OffsetTime. This may happen if SCENE_CENTER_TIME attribute was found without DATE_ACQUIRED.

toBoundingBox

private boolean toBoundingBox(int base)

Computes the bounding box for the 8 corners values starting at the given index. Valid indices are 0 for the projected envelope or 8 for the geographic bounding box. Result is stored in the 4 values starting the given base index.

Returns:

true of success, or false if there is no bounding box.

getMetadata

final org.opengis.metadata.Metadata getMetadata()
                                         throws org.opengis.util.FactoryException

Returns the metadata about the resources described in the Landsat file. The read(BufferedReader) method must be invoked at least once before.

Throws:

org.opengis.util.FactoryException - if an error occurred while creating the Coordinate Reference System.

getFilename

private String getFilename()

Returns the filename to show in error messages, or a localized "unnamed" word if none.

toLongName

private String toLongName(String key)

Prepends the group name before the given key, if a group name exists. This is used only for formatting warning messages.

warning

private void warning(String key,
 BufferedReader reader,
 Exception e)

Invoked when a non-fatal exception occurred while reading metadata. This method sends a record to the registered listeners if any, or logs the record otherwise.

errors

private Errors errors()

Returns the resources to use for formatting error messages.