@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdS63UnifiedModelDecoder extends Object implements ILcdModelDecoder,ILcdDataSourceModelDecoder, ILcdMetadataDecoder, ILcdInputStreamFactoryCapable
The equivalent decoder of TLcdS57UnifiedModelDecoder
for S-57 data which
is encrypted according to the S-63 standard. These formats are published by the International Hydrographic Organization
in "IHO Transfer Standard for Digital Hydrographic Data, Special Publications No. 57
and No. 63"
To decode S-63 data, the following properties should be set on the decoder:
setSACertificateSource(String
aSourceName)
) orsetSAPublicKeySource(String aSourceName)
)setBasicPermitSource(String
aSourceName)
or setBasicPermitSources(List<String> aSourceNames)
)
orsetMetaPermitSource(String
aSourceName)
) or setMetaPermitSources(List<String> aSourceNames)
Additionally, when you are not an Ecdis manufacturer yourself, the running LuciadLightspeed license should contain a valid S-63 User Permit. The model decoder will only work with S-63 files which were provided for this User Permit. Consult the developer guide for more information on how to work with User Permits.
The decoded models have the same structure as the models from the TLcdS57UnifiedModelDecoder
, which
depends on whether a catalogue or a single cell is decoded. The only difference is that the model descriptor
is a TLcdS63ModelDescriptor
on the individual cell models.
File | Required | Entry point | Description |
---|---|---|---|
CATALOG.031 | x | x | An S-63 catalog |
*.000 | x | x | An S-63 individual cell |
ILcdInputStreamFactory
of this decoder.TLcdS57UnifiedModelDecoder
.
TLcdS63ModelDescriptor
, with type S-63
.TLcdS57CatalogueModelDescriptor
, with type S-57 Catalogue
, and the models for each cell will have TLcdS63ModelDescriptor
, with type S-63
.TLcdGeodeticReference
, as described by the specification.TLcdS57ModelDecoder
for more information on domain objects.
setVerifyChecksum(boolean)
to toggle file checksum validation.setMetaPermitSources(java.util.List<java.lang.String>)
or setBasicPermitSources(java.util.List<java.lang.String>)
to configure your cell permit files. By default, this decoder will look for permit files next to the data.setSACertificateSources(java.util.List<java.lang.String>)
and setSACertificateSources(java.util.List<java.lang.String>)
to set the location of the SA's digital certificates.setDoAuthentication(boolean)
to toggle verification of cell contains with the digital signature file.
ILcdModelDecoder decoder = new TLcdS63UnifiedModelDecoder();
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
.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.
Your handler's handleCellWarnings
will be called during
decode(java.lang.String)
with TLcdS63Exception
s to notify you of issues with cells}:
SSE_011
). These cells will not be loaded.SSE_020
). The cells will still be loaded.SSE_015
). The cells will still be loaded.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.
TLcdS57UnifiedModelDecoder
.TLcdS57ModelDecoder
.ILcdMetadataDecoder.MetadataWithSource
Constructor and Description |
---|
TLcdS63UnifiedModelDecoder()
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)
The S-63 metadata has a similar structure as the S-57 one.
|
TLcdModelMetadata |
decodeModelMetadata(String aSourceName)
Decodes metadata for the specified data source.
|
ILcdModel |
decodeSource(ILcdDataSource aDataSource)
Creates a new model from the given data source.
|
List<String> |
getBasicPermitSources()
|
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.
|
List<String> |
getMetaPermitSources()
|
List<String> |
getSACertificateSources()
|
List<String> |
getSAPublicKeySources()
|
File |
getSENCCacheDir()
Returns the SENC cache dir where the converted SENC copies of S-57 cells should be stored.
|
String |
getUserPermit()
|
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 |
setBasicPermitSources(List<String> aSourceNames)
|
void |
setDoAuthentication(boolean aDoAuthentication)
|
static void |
setEncryptedHardwareID(String aHardwareID)
Sets an encrypted version of the hardware ID (
HW_ID ) of this system. |
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 |
setMetaPermitSources(List<String> aSourceNames)
|
static void |
setS63CustomerSystemID(String aS63CustomerSystemId)
Configures the S63 Customer System ID, a unique ID used to identify an S-63 system.
|
void |
setSACertificateSources(List<String> aSourceNames)
|
void |
setSAPublicKeySources(List<String> aSourceNames)
|
void |
setSENCCacheDir(File aSENCCacheDir)
Sets the SENC cache dir where the converted SENC copies of S-57 cells should be stored.
|
static void |
setUnencryptedHardwareID(String aHardwareID)
Sets an unencrypted version of the hardware ID (
HW_ID ) of this system. |
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 TLcdS63UnifiedModelDecoder()
public static void setS63CustomerSystemID(String aS63CustomerSystemId)
com.luciad.format.s63.s63CustomerSystemID
:
-Dcom.luciad.format.s63.s63CustomerSystemID=mys63idThe system property will be overridden if the setter method is used.
TLcyS63FormatAddOn.s63CustomerSystemID
configuration setting of the S-63 add-on (TLcyS63FormatAddOn.cfg
).
If your LuciadLightspeed license is not linked to an S-63 Customer System ID, you should not use this method.
If your LuciadLightspeed license is linked to an S-63 Customer System ID, you must set the ID
before using canDecodeSource(java.lang.String)
or decode(java.lang.String)
, or they will return false
and throw IllegalArgumentException
, respectively.
The ID is verified against the ID linked to your LuciadLightspeed license. If the ID does not match:
IllegalArgumentException
canDecodeSource(java.lang.String)
returns false
decode(java.lang.String)
throws IllegalArgumentException
aS63CustomerSystemId
- The ID to validate withIllegalArgumentException
- if the given ID does not match the ID linked with your license.public static void setUnencryptedHardwareID(String aHardwareID)
Sets an unencrypted version of the hardware ID (HW_ID
) of this system.
This method will encrypt the hardware ID, and pass it to the setEncryptedHardwareID(String)
method.
For convenience, this method is available on all of the S-63 model decoder classes
(TLcdS63UnifiedModelDecoder
, TLcdS63CatalogueModelDecoder
and TLcdS63ModelDecoder
).
It is sufficient to call this method once on any of model decoders.
aHardwareID
- The 5-digit hexadecimal number.
For example "A79AB"setEncryptedHardwareID(String)
public static void setEncryptedHardwareID(String aHardwareID)
Sets an encrypted version of the hardware ID (HW_ID
) of this system.
This method can only be called when you are a manufacturer of ECDIS systems,
and have bought a corresponding license.
You can check whether your license supports this by opening the development_license.txt file
(this file is located inside the development_license.jar file).
It must contain the s63Manufacturer = true
key-value pair.
If you want to specify the hardware ID using the API and do not want to do the encryption yourself,
you can use the setUnencryptedHardwareID(String)
method instead.
If you want to do the encryption yourself, you can use the following code which uses an RSA encryption:
String hardwareID = ... ;//5-digit hexadecimal number (for example "A79AB")
byte[] rsa_n = {0, -51, -16, -29, -89, -15, -58, -106, -80, -113, -6, 64, -111, -85, -60, -10, 47};
byte[] rsa_e = {0, -128, -23};
BigInteger hw_id_encrypted = new BigInteger(hardwareID, 16).modPow(new BigInteger(rsa_e), new BigInteger(rsa_n));
return hw_id_encrypted.toString(16);
The encrypted hardware ID can also be specified using a system property. Setting the unencrypted hardware ID using the system property is not supported.
-Dcom.luciad.format.s63.encryptedHardwareID=xxxxxxx
The S-63 specification requires that manufacturers take the necessary precautions to ensure that the HW_ID
remains unknown to the end-user of the system.
This method works with an encrypted form of the HW_ID
, but this is not sufficient to ensure proper protection
of the HW_ID
.
It is up to the manufacturer using the Luciad API to ensure that the end-user has no access to the runtime environment,
and that the (encoded) version of the HW_ID
is not accessible by the user.
Note: this method should be called before triggering any S-63 related code. Calling this method a second time after any S-63 related code has been triggered has no effect.
For convenience, this method is available on all of the S-63 model decoder classes
(TLcdS63UnifiedModelDecoder
, TLcdS63CatalogueModelDecoder
and TLcdS63ModelDecoder
).
It is sufficient to call this method once on any of model decoders.
aHardwareID
- The encrypted version of the 5-digit hexadecimal number.setUnencryptedHardwareID(String)
public void setDoAuthentication(boolean aDoAuthentication)
public String getUserPermit()
public String getDisplayName()
ILcdModelDecoder
ILcdModelDecoder
.getDisplayName
in interface ILcdModelDecoder
ILcdModelDecoder
.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)
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 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 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
"ENC.PMT"
and/or "PERMIT.TXT"
are added as support files to the aggregate.
These permit files need to be next to the "CATALOG.031"
file in the catalog directory.
Permits in other (user-defined) directories are not part of the metadata.decodeMetadata
in interface ILcdMetadataDecoder
aSourceName
- the source name to decode metadata fromIOException
- if the metadata cannot be decoded for some reasonTLcdS57UnifiedModelDecoder.decodeMetadata(String)
public boolean canDecodeSource(ILcdDataSource aDataSource)
Return true
if:
TLcdS57CatalogueDataSource
.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)