Operator (BEAM 5.0 API)

java.lang.Object
- org.esa.beam.framework.gpf.Operator

Direct Known Subclasses:

GraphOp, PointOperator, PyOperator
```
public abstract class Operator
extends Object
```
The abstract base class for all operators intended to be extended by clients.
The following methods are intended to be implemented or overridden:
initialize(): must be implemented in order to initialise the operator and create the target product.
computeTile(): implemented to compute the tile for a single band.
computeTileStack(java.util.Map, java.awt.Rectangle, com.bc.ceres.core.ProgressMonitor): implemented to compute the tiles for multiple bands.
dispose(): can be overridden in order to free all resources previously allocated by the operator.

Generally, only one computeTile method needs to be implemented. It depends on the type of algorithm which of both operations is most advantageous to implement:

If bands can be computed independently of each other, then it is beneficial to implement the computeTile() method. This is the case for sub-sampling, map-projections, band arithmetic, band filtering and statistic analyses.
computeTileStack() should be overridden in cases where the bands of a product cannot be computed independently, e.g. because they are a simultaneous output. This is often the case for algorithms based on neural network, cluster analyses, model inversion methods or spectral unmixing.

The framework execute either the computeTile() or the computeTileStack() method based on the current use case or request. If tiles for single bands are requested, e.g. for image display, it will always prefer an implementation of the computeTile() method and call it. If all tiles are requested at once, e.g. writing a product to disk, it will attempt to use the computeTileStack() method. If the framework cannot use its preferred operation, it will use the one implemented by the operator.

todo - Explain the role of operator annotations (nf - 15.10.2007)

todo - Explain the role of the SPI (nf - 15.10.2007)

Since:: 4.1
Author:: Norman Fomferra, Marco Peters, Marco Zühlke
See Also:: OperatorSpi, OperatorMetadata, Parameter, TargetProduct, TargetProperty, SourceProduct, SourceProducts

Constructor Summary

Constructors
Modifier Constructor and Description

protected Operator()
Constructs a new operator.

Constructors
Modifier	Constructor and Description
`protected`	`Operator()` Constructs a new operator.

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`checkForCancellation()` Checks for cancellation of the current processing request.
`void`	`computeTile(Band targetBand, Tile targetTile, com.bc.ceres.core.ProgressMonitor pm)` Called by the framework in order to compute a tile for the given target band.
`void`	`computeTileStack(Map<Band,Tile> targetTiles, Rectangle targetRectangle, com.bc.ceres.core.ProgressMonitor pm)` Called by the framework in order to compute the stack of tiles for the given target bands.
`protected void`	`deactivateComputeTileMethod()` Deactivates the `computeTile` method.
`void`	`dispose()` Releases the resources the operator has acquired during its lifetime.
`protected void`	`finalize()` Overridden in order to force a call to `dispose()`, if not already done.
`String`	`getId()`
`Logger`	`getLogger()` Gets the logger whuich can be used to log information during initialisation and tile computation.
`Object`	`getParameter(String name)` Gets the value for the parameter with the given name.
`Object`	`getParameter(String name, Object defaultValue)` Gets the value for the parameter with the given name.
`Product`	`getSourceProduct()` Gets a single source product.
`Product`	`getSourceProduct(String id)` Gets the source product using the specified name.
`String`	`getSourceProductId(Product product)` Gets the identifier for the given source product.
`Product[]`	`getSourceProducts()` Gets the source products in the order they have been declared.
`Tile`	`getSourceTile(RasterDataNode rasterDataNode, Rectangle region)` Gets a `Tile` for a given band and image region.
`Tile`	`getSourceTile(RasterDataNode rasterDataNode, Rectangle region, javax.media.jai.BorderExtender borderExtender)` Gets a `Tile` for a given band and image region.
`OperatorSpi`	`getSpi()` Gets the SPI which was used to create this operator.
`Product`	`getTargetProduct()` Gets the target product for the operator.
`Object`	`getTargetProperty(String name)` Gets a target property of the operator.
`abstract void`	`initialize()` Initializes this operator and sets the one and only target product.
`void`	`setLogger(Logger logger)` Sets the logger which can be used to log information during initialisation and tile computation.
`void`	`setParameter(String name, Object value)` Sets the value for the parameter with the given name.
`void`	`setParameterDefaultValues()` Sets the operator parameters to their default values, if any.
`protected void`	`setRequiresAllBands(boolean requiresAllBands)`
`void`	`setSourceProduct(Product sourceProduct)` Sets a single source product.
`void`	`setSourceProduct(String id, Product product)` Sets a source product.
`void`	`setSourceProducts(Product... products)` Sets the source products.
`void`	`setSpi(OperatorSpi operatorSpi)` Sets the SPI which was used to create this operator.
`void`	`setTargetProduct(Product targetProduct)` Sets the target product for the operator.
`void`	`stopTileComputationObservation()` Non-API.
`void`	`update()` Updates this operator forcing it to recreate the target product.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Operator
```
protected Operator()
```
    Constructs a new operator.
- Method Detail
  - setParameterDefaultValues
```
public void setParameterDefaultValues()
```
    Sets the operator parameters to their default values, if any.
  - finalize
```
protected final void finalize()
                       throws Throwable
```
    Overridden in order to force a call to dispose(), if not already done.
    
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    Throwable - The Exception raised by this method
  - initialize
```
public abstract void initialize()
                         throws OperatorException
```
    Initializes this operator and sets the one and only target product.
    The target product can be either defined by a field of type Product annotated with the TargetProduct annotation or by calling setTargetProduct(org.esa.beam.framework.datamodel.Product) method.
    
    This method shall never be called directly. The framework calls this method after it has created an instance of this Operator. This will occur only once durting the lifetime of an Operator instance. If not already done, calling the getTargetProduct() will always trigger a call to the initialize() method.
    Any client code that must be performed before computation of tile data should be placed here.
    
    Throws:
    
    OperatorException - If an error occurs during operator initialisation.
    See Also:
    getTargetProduct()
  - update
```
public void update()
```
    Updates this operator forcing it to recreate the target product. Warning: Experimental API added by nf (25.02.2010)
    
    Since:
    
    BEAM 4.8
  - computeTile
```
public void computeTile(Band targetBand,
               Tile targetTile,
               com.bc.ceres.core.ProgressMonitor pm)
                 throws OperatorException
```
    Called by the framework in order to compute a tile for the given target band.
    The default implementation throws a runtime exception with the message "not implemented".
    
    This method shall never be called directly.
    
    Parameters:
    targetBand - The target band.
    targetTile - The current tile associated with the target band to be computed.
    pm - A progress monitor which should be used to determine computation cancelation requests.
    
    Throws:
    
    OperatorException - If an error occurs during computation of the target raster.
  - computeTileStack
```
public void computeTileStack(Map<Band,Tile> targetTiles,
                    Rectangle targetRectangle,
                    com.bc.ceres.core.ProgressMonitor pm)
                      throws OperatorException
```
    Called by the framework in order to compute the stack of tiles for the given target bands.
    The default implementation throws a runtime exception with the message "not implemented".
    
    This method shall never be called directly.
    
    Parameters:
    targetTiles - The current tiles to be computed for each target band.
    targetRectangle - The area in pixel coordinates to be computed (same for all rasters in targetRasters).
    pm - A progress monitor which should be used to determine computation cancelation requests.
    
    Throws:
    
    OperatorException - if an error occurs during computation of the target rasters.
  - dispose
```
public void dispose()
```
    Releases the resources the operator has acquired during its lifetime. The default implementation does nothing.
    Overrides should make sure to call super.dispose() as well.
  - deactivateComputeTileMethod
```
protected final void deactivateComputeTileMethod()
                                          throws IllegalStateException
```
    Deactivates the computeTile method. This method can be called from within the initialize() method if the current operator configuration prevents the computation of tiles of individual, independent bands.
    
    Throws:
    
    IllegalStateException - if the computeTileStack method is not implemented
  - setRequiresAllBands
```
protected final void setRequiresAllBands(boolean requiresAllBands)
```
  - getId
```
public final String getId()
```
    Returns:
    The operator's runtime identifier assigned by the framework.
  - getSourceProducts
```
public final Product[] getSourceProducts()
```
    Gets the source products in the order they have been declared.
    
    Returns:
    The array source products.
  - setSourceProducts
```
public final void setSourceProducts(Product... products)
```
    Sets the source products.
    
    Parameters:
    products - The source products.
    Since:
    
    BEAM 4.2
  - getSourceProduct
```
public Product getSourceProduct()
```
    Gets a single source product. This method is a shortcut for getSourceProduct("sourceProduct").
    
    Returns:
    The source product, or null if not set.
    Since:
    
    BEAM 4.2
  - setSourceProduct
```
public void setSourceProduct(Product sourceProduct)
```
    Sets a single source product. This method is a shortcut for setSourceProduct("sourceProduct", sourceProduct).
    
    Parameters:
    sourceProduct - the source product to be set
    Since:
    
    BEAM 4.2
  - getSourceProduct
```
public final Product getSourceProduct(String id)
```
    Gets the source product using the specified name.
    
    Parameters:
    id - the identifier
    
    Returns:
    the source product, or null if not found
    See Also:
    getSourceProductId(Product)
  - setSourceProduct
```
public final void setSourceProduct(String id,
                    Product product)
```
    Sets a source product. One product instance can be registered with different identifiers, e.g. "source", "source1" and "input" in consecutive calls.
    
    Parameters:
    id - a source product identifier
    product - the source product to be set
    Since:
    
    BEAM 4.2
  - getSourceProductId
```
public final String getSourceProductId(Product product)
```
    Gets the identifier for the given source product.
    
    Parameters:
    product - The source product.
    
    Returns:
    The identifier, or null if no such exists.
    See Also:
    getSourceProduct(String)
  - getTargetProduct
```
public final Product getTargetProduct()
                               throws OperatorException
```
    Gets the target product for the operator.
    
    If the target product is not set, calling this method results in a call to initialize().
    
    Returns:
    The target product.
    
    Throws:
    
    OperatorException - May be caused by initialize(), if the operator is not initialised, or if the target product is not set.
  - setTargetProduct
```
public final void setTargetProduct(Product targetProduct)
```
    Sets the target product for the operator.
    
    Must be called from within the initialize() method.
    
    Parameters:
    targetProduct - The target product.
  - getTargetProperty
```
public final Object getTargetProperty(String name)
                               throws OperatorException
```
    Gets a target property of the operator.
    
    If the requested target property is not set, calling this method results in a call to initialize().
    
    Parameters:
    name - the name of the property requested.
    
    Returns:
    the target property requested.
    
    Throws:
    
    OperatorException - May be caused by initialize(), if the operator is not initialised, or if the target product is not been set.
  - getParameter
```
public Object getParameter(String name)
```
    Gets the value for the parameter with the given name.
    
    Parameters:
    name - The parameter name.
    
    Returns:
    The parameter value, which may be null.
    Since:
    
    BEAM 4.7
  - getParameter
```
public Object getParameter(String name,
                  Object defaultValue)
```
    Gets the value for the parameter with the given name.
    
    Parameters:
    name - The parameter name.
    defaultValue - The default value which is used in case getParameter(String) returns null. May be null.
    
    Returns:
    The parameter value, or the given defaultValue.
    Since:
    
    BEAM 5.0
  - setParameter
```
public void setParameter(String name,
                Object value)
```
    Sets the value for the parameter with the given name.
    
    Parameters:
    name - The parameter name.
    value - The parameter value, which may be null.
    Since:
    
    BEAM 4.7
  - getSourceTile
```
public final Tile getSourceTile(RasterDataNode rasterDataNode,
                 Rectangle region)
                         throws OperatorException
```
    Gets a Tile for a given band and image region.
    
    Parameters:
    rasterDataNode - the raster data node of a data product, e.g. a Band or TiePointGrid.
    region - the image region in pixel coordinates
    
    Returns:
    a tile.
    
    Throws:
    
    OperatorException - if the tile request cannot be processed
  - getSourceTile
```
public final Tile getSourceTile(RasterDataNode rasterDataNode,
                 Rectangle region,
                 javax.media.jai.BorderExtender borderExtender)
                         throws OperatorException
```
    Gets a Tile for a given band and image region. The region can overlap the bounds of source image. This method is particulary useful if you need to compute target pixels from an n x m region around a corresponding source pixel. In this case an extended tile will need to be read from the source.
    
    Parameters:
    rasterDataNode - the raster data node of a data product, e.g. a Band or TiePointGrid.
    region - The image region in pixel coordinates
    borderExtender - A strategy used to fill the raster regions that lie outside the bounds of the source image.
    
    Returns:
    A tile whose region can overlap the bounds of source image.
    
    Throws:
    
    OperatorException - if the tile request cannot be processed
    Since:
    
    BEAM 4.7.1
  - checkForCancellation
```
protected final void checkForCancellation()
                                   throws OperatorException
```
    Checks for cancellation of the current processing request. Throws an exception, if the request has been canceled (e.g. by the user).
    
    Throws:
    
    OperatorException - if the current processing request has been canceled (e.g. by the user).
  - getLogger
```
public final Logger getLogger()
```
    Gets the logger whuich can be used to log information during initialisation and tile computation.
    
    Returns:
    The logger.
  - stopTileComputationObservation
```
public void stopTileComputationObservation()
```
    Non-API.
  - setLogger
```
public final void setLogger(Logger logger)
```
    Sets the logger which can be used to log information during initialisation and tile computation.
    
    Parameters:
    logger - The logger.
  - getSpi
```
public final OperatorSpi getSpi()
```
    Gets the SPI which was used to create this operator. If no operator has been explicitly set, the method will return an anonymous SPI.
    
    Returns:
    The operator SPI.
  - setSpi
```
public final void setSpi(OperatorSpi operatorSpi)
```
    Sets the SPI which was used to create this operator.
    
    Parameters:
    operatorSpi - The operator SPI.

Class Operator

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Operator

Method Detail

setParameterDefaultValues

finalize

initialize

update

computeTile

computeTileStack

dispose

deactivateComputeTileMethod

setRequiresAllBands

getId

getSourceProducts

setSourceProducts

getSourceProduct

setSourceProduct

getSourceProduct

setSourceProduct

getSourceProductId

getTargetProduct

setTargetProduct

getTargetProperty

getParameter

getParameter

setParameter

getSourceTile

getSourceTile

checkForCancellation

getLogger

stopTileComputationObservation

setLogger

getSpi

setSpi