com.luciad.format.oracle.georaster

Database ConnectorsClass TLcdOracleGeoRasterModelDecoder

java.lang.Object

com.luciad.format.oracle.georaster.TLcdOracleGeoRasterModelDecoder

All Implemented Interfaces:

ILcdModelDecoder

@LcdService(service=ILcdModelDecoder.class,
            priority=20000)
public class TLcdOracleGeoRasterModelDecoder
extends Object
implements ILcdModelDecoder

This ILcdModelDecoder decodes rasters stored in an Oracle Spatial database.

Input files/properties

A spatial database is accessed based on a set of properties. The properties can be passed in a Properties object, or using a properties file with extension "ogr".

The common properties needed to establish a connection are:

• driver (default = oracle.jdbc.driver.OracleDriver): the JDBC driver that will be used to connect to the database.
• url: the database URL.
• user: the database user name.
• password: the user's password.
• alwaysCloseConnection (default = false): an optional boolean to specify that the database connection should be closed after each query. Setting this flag can be useful for database drivers that pool connections, so the connections are reused instead of really being closed.

Other JDBC properties that can help to tune the database connection are passed on to JDBC as well.

The properties that identify the tables, columns, rows, etc. within the database are:

• table: the name of the table containing the rasters.
• geoRasterColumn: the column containing the rasters.
• selectionTables (default = null): an optional comma-separated list of tables required to constrain the rasters of the model. These tables will be added after the main table in the FROM parts of SELECT queries. Note that any column names that are ambiguous (because they occur in multiple tables), have to be prefixed with the suitable table names.
• selectionFilter (default = null): an optional SQL select query to constrain the rasters of the model. This query will be added after the spatial query in the WHERE parts of SELECT queries.
• preferredBand (default = -1): optional, indicates that a single band should be decoded from a multispectral image. For 16 bit images it has the benefit of producing non-truncated, 16 bit rasters.
• sourceFileName: an optional string to be used as the source name in the model descriptor. By default it is the name of the "ogr " file, or "DB" when decoding a stand-alone Properties object.
• displayName: an optional string to be used as the display name in the model descriptor. If not specified, it is equal to the sourceName.

Example properties file:

 # The basic database connection properties.
 driver    = oracle.jdbc.driver.OracleDriver
 url       = jdbc:oracle:thin:@myhost:1521:LUCIAD
 user      = scott
 password  = tiger

 # Optional (default is false)
 alwaysCloseConnection = true

 # The data of interest.
 table           = COUNTRIES
 geoRasterColumn = GEORASTER

 # Optionally, decode a single color band
 # preferredBand=2

 # Optional extra tables and SQL condition to restrict the database elements.
 # Note that the column names have to be prefixed with the table
 # name if they are ambiguous, like the ID column below.
 # selectionTables = POPULATION
 # selectionFilter = COUNTRIES.ID = POPULATION.ID AND POPULATION.VALUE  > 1e7
 

Supported transfer protocols

• This model decoder supports all protocols that are supported by the underlying JDBC driver.

Model structure

• If all the database rasters matching the ogr file or Properties object have the same geographic reference, then the model decoder returns an ILcd2DBoundsIndexedModel.
• If the rasters matching the ogr file or Properties object have different geographic references, then the model decoder returns an ILcdModelTreeNode. The ILcdModelTreeNode contains several ILcd2DBoundsIndexedModel sub-models, one for each encountered geographic reference.

Model descriptor

• All models and sub-models returned by this model decoder have a TLcdOracleGeoRasterModelDescriptor.
• The source name of the model descriptor is given by the sourceFileName property.
• The display name of the model descriptor is given by the displayName property.
• The type name of the model descriptor is "DB".

Model elements

• When the decoder returns a single ILcd2DBoundsIndexedModel, the model elements implement ILcdMultilevelRaster.
• When the decoder returns an ILcdModelTreeNode, the model tree node has no elements of its own. All the sub-models of the ILcdModelTreeNode contain elements that implement ILcdMultilevelRaster.

Model reference

By default, the model reference of a decoded model is determined by the SRID of the spatial table. If no model reference can be created the default model reference set on this decoder will be used (see setDefaultModelReference(com.luciad.model.ILcdModelReference)).

Useful settings

• preferredBand - indicates that a single band should be decoded from a multispectral image.
• defaultModelReference - if the database raster does not define a model reference, the decoder will use this one as a fall-back.

Sample code

 ILcdModelDecoder decoder = new TLcdOracleGeoRasterModelDecoder();
 // decoder.setPreferredBand(0);
 ILcdModel model = decoder.decode("file.ogr");
 

Thread safety

• The decoding of models is not thread-safe.
• The decoded models are thread-safe for reading.

Supported versions and specifications

• The decoder works with Oracle 10.2 server or later.

Known limitations

• The decoder does not support third-party compression methods.
• The decoder supports database rasters having a cell depth of 1,2,4,8 or 16 bits. Higher cell depths are not supported.
• If the database raster has multiple color bands, the bands must either be all in the same data block (interleaved) or each band in its own separate block. In other words, the case when N color bands are distributed over M data blocks (N != M) is not supported.

Decoder details

We will refer to the raster that is stored in the Oracle tables as the database raster or input raster, and to the raster returned by the decoder as the decoded raster.

• Tiling: If a database raster uses blocking, the blocks are translated into tiles. If blocking is not used, the decoded ILcdMultilevelRasters will not be tiled.
• Pyramids: If a database raster has multiple resolution levels, they will be decoded as separate levels in the corresponding ILcdMultilevelRaster. If pyramids are not used in the database, the ILcdMultilevelRaster will contain a single resolution level.
• Cell depth: The database rasters must have a cell depth of 1, 2, 4, 8, or 16 bits. Higher cell depths are currently not supported.

  If the cell depth is 1, 2, or 4 bits (several raster cells are packed in one byte) then each cell will be expanded to occupy 8 bits in the decoded raster.

  If the database raster has a cell depth of 16 bits, the decoded raster may have 8 or 16 bits, depending on the database raster's color model and whether the user specified a single preferred band to be decoded (see the Color Models section).
• Elevation data: If at least one of the matching database rasters contains 16 bit signed values (16BIT_S) and has exactly one color band then the data is considered to represent elevations. The isElevation method of the model descriptor will return true.
• Compression: The following block compression methods are supported:
  • NONE
  • DEFLATE
  • JPEG-F
  • JPEG-B
• Color models: If the database raster has a true color model and at least 3 color bands, the decoder will normally create an 8 bit RGB raster having a direct color model. The R, G, and B bands are selected according to the database raster's defaultColorLayer property (see the Oracle documentation). If the database raster has a cell depth of 16 bits, the decoder truncates the cell values to 8 bits by taking only the most significant byte of the value.

  To decide if the database raster has a true (direct) or an indexed color model, the decoder checks the colorMap property of the first database raster layer. If the database defines a color map, the decoded raster will have an IndexedColorModel using that color map, otherwise the decoded raster will have a direct color model.

  If the user specifies a preferred band via the setPreferredBand(int) method, the decoded raster will always have an IndexColorModel. The color map of this color model is extracted from the database by looking at the colorMap property of the requested band/layer (see Oracle documentation for getColorMap). If no color map is specified by the database then a default IndexColorModel is created. This color model contains gray scale values in the usual case, or values suitable for displaying elevation data, if the raster contains elevations.

  If the database raster NODATA value is defined, the color model is expanded to include an alpha channel or an alpha value and the corresponding pixels are set to full transparency in the decoded raster.

The type of rasters created by the decoder is summarized in the following table:

DB Cell Depth	DB Bands	Preferred Band	Decoded raster
1,2,4,8 bit	3 bands or more	No	RGB, 8 bit
	2 bands	No	error
	2 bands or more	Yes	Indexed, 8 bit
	1 band or grayscale	-	Indexed, 8 bit
16 bit	3 bands or more	No	RGB, truncated to 8 bit
	2 bands	No	error
	2 bands or more	Yes	Indexed, 16 bit
	1 band	-	Indexed, 16 bit

The rasters of the model are read lazily - the data is retrieved from the database only when it is actually required. For this reason, each decoded raster keeps a database connection open. The connection can be closed by calling the close() method of the associated TLcdOracleGeoRasterModelDescriptor.

Performance tips

By default, a single database connection is kept open and used for reading every tile. Access to different tiles from different threads is synchronized on this unique connection object. Multi-threaded performance can be improved by setting the alwaysCloseConnection to true and setting a connection-pooling database driver. This forces the model to ask for a new connection every time a tile read is necessary. Multiple threads will obtain different connections from the pool, so the reading will be done in parallel instead of being serialized on a single connection object.

Since:

8.0

See Also:

Oracle Spatial GeoRaster, TLcdOracleGeoRasterModelDescriptor

Constructor Summary

Constructors

Constructor and Description
TLcdOracleGeoRasterModelDecoder() Constructs a new TLcdOracleGeoRasterModelDecoder, with a globally shared buffer for caching tiles.
TLcdOracleGeoRasterModelDecoder(ILcdBuffer aBuffer) Constructs a new TLcdOracleGeoRasterModelDecoder.

Method Summary

Modifier and Type	Method and Description
boolean	canDecodeSource(String aSourceName) Checks whether this model decoder can decode the specified data source.
ILcdModel	decode(Properties aProperties) Creates a new model from the given set of properties.
ILcdModel	decode(String aSourceName) Creates a new model from the given data source.
ILcdModelReference	getDefaultModelReference() Returns the default model reference.
String	getDisplayName() Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.
int	getPreferredBand() Returns the preferred band.
static boolean	isClassTraceOn() Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.
static void	setClassTraceOn(boolean aClassTraceOn) Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.
void	setDefaultModelReference(ILcdModelReference aDefaultModelReference) Sets the model reference to be used if the georaster does not define one.
void	setPreferredBand(int aPreferredBand) Sets the preferred band for extracting the colormap.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.luciad.model.ILcdModelDecoder

canDecodeSource, decodeModelMetadata, decodeModelMetadata, decodeSource, discoverDataSources

Constructor Detail

TLcdOracleGeoRasterModelDecoder

public TLcdOracleGeoRasterModelDecoder()

Constructs a new TLcdOracleGeoRasterModelDecoder, with a globally shared buffer for caching tiles.

See Also:

TLcdSharedBuffer.getBufferInstance()

TLcdOracleGeoRasterModelDecoder

public TLcdOracleGeoRasterModelDecoder(ILcdBuffer aBuffer)

Constructs a new TLcdOracleGeoRasterModelDecoder.

Parameters:

aBuffer - a buffer used for internal operations. The buffer must be large enough to keep at least one decoded raster tile (eg. pixel_width x pixel_height x 3, assuming 3 color bands and one byte per color sample).

Method Detail

setDefaultModelReference

public void setDefaultModelReference(ILcdModelReference aDefaultModelReference)

Sets the model reference to be used if the georaster does not define one.

Parameters:

aDefaultModelReference - the default model reference.

getDefaultModelReference

public ILcdModelReference getDefaultModelReference()

Returns the default model reference.

Returns:

a model reference.

getPreferredBand

public int getPreferredBand()

Returns the preferred band. Default is -1, which means undefined.

Returns:

the preferred band.

setPreferredBand

public void setPreferredBand(int aPreferredBand)

Sets the preferred band for extracting the colormap. If the argument is positive or zero then the output raster will contain only the given band of the database raster. If the band does not have a colormap, a default gray-level colormap is used. See the Color Model section at the top of this file.

If the value set via this method is positive or zero, it will override the preferredBand specified in the ogr properties file.

Parameters:

aPreferredBand - the index of the preferred band

isClassTraceOn

public static boolean isClassTraceOn()

Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.

Returns true if tracing is enabled for this class.

Returns:

true if tracing is enabled for this class, false otherwise.

setClassTraceOn

public static void setClassTraceOn(boolean aClassTraceOn)

Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.

Enables tracing for all instances of this class. If the argument is true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.

Parameters:

aClassTraceOn - if true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.

getDisplayName

public String getDisplayName()

Description copied from interface: ILcdModelDecoder

Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.

Specified by:

getDisplayName in interface ILcdModelDecoder

Returns:

the displayable name of this ILcdModelDecoder.

canDecodeSource

public boolean canDecodeSource(String aSourceName)

Description copied from interface: ILcdModelDecoder

Checks whether this model decoder can decode the specified data source. It is acceptable for this method to return true for a source name while decode throws an exception for that same source name.

For performance reasons, we strongly recommend that this will only be a simple test. For example: check the file extension of a file, but not that the file exists or contains expected content.

Specified by:

canDecodeSource in interface ILcdModelDecoder

Parameters:

aSourceName - the data source to be verified; typically a file name or a URL.

Returns:

true if this decoder can likely decode the data specified by the source name, false otherwise.

See Also:

ILcdModelDecoder.decode(String), ILcdModelDecoder.decodeModelMetadata(String)

decode

public ILcdModel decode(String aSourceName)
                 throws IOException

Description copied from interface: ILcdModelDecoder

Creates a new model from the given data source.

Specified by:

decode in interface ILcdModelDecoder

Parameters:

aSourceName - the data source to be decoded; typically a file name or a URL.

Returns:

A model containing the decoded data. While null is allowed, implementors are advised to throw an error instead.

Throws:

IOException - for any exceptions caused by IO problems or invalid data. Since decoding invalid data almost always results in RunTimeExceptions (NullPointerException, IndexOutOfBoundsException, IllegalArgumentException, ...) on unexpected places, implementations are advised to catch RuntimeExceptions in their decode() method, and wrap them into an IOException, as illustrated in the code snippet below.

   public ILcdModel decode( String aSourceName ) throws IOException {
      try (InputStream input = fInputStreamFactory.createInputStream(aSourceName)) {
         // Perform decoding ...
      } catch (RuntimeException e) {
         throw new IOException(e);
      }
   }
 

InterruptedIOException - When the thread on which this method is called is interrupted: it is recommended to stop the decoding and throw an InterruptedIOException. This same exception can also be used if the decoder shows UI to the user, and the user cancels the decoding through the UI.

See Also:

ILcdModelDecoder.canDecodeSource(String)

decode

public ILcdModel decode(Properties aProperties)
                 throws IOException

Creates a new model from the given set of properties.

Parameters:

aProperties - a Properties object containing information about an Oracle database

Returns:

a new model

Throws:

IOException