@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdS57UnifiedModelDecoder extends Object implements ILcdModelDecoder,ILcdDataSourceModelDecoder, ILcdMetadataDecoder, ILcdInputStreamFactoryCapable
This model decoder decodes ECDIS S-57 data into ILcdModel
objects.
This model decoder is capable of decoding catalogue files and single cell files. It
can also handle both ENC files and AML files. Internally the model decoder delegates to a
TLcdS57ModelDecoder
and TLcdS57CatalogueModelDecoder
. As a result, this model
decoder returns models with the same structure as those model decoders. It also has the same set
of features and limitations. Consult the javadoc of those model decoders for more
information.
This model decoder is the recommended one for all users who just want to visualize S-57 data. Only if you need access to the more specialized methods/functionality of the individual model decoders you should use those classes directly.
The models created by this model decoder can directly
be passed to the TLcdS52GXYLayerFactory
and the TLspS52LayerBuilder
.
File | Required | Entry point | Description |
---|---|---|---|
CATALOG.031 | x | x | An S-57 catalog |
*.000 | x | x | Individual S-57 cells |
ILcdInputStreamFactory
of this decoder.
TLcdModelList (catalogue) --> TLcdS57CatalogueModelDescriptor
|
+-- TLcdModelList (one for each level) --> TLcdS57LevelModelDescriptor
|
+-- ILcdModel (one for each ENC cell) --> TLcdS57ModelDescriptor
ILcd2DBoundsIndexedModel
.TLcdS57ModelDescriptor
, with type S-57
.TLcdS57CatalogueModelDescriptor
, with type S-57 Catalogue
.TLcdGeodeticReference
, as described by the specification.TLcdS57ModelDecoder
for more information on domain objects.
setVerifyChecksum(boolean)
to toggle file checksum validation.
ILcdModelDecoder decoder = new TLcdS57UnifiedModelDecoder();
ILcdModel model = decoder.decode("/path/to/CATALOG.031");
// Or ILcdModel model = decoder.decode("/path/to/GB4D132.000");
// To add to a Lightspeed view:
lspView.addLayer(TLspS52LayerBuilder.newBuilder().model(model).build());
// To add to a GXY view:
gxyView.addLayer(new TLcdS52GXYLayerFactory().createGXYLayer(model));
TLcdS57ModelDecoder
for more information on this
topic.
setLoadingPolicy
method: it allows to use lazy loading with weak or soft references, necessary when dealing with
large catalogues that
are too large to load fully into memory.
If the decoded models are processed by the TLcdS52ModelListBuilder
and all
consecutive operations are
performed on the S-52 ordered model list (not on the original model list), it is advised to use
the
LoadingPolicy.WEAK_REFERENCED
policy for optimal performance and memory usage.
setIgnoreInvalidCells(boolean)
and setInvalidCellExceptionHandler(com.luciad.format.s57.ILcdS57InvalidCellExceptionHandler)
.
exception handler
swallows the exception, the cell is ignored and decoding of other cells continues.exception handler
re-throws the exception and ignore invalid cells
is set, the cell is ignored and decoding of other cells continues.exception handler
re-throws the exception and ignore invalid cells
is not set, decoding is interrupted and the exception is passed to the caller. This is the default.ignore invalid cells
is set to false
, and the
exception handler
logs and re-throws all exceptions, except for missing cell files:
these are simply logged and ignored.
For missing cell files, you can expect an FileNotFoundException
as error.
See also the class documentation of TLcdS63UnifiedModelDecoder for more information on error and warning handling of S-63 catalogs.
Since cells in a catalog are lazy-loaded, exceptions can occur not only during the decode(java.lang.String)
, but also
when accessing the data later, for example listing
elements
,
or by accessing some properties of TLcdS57ModelDescriptor
.
If a cell is ignored, a empty stub model is inserted in place of the actual model.
S-57
standard ("IHO Transfer Standard for Digital
Hydrographic Data, Special Publication
No. 57"). This includes S-63, Inland ECDIS (2.0 to 2.4) and AML data.TLcdS57ModelDecoder
apply.TLcdS57ModelDecoder
,
TLcdS57CatalogueModelDecoder
ILcdMetadataDecoder.MetadataWithSource
Constructor and Description |
---|
TLcdS57UnifiedModelDecoder()
Create a new unified model decoder instance
|
Modifier and Type | Method and Description |
---|---|
boolean |
canDecodeMetadata(String aSourceName)
Tells whether this metadata decoder can likely decode metadata for a given source name.
|
boolean |
canDecodeSource(ILcdDataSource aDataSource)
Checks whether this model decoder can decode the data source.
|
boolean |
canDecodeSource(String aSourceName)
Checks whether this model decoder can decode the specified data source.
|
ILcdModel |
decode(String aSourceName)
Creates a new model from the given data source.
|
TLcdISO19115Metadata |
decodeMetadata(String aSourceName)
Decodes the metadata from a given source name as an ISO-19115 metadata object.
|
TLcdModelMetadata |
decodeModelMetadata(String aSourceName)
Decodes metadata for the specified data source.
|
ILcdModel |
decodeSource(ILcdDataSource aDataSource)
Creates a new model from the given data source.
|
String |
getDisplayName()
Returns a short, displayable name for the format that is decoded by this
ILcdModelDecoder . |
ILcdInputStreamFactory |
getInputStreamFactory()
Returns the input stream factory that is used.
|
ILcdS57InvalidCellExceptionHandler |
getInvalidCellExceptionHandler()
Return the cell exception handler to be used when decoding individual cells.
|
File |
getSENCCacheDir()
Returns the SENC cache dir where the converted SENC copies of S-57 cells should be stored.
|
boolean |
isIgnoreInvalidCells()
Returns whether to ignore invalid cells or not.
|
boolean |
isUseSENCCache()
Returns
true if the SENC cache is being used, false otherwise. |
boolean |
isVerifyChecksum()
Returns whether to compute the checksum of the ENC cells and verify it with the corresponding
checksum in the catalogue.
|
void |
setIgnoreInvalidCells(boolean aIgnoreInvalidCells)
Specifies whether to ignore invalid cells in a catalog or not.
|
void |
setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
Sets the input stream factory to be used.
|
void |
setInvalidCellExceptionHandler(ILcdS57InvalidCellExceptionHandler aHandler)
Sets the cell exception handler to be used when decoding individual cells in a catalog.
|
void |
setSENCCacheDir(File aSENCCacheDir)
Sets the SENC cache dir where the converted SENC copies of S-57 cells should be stored.
|
void |
setUseSENCCache(boolean aUseSENCCache)
Enables or disables the use of SENC (System ENC) caches.
|
void |
setVerifyChecksum(boolean aVerifyChecksum)
Sets whether to compute the checksum of the ENC cells and verify it with the corresponding
checksum in the catalogue.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
decodeModelMetadata, discoverDataSources
findAndDecodeMetadata
public TLcdS57UnifiedModelDecoder()
public String getDisplayName()
ILcdModelDecoder
ILcdModelDecoder
.getDisplayName
in interface ILcdModelDecoder
ILcdModelDecoder
.public boolean canDecodeSource(String aSourceName)
ILcdModelDecoder
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.
canDecodeSource
in interface ILcdModelDecoder
aSourceName
- the data source to be verified; typically a file name or a URL.true
if this decoder can likely decode the data specified by the source name, false
otherwise.ILcdModelDecoder.decode(String)
,
ILcdModelDecoder.decodeModelMetadata(String)
public ILcdModel decode(String aSourceName) throws IOException
ILcdModelDecoder
decode
in interface ILcdModelDecoder
aSourceName
- the data source to be decoded; typically a file name or a URL.null
is allowed, implementors are advised to throw an error instead.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.ILcdModelDecoder.canDecodeSource(String)
public boolean canDecodeSource(ILcdDataSource aDataSource)
Return true
if:
TLcdS57CatalogueDataSource
.ENC
, ENC
or AML
cell.canDecodeSource
in interface ILcdModelDecoder
aDataSource
- the data sourcetrue
if the data source can be decoded, false
otherwiseILcdModelDecoder.decodeSource(ILcdDataSource)
,
ILcdModelDecoder.decodeModelMetadata(ILcdDataSource)
public ILcdModel decodeSource(ILcdDataSource aDataSource) throws IOException
ILcdModelDecoder
Creates a new model from the given data source.
By default, this method:
NullPointerException
when a null
data source is passed.ILcdModelDecoder.decode(String)
method when a TLcdDataSource
is passed.decodeSource
in interface ILcdModelDecoder
aDataSource
- the ILcdDataSource
to be decoded.null
is allowed, implementors are advised to throw an error instead.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 decodeSource(ILcdDataSource aDataSource) throws IOException {
try {
// Perform decoding ...
} catch (RuntimeException e) {
throw new IOException(e);
}
}
ILcdModelDecoder.canDecodeSource(ILcdDataSource)
public boolean canDecodeMetadata(String aSourceName)
ILcdMetadataDecoder
true
, it is likely that ILcdMetadataDecoder.decodeMetadata(String)
will return a non-null TLcdISO19115Metadata
object,
but it is not a guarantee. The result is optimistic.
false
, it is guaranteed that ILcdMetadataDecoder.decodeMetadata(String)
will throw an exception or return null
.
canDecodeMetadata
in interface ILcdMetadataDecoder
aSourceName
- the source name to decode metadata fortrue
if this metadata decoder can decode metadata for the given source name, false
otherwisepublic TLcdISO19115Metadata decodeMetadata(String aSourceName) throws IOException
ILcdMetadataDecoder
Note that even if ILcdMetadataDecoder.canDecodeMetadata(String)
returns true
, this method may yet not be able to
decode the given source name. While returning null
is allowed when this decoder couldn't decode the
given source name, implementors are advised to throw an error instead.
decodeMetadata
in interface ILcdMetadataDecoder
aSourceName
- the source name to decode metadata fromIOException
- if the metadata cannot be decoded for some reasonpublic TLcdModelMetadata decodeModelMetadata(String aSourceName) throws IOException
decodeModelMetadata
in interface ILcdModelDecoder
aSourceName
- the data source for which the model metadata will be decoded.IOException
- if the metadata cannot be decoded for some reason.ILcdModelDecoder.canDecodeSource(String)
public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
ILcdInputStreamFactoryCapable
setInputStreamFactory
in interface ILcdInputStreamFactoryCapable
aInputStreamFactory
- the input stream factory to be used.public ILcdInputStreamFactory getInputStreamFactory()
ILcdInputStreamFactoryCapable
getInputStreamFactory
in interface ILcdInputStreamFactoryCapable
public void setInvalidCellExceptionHandler(ILcdS57InvalidCellExceptionHandler aHandler)
class javadoc
section "Error handling" for details.
This handler is not invoked when decoding an individual faulty cell directly (not through a
catalog).
Instead, an exception will be thrown from the decode(java.lang.String)
method.aHandler
- the exception handler to be used when decoding individual cells.getInvalidCellExceptionHandler()
,
ILcdS57InvalidCellExceptionHandler
,
setIgnoreInvalidCells(boolean)
public ILcdS57InvalidCellExceptionHandler getInvalidCellExceptionHandler()
setInvalidCellExceptionHandler(ILcdS57InvalidCellExceptionHandler)
public void setIgnoreInvalidCells(boolean aIgnoreInvalidCells)
class javadoc
section "Error handling" for details.
This setting has no effect when decoding an individual faulty cell directly (not through a
catalog).
Instead, an exception will be thrown from the decode(java.lang.String)
method.aIgnoreInvalidCells
- true
when invalid cells should be ignoredisIgnoreInvalidCells()
,
setInvalidCellExceptionHandler(com.luciad.format.s57.ILcdS57InvalidCellExceptionHandler)
public boolean isIgnoreInvalidCells()
true
if invalid cells have to be ignored, false
otherwise.setIgnoreInvalidCells(boolean)
public void setVerifyChecksum(boolean aVerifyChecksum)
aVerifyChecksum
- boolean indicating whether to verify the ENC cell checksums.public boolean isVerifyChecksum()
public void setUseSENCCache(boolean aUseSENCCache)
setSENCCacheDir(File)
.
This setting has no effect when decoding individual cells directly (not from a catalog).aUseSENCCache
- flag indicating whether to use the SENC cache or not.isUseSENCCache()
,
setSENCCacheDir(File)
public boolean isUseSENCCache()
true
if the SENC cache is being used, false
otherwise.
This setting has no effect when decoding individual cells directly (not from a catalog).true
if the SENC cache is being used, false
otherwise.setUseSENCCache(boolean)
public void setSENCCacheDir(File aSENCCacheDir)
.senccache
directory in the user's home folder.
If the specified directory does not exist yet, it will be automatically created by the
decoder.
SENC caches are not thread-safe: they should not be used simultaneously by multiple decoder
instances; if multiple decoder instances run simultaneously they should all have their own
SENC
cache dir.
aSENCCacheDir
- the SENC cache dir where the converted SENC copies of S-57 cells should
be
stored.getSENCCacheDir()
,
setUseSENCCache(boolean)
public File getSENCCacheDir()
setSENCCacheDir(File)
,
setUseSENCCache(boolean)