Package com.luciad.format.s101.model

Class TLcdS101ModelDecoder

java.lang.Object
com.luciad.format.s101.model.TLcdS101ModelDecoder
All Implemented Interfaces:
ILcdModelDecoder
@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdS101ModelDecoder extends Object implements ILcdModelDecoder

This model decoder decodes ECDIS S-101 data into ILcdModel objects.

This model decoder is capable of decoding catalogue files and single cell files.

Input

Note: The decoder also supports the simultaneous decoding of multiple catalogues as a single, virtual catalogue. To decode multiple catalogues simultaneously, put the catalogue directories in a common parent directory, and place an empty file, called MULTICATALOG.XML, in this parent directory. When decoding this file, the decoder will automatically scan for catalogues in the subdirectories and decode them as one catalogue.
File Required Entry point Description
catalog.xml x x
 An S-101 catalog
101*.000 x x
 Individual S-101 cells

Supported file transfer protocols

  • This model decoder only decodes data from a file system.

Model structure

  • When decoding an exchange catalogue, the decoder will return an ILcdModelContainer, with one sub-model for each individual cell file referenced by the catalogue. Otherwise, an individual model is returned.
  • All models returned by this model decoder implement ILcd2DBoundsIndexedModel.

Model descriptor

  • All models returned by this model decoder have a TLcdS101ModelDescriptor.
  • The type name of the model descriptor is the display name of this decoder.
  • The descriptor provides access to a TLcdDataModel defining all the S-101 feature types.

Model reference

Useful settings

  • When loading encrypted S-101 data, the decoder will by default look for the PERMIT.XML file in the same directory as your CATALOG.XML file. To load permit files in other locations, install a permit provider function.
  • If you are acting as the system manufacturer (instead of Luciad) and therefore issue your own user permits to your end users, you need to set your manufacturer key on the decoder for data decryption to work.

Model elements

Sample code


 ILcdModelDecoder decoder = new TLcdS101ModelDecoder();
 ILcdModel model = decoder.decode("file.000");

Performance tips

  • The use of exchange catalogues is recommended over the decoding of individual cell files, since it allows the cells to be loaded lazily, based on the current extents and zoom level of the map.

Thread safety

  • The decoding of models is thread-safe.
  • The decoded models are thread-safe for read access.

Supported versions and specifications

  • This decoder is based on the IHO S-101 ENC Product Specification, Edition 2.0.0. The specification is available for download from the IHO's website.

Known limitations

  • Data which is not based on Edition 2.0.0 or later of the S-101 specification (see above) might not be decoded correctly.
  • Data decryption is only supported when loading a catalog file. Decryption is not currently possible when loading individual cell (*.000) files.
  • As the S‑101 format is still relatively new and current test data — including the official S‑164 dataset for the final S‑101 2.0 version — remains limited, our S‑101 implementation cannot yet be guaranteed as fully complete. We will continue to monitor updates and refine the implementation as new test data becomes available.

Requirements

  • This decoder is part of the Maritime Standards component.
  • The decoder uses native libraries, for which the appropriate platform-specific JAR file (libs101-*-native.*.jar) must be available on the Java classpath.
Since:
2026.0

  • Constructor Details

    • TLcdS101ModelDecoder

      public TLcdS101ModelDecoder()

  • Method Details

    • 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 aSource)
      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:
      aSource - 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:

    • decode

      public ILcdModel decode(String aSource) throws IOException
      Description copied from interface: ILcdModelDecoder
      Creates a new model from the given data source.
      Specified by:
      decode in interface ILcdModelDecoder
      Parameters:
      aSource - 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);
      }
   }
      See Also:

    • setPermitProvider

      public void setPermitProvider(Function<String,String> aPermitProvider)
      Sets a function which, given a path to a CATALOG.XML file, returns the path to the corresponding PERMIT.XML file. This function is used when decoding encrypted S-101 data. By default, the PERMIT.XML file is assumed to be located next to the CATALOG.XML file.
      Parameters:
      aPermitProvider - a function which returns the permit file to be used for a given catalog file

    • setManufacturerKey

      public void setManufacturerKey(String aManufacturerKey)
      Sets the manufacturer key used to decrypt S-101 user permits. If no value is specified, Luciad's key is used. Changing the key is only necessary if you need to consume S-101 data which was not encrypted with a user permit issued by Luciad.

      Note that the key can also be set using the system property com.luciad.format.s101.s101ManufacturerKey.

      Parameters:
      aManufacturerKey - the manufacturer key used to decrypt S-101 user permits