org.esa.beam.framework.dataio
Class AbstractProductReader

java.lang.Object
  org.esa.beam.framework.dataio.AbstractProductReader

All Implemented Interfaces:

ProductReader

Direct Known Subclasses:

AbstractProductBuilder

public abstract class AbstractProductReader
extends Object
implements ProductReader

The AbstractProductReader class can be used as a base class for new product reader implementations. The only two methods which clients must implement are readProductNodes() and readBandData methods.

Version:

$Revision$ $Date$

Author:

Norman Fomferra

See Also:

readProductNodes(java.lang.Object, org.esa.beam.framework.dataio.ProductSubsetDef), readBandRasterData(org.esa.beam.framework.datamodel.Band, int, int, int, int, org.esa.beam.framework.datamodel.ProductData, com.bc.ceres.core.ProgressMonitor)

Constructor Summary

protected

AbstractProductReader(ProductReaderPlugIn readerPlugIn) Constructs a new abstract product reader.

Method Summary

void	close() Closes the access to all currently opened resources such as file input streams and all resources of this children directly owned by this reader.
protected static void	configurePreferredTileSize(Product product)
protected TiePointGrid	createTiePointGrid(String gridName, int gridWidth, int gridHeight, float offsetX, float offsetY, float subSamplingX, float subSamplingY, float[] tiePoints) Creates a tie point grid from the given properties.
protected int	getGridDiscontinutity(String name) Used by the createTiePointGrid method in order to determine the discontinuity mode for angle tie-point grids.
Object	getInput() Retrives the current output destination object.
TreeNode<File>	getProductComponents() Retrieves a set of TreeNode objects that represent the physical product structure as stored on the harddrive.
ProductReaderPlugIn	getReaderPlugIn() Returns the plug-in which created this product reader.
ProductSubsetDef	getSubsetDef() Returns the subset information with which this data product is read from its physical source.
protected boolean	isInstanceOfValidInputType(Object input) Checks if the given object is an instance of one of the valid input types for this product reader.
boolean	isMetadataIgnored() Checks if this reader ignores metadata or not.
boolean	isNodeAccepted(String name) Tests whether or not a product node (a band, a tie-point grid or metadata element) with the given name is accepted with respect to the optional spectral band subset.
void	readBandRasterData(Band destBand, int destOffsetX, int destOffsetY, int destWidth, int destHeight, ProductData destBuffer, com.bc.ceres.core.ProgressMonitor pm) Reads raster data from the data source specified by the given destination band into the given in-memory buffer and region.
protected abstract void	readBandRasterDataImpl(int sourceOffsetX, int sourceOffsetY, int sourceWidth, int sourceHeight, int sourceStepX, int sourceStepY, Band destBand, int destOffsetX, int destOffsetY, int destWidth, int destHeight, ProductData destBuffer, com.bc.ceres.core.ProgressMonitor pm) The template method which is called by the method after an optional spatial subset has been applied to the input parameters.
Product	readProductNodes(Object input, ProductSubsetDef subsetDef) Reads the nodes of a data product and returns an in-memory representation of it.
protected abstract Product	readProductNodesImpl() Provides an implementation of the readProductNodes interface method.
protected void	setInput(Object input)
protected void	setSubsetDef(ProductSubsetDef subsetDef) Sets the subset information.
String	toString() Returns a string representation of the reader.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractProductReader

protected AbstractProductReader(ProductReaderPlugIn readerPlugIn)

Constructs a new abstract product reader.

Parameters:

readerPlugIn - the reader plug-in which created this reader, can be null for internal reader implementations

Method Detail

getReaderPlugIn

public ProductReaderPlugIn getReaderPlugIn()

Returns the plug-in which created this product reader.

Specified by:

getReaderPlugIn in interface ProductReader

Returns:

the product reader plug-in, should never be null

getInput

public Object getInput()

Retrives the current output destination object. The return value might be null if the setInput() method has not been called so far.

Specified by:

getInput in interface ProductReader

setInput

protected void setInput(Object input)

isMetadataIgnored

public boolean isMetadataIgnored()

Checks if this reader ignores metadata or not.

Returns:

true if so

getSubsetDef

public ProductSubsetDef getSubsetDef()

Returns the subset information with which this data product is read from its physical source.

Specified by:

getSubsetDef in interface ProductReader

Returns:

the subset information, can be null

setSubsetDef

protected void setSubsetDef(ProductSubsetDef subsetDef)

Sets the subset information. This implemetation is protected to overwrite in the inherided class to ensure that the subset information cannot be set from the readProductNodes method.

Parameters:

subsetDef - the subset definition

isNodeAccepted

public boolean isNodeAccepted(String name)

Tests whether or not a product node (a band, a tie-point grid or metadata element) with the given name is accepted with respect to the optional spectral band subset. All accepted nodes will be part of the product read.

Parameters:

name - the node name

Returns:

true if so

readProductNodes

public Product readProductNodes(Object input,
                                ProductSubsetDef subsetDef)
                         throws IOException

Reads the nodes of a data product and returns an in-memory representation of it.

The given subset info can be used to specify spatial and spectral portions of the original proudct. If the subset is omitted, the complete product is read in.

Whether the band data - the actual pixel values - is read in immediately or later when pixels are requested, is up to the implementation.

Specified by:

readProductNodes in interface ProductReader

Parameters:

input - an object representing a valid output for this product reader, might be a ImageInputStream or other Object to use for future decoding.

subsetDef - a spectral or spatial subset (or both) of the product. If null, the entire product is read in

Throws:

IllegalArgumentException - if input type is not supported (see ProductReaderPlugIn.getInputTypes()).

IOException - if an I/O error occurs

IllegalFileFormatException - if the file format is unknown.

readProductNodesImpl

protected abstract Product readProductNodesImpl()
                                         throws IOException

Provides an implementation of the readProductNodes interface method. Clients implementing this method can be sure that the input object and eventually the subset information has already been set.

This method is called as a last step in the readProductNodes(input, subsetInfo) method.

Returns:

a new product instance

Throws:

IOException - if an I/O error occurs

readBandRasterData

public void readBandRasterData(Band destBand,
                               int destOffsetX,
                               int destOffsetY,
                               int destWidth,
                               int destHeight,
                               ProductData destBuffer,
                               com.bc.ceres.core.ProgressMonitor pm)
                        throws IOException

Reads raster data from the data source specified by the given destination band into the given in-memory buffer and region.

For a complete description, please refer to the ProductReader.readBandRasterData(org.esa.beam.framework.datamodel.Band, int, int, int, int, org.esa.beam.framework.datamodel.ProductData, com.bc.ceres.core.ProgressMonitor) interface definition} of this method.

The AbstractProductReader implements this method using the Template Method pattern. The template method in this case is the abstract method to which the call is delegated after an optional spatial subset given by getSubsetDef() has been applied to the input parameters.

Specified by:

readBandRasterData in interface ProductReader

Parameters:

destBand - the destination band which identifies the data source from which to read the sample values

destOffsetX - the X-offset in the band's raster co-ordinates

destOffsetY - the Y-offset in the band's raster co-ordinates

destWidth - the width of region to be read given in the band's raster co-ordinates

destHeight - the height of region to be read given in the band's raster co-ordinates

destBuffer - the destination buffer which receives the sample values to be read

pm - a monitor to inform the user about progress

Throws:

IOException - if an I/O error occurs

IllegalArgumentException - if the number of elements destination buffer not equals destWidth * destHeight or the destination region is out of the band's raster

See Also:

readBandRasterDataImpl(int, int, int, int, int, int, org.esa.beam.framework.datamodel.Band, int, int, int, int, org.esa.beam.framework.datamodel.ProductData, com.bc.ceres.core.ProgressMonitor), getSubsetDef(), ProductReader.readBandRasterData(org.esa.beam.framework.datamodel.Band, int, int, int, int, org.esa.beam.framework.datamodel.ProductData, com.bc.ceres.core.ProgressMonitor), RasterDataNode.getRasterWidth(), RasterDataNode.getRasterHeight()

readBandRasterDataImpl

protected abstract void readBandRasterDataImpl(int sourceOffsetX,
                                               int sourceOffsetY,
                                               int sourceWidth,
                                               int sourceHeight,
                                               int sourceStepX,
                                               int sourceStepY,
                                               Band destBand,
                                               int destOffsetX,
                                               int destOffsetY,
                                               int destWidth,
                                               int destHeight,
                                               ProductData destBuffer,
                                               com.bc.ceres.core.ProgressMonitor pm)
                                        throws IOException

The template method which is called by the method after an optional spatial subset has been applied to the input parameters.

The destination band, buffer and region parameters are exactly the ones passed to the original call. Since the destOffsetX and destOffsetY parameters are already taken into acount in the sourceOffsetX and sourceOffsetY parameters, an implementor of this method is free to ignore them.

Parameters:

sourceOffsetX - the absolute X-offset in source raster co-ordinates

sourceOffsetY - the absolute Y-offset in source raster co-ordinates

sourceWidth - the width of region providing samples to be read given in source raster co-ordinates

sourceHeight - the height of region providing samples to be read given in source raster co-ordinates

sourceStepX - the sub-sampling in X direction within the region providing samples to be read

sourceStepY - the sub-sampling in Y direction within the region providing samples to be read

destBand - the destination band which identifies the data source from which to read the sample values

destOffsetX - the X-offset in the band's raster co-ordinates

destOffsetY - the Y-offset in the band's raster co-ordinates

destWidth - the width of region to be read given in the band's raster co-ordinates

destHeight - the height of region to be read given in the band's raster co-ordinates

destBuffer - the destination buffer which receives the sample values to be read

pm - a monitor to inform the user about progress

Throws:

IOException - if an I/O error occurs

See Also:

readBandRasterData(org.esa.beam.framework.datamodel.Band, int, int, int, int, org.esa.beam.framework.datamodel.ProductData, com.bc.ceres.core.ProgressMonitor), getSubsetDef()

close

public void close()
           throws IOException

Closes the access to all currently opened resources such as file input streams and all resources of this children directly owned by this reader. Its primary use is to allow the garbage collector to perform a vanilla job.

This method should be called only if it is for sure that this object instance will never be used again. The results of referencing an instance of this class after a call to close() are undefined.

Overrides of this method should always call super.close(); after disposing this instance.

Specified by:

close in interface ProductReader

Throws:

IOException - if an I/O error occurs

getProductComponents

public TreeNode<File> getProductComponents()

Retrieves a set of TreeNode objects that represent the physical product structure as stored on the harddrive. The tree consisty of: - a root node (the one returned) pointing to the directory that CONTAINS the product - any number of nested children that compose the product. Each TreeNod is configured as follows: - id: contains a string representation of the path. For the root node, this is the absolute path to the parent of the file returned by Product.getFileLocation(). For all subsequent nodes, the node name. - content: each node stores as content a java.io.File object that physically defines the node.

The method returns null when a TreeNode can not be assembled (i.e. in-memory product, created from stream ...)

Returns:

the root TreeNode or null

isInstanceOfValidInputType

protected boolean isInstanceOfValidInputType(Object input)

Checks if the given object is an instance of one of the valid input types for this product reader.

Parameters:

input - the input object passed to readProductNodes(Object, ProductSubsetDef)

Returns:

true if so

See Also:

ProductReaderPlugIn.getInputTypes()

getGridDiscontinutity

protected int getGridDiscontinutity(String name)

Used by the createTiePointGrid method in order to determine the discontinuity mode for angle tie-point grids.

The default implementation returns TiePointGrid.DISCONT_AT_180 for the names "lon", "long" or "longitude" ignoring letter case, TiePointGrid.DISCONT_NONE otherwise.

Parameters:

name - the grid name

Returns:

the discontinuity mode, always one of TiePointGrid.DISCONT_NONE, TiePointGrid.DISCONT_AT_180 and TiePointGrid.DISCONT_AT_360.

createTiePointGrid

protected TiePointGrid createTiePointGrid(String gridName,
                                          int gridWidth,
                                          int gridHeight,
                                          float offsetX,
                                          float offsetY,
                                          float subSamplingX,
                                          float subSamplingY,
                                          float[] tiePoints)

Creates a tie point grid from the given properties.

The method uses the getGridDiscontinutity(String) method in order to creater an appropriate angular tie-point grids.

Parameters:

gridName - the grid name

gridWidth - the grid's raster width

gridHeight - the grid's raster height

offsetX - the grid origin's X-coordinate in pixel units

offsetY - the grid origin's Y-coordinate in pixel units

subSamplingX - the grid subsampling's X in pixel units

subSamplingY - the grid subsampling's Y in pixel units

tiePoints - the tie-points

Returns:

the tie-point grid instance, never null

configurePreferredTileSize

protected static void configurePreferredTileSize(Product product)

toString

public String toString()

Returns a string representation of the reader.

Overrides:

toString in class Object

Returns:

a string representation of the object.