public interface ILcdModelDecoder
ILcdModel instances from files or from other data sources. It also allows
retrieving model metadata without decoding the model itself.
The supported data sources and the type of models (implemented interfaces, structure, contents, ...) that are
created are defined by the actual implementations of this interface.
Each model decoder has a displayable name that identifies the data format, decoded by this decoder.
See the Supporting Custom Formats documentation for some examples on how to implement this interface.
ILcdModel,
ILcdDataSource| Modifier and Type | Method and Description |
|---|---|
default boolean |
canDecodeSource(ILcdDataSource aDataSource)
Checks whether this model decoder can decode the data source(s), identified by the passed
ILcdDataSource. |
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.
|
default TLcdModelMetadata |
decodeModelMetadata(ILcdDataSource aDataSource)
Decodes metadata for the specified data source.
|
default TLcdModelMetadata |
decodeModelMetadata(String aSourceName)
Decodes metadata for the specified data source.
|
default ILcdModel |
decodeSource(ILcdDataSource aDataSource)
Creates a new model from the given data source.
|
default List<? extends ILcdDataSource> |
discoverDataSources(String aPath)
Retrieves a set of model-specific
ILcdDataSource instances. |
String |
getDisplayName()
Returns a short, displayable name for the format that is decoded by this
ILcdModelDecoder. |
String getDisplayName()
ILcdModelDecoder.ILcdModelDecoder.boolean canDecodeSource(String aSourceName)
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.
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.decode(String),
decodeModelMetadata(String)default TLcdModelMetadata decodeModelMetadata(String aSourceName) throws IOException
aSourceName - the data source to be decoded; typically a file name or a URL.IOException - if the metadata cannot be decoded for some reason.canDecodeSource(String)default TLcdModelMetadata decodeModelMetadata(ILcdDataSource aDataSource) throws IOException
aDataSource - the data source to be decoded.IOException - if the metadata cannot be decoded for some reason.canDecodeSource(ILcdDataSource)ILcdModel decode(String aSourceName) throws IOException
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.NullPointerException - if null is not accepted as value for aSourceName by this model decoder.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.canDecodeSource(String)default boolean canDecodeSource(ILcdDataSource aDataSource)
Checks whether this model decoder can decode the data source(s), identified by the passed ILcdDataSource.
For performance reasons, we strongly recommend that this will only be a simple test.
For example: check the instance class of aDataSource,
or check the file extension if it is a TLcdDataSource.
The default implementation of this method will check if the given ILcdDataSource is a
TLcdDataSource. If not, this method returns false. Otherwise, it delegates
the source to the canDecodeSource(String) method.
aDataSource - the ILcdModelSource to be verified.true if this decoder can likely decode the data specified by aDataSource, false
otherwise.decodeSource(ILcdDataSource),
decodeModelMetadata(ILcdDataSource)default ILcdModel decodeSource(ILcdDataSource aDataSource) throws IOException
Creates a new model from the given data source.
By default, this method:
NullPointerException when a null data source is passed.decode(String) method when a TLcdDataSource is passed.aDataSource - the ILcdDataSource to be decoded.null is allowed, implementors are advised to throw an error instead.NullPointerException - if null is not accepted as value for aDataSource by this model decoder.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);
}
}
canDecodeSource(ILcdDataSource)default List<? extends ILcdDataSource> discoverDataSources(String aPath) throws IOException
Retrieves a set of model-specific ILcdDataSource instances.
By default, this method:
TLcdDataSource that contains a reference to the supplied path,
when canDecodeSource(String) returns true for the supplied path.IOException when canDecodeSource(String) returns false for the supplied path.ILcdDataSource, for instance, if the
path references a collection of data sources.
An example where this is useful is for container formats, such as NetCDF. A NetCDF
file can contain multiple measurement layers. This discoverDataSources(String) method
allows you to distinguish between them using ILcdDataSources, where each measurement
layer can be referenced to and decoded separately using decodeSource(ILcdDataSource)
aPath - A path to the data source to be decoded; typically a file path or a URL.true for canDecodeSource(String), it will
return a list containing at least a single ILcdDataSource.IOException - If this model decoder returns false for canDecodeSource(String)
or if any exceptions caused by IO problems or invalid data occur.