com.luciad.lucy.model

LuciadLightspeedClass TLcyCompositeModelDecoder

java.lang.Object

com.luciad.lucy.util.TLcyGenericComposite<TLcyModelDecoderHolder>

com.luciad.lucy.model.TLcyCompositeModelDecoder

All Implemented Interfaces:

ILcyModelDecoderContainer , ILcdDataSourceModelDecoder , ILcdModelDecoder, Iterable<TLcyModelDecoderHolder>

public class TLcyCompositeModelDecoder
extends TLcyGenericComposite<TLcyModelDecoderHolder>
implements 
ILcdDataSourceModelDecoder
, 
ILcyModelDecoderContainer

Composite implementation (see composite design pattern) of ILcdModelDecoder. It keeps a list of associated ILcdModelDecoders. When it is asked to decode a model, it loops over its associated ILcdModelDecoders to find a suitable ILcdModelDecoder. That ILcdModelDecoder is asked to decode a model.

When creating a new TLcyCompositeModelDecoder using the default constructor (see TLcyCompositeModelDecoder(), the created instance will only work on/with the ILcdModelDecoders registered on this composite instance (see addModelDecoder(com.luciad.model.ILcdModelDecoder, ALcyFileTypeDescriptor) and removeModelDecoder(com.luciad.model.ILcdModelDecoder).

When creating a new TLcyCompositeModelDecoder using the constructor specifying an ILcyLucyEnv instance (see TLcyCompositeModelDecoder(com.luciad.lucy.ILcyLucyEnv), the created instance will work on the Lucy back-end services. It will use all registered ILcdModelDecoder instances of the Lucy back-end, adding and/or removing an ILcdModelDecoder will add/remove the ILcdModelDecoder as service from Lucy, ... .

Decoding a source into an ILcdModel using the back-end based implementation can be done by creating a new instance of this class:

 //Create a new instance whenever you need it
 TLcyCompositeModelDecoder decoder = new TLcyCompositeModelDecoder( aLucyEnv );
 try{
   ILcdModel model = decoder.decode( String aSourceName );
 } catch( IOException aException ){
   //an IOException occurred during the decoding of aSourceName
 }
 //There is no need to keep a reference to the composite instance, you can create a new one
 //the next time you would need it
 decoder = null;
 

Note: the ILcdModelDecoders are not directly registered as service to Lucy, but wrapped with a holder object. This holder object allows to register the ILcdModelDecoder with some extra information like e.g. an ALcyFileTypeDescriptor. Using a back-end based TLcyCompositeModelDecoder will only use the registered TLcyModelDecoderHolder objects, and not for example an ILcdModelDecoder which was directly (=not wrapped) registered as a service .

See Also:

TLcyModelDecoderHolder

Field Summary

Fields inherited from class com.luciad.lucy.util.TLcyGenericComposite

PRIORITY_DEFAULT, PRIORITY_FALLBACK

Constructor Summary

Constructors

Constructor and Description
TLcyCompositeModelDecoder() Default constructor.
TLcyCompositeModelDecoder(ILcyLucyEnv aLucyEnv) Construct a TLcyCompositeModelDecoder working on the Lucy back-end.

Method Summary

Modifier and Type	Method and Description
void	addModelDecoder(ILcdModelDecoder aModelDecoder, ALcyFileTypeDescriptor aFileTypeDescriptor) Adds the given model decoder to this container.
boolean	canDecodeSource(ILcdDataSource aDataSource) Loops over its associated list of ILcdModelDecoders to find a suitable ILcdModelDecoder.
boolean	canDecodeSource(String aSourceName) Loops over its associated list of ILcdModelDecoders to find a suitable ILcdModelDecoder.
ILcdModel	decode(String aSourceName) Loops over its associated list of ILcdModelDecoders to find a suitable ILcdModelDecoder.
ILcdModel	decodeSource(ILcdDataSource aDataSource) Loops over its associated list of ILcdModelDecoders to find a suitable ILcdModelDecoder.
ALcyFileTypeDescriptor	getDecoderFileTypeDescriptor(int aIndex) Retrieves the file type descriptor at the given index, or null if the decoder was added with null as a descriptor.
String	getDisplayName() Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.
ILcdModelDecoder	getModelDecoder(int aIndex) Returns the model decoder at the given index.
int	getModelDecoderCount() Returns the number of model decoders currently in this container.
void	removeModelDecoder(ILcdModelDecoder aModelDecoder) Removes the given model decoder from this container.

Methods inherited from class com.luciad.lucy.util.TLcyGenericComposite

add, add, getList, getPriority, iterator, remove

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

decodeModelMetadata, decodeModelMetadata, discoverDataSources

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

TLcyCompositeModelDecoder

public TLcyCompositeModelDecoder()

Default constructor. No ILcdModelDecoders are associated.

The created instance will only work on the ILcdModelDecoder instances registered to it. If you want to use all registered ILcdModelDecoder instances of the Lucy back-end, use TLcyCompositeModelDecoder(com.luciad.lucy.ILcyLucyEnv) instead.

See Also:

TLcyCompositeModelDecoder(com.luciad.lucy.ILcyLucyEnv)

TLcyCompositeModelDecoder

public TLcyCompositeModelDecoder(ILcyLucyEnv aLucyEnv)

Construct a TLcyCompositeModelDecoder working on the Lucy back-end.

It will use all ILcdModelDecoder instances registered to the back-end, and adding and/or removing ILcdModelDecoders to/from this TLcyCompositeModelDecoder will respectively add/remove it as service from the back-end.

If you want to create a TLcyCompositeModelDecoder which does not use the back-end, use TLcyCompositeModelDecoder() instead.

Parameters:

aLucyEnv - The Lucy back-end.

See Also:

TLcyCompositeModelDecoder(), ILcyLucyEnv.addService(Object, int), ILcyLucyEnv.removeService(Object)

Method Detail

addModelDecoder

public void addModelDecoder(ILcdModelDecoder aModelDecoder,
                            ALcyFileTypeDescriptor aFileTypeDescriptor)

Adds the given model decoder to this container.

If the constructor specifying an ILcyLucyEnv is used, the ALcyFileTypeDescriptor and its associated ILcdModelDecoder will be registered on the Lucy back-end (see ILcyLucyEnv.addService(Object, int) by using an TLcyModelDecoderHolder. When calling ILcyLucyEnv.getServices(Class) afterwards, the holder objects will only be returned when the requested class was TLcyModelDecoderHolder.class
Note: if you want to remove the registered ALcyFileTypeDescriptor and its associated ILcdModelDecoder, use removeModelDecoder(com.luciad.model.ILcdModelDecoder) and not ILcyLucyEnv.removeService(Object).

Specified by:

addModelDecoder in interface ILcyModelDecoderContainer

Parameters:

aModelDecoder - The model decoder to add

aFileTypeDescriptor - The file type descriptor that provides more information on the file types this decoder can handle, or null if this decoder does not work with files.

See Also:

removeModelDecoder(com.luciad.model.ILcdModelDecoder)

removeModelDecoder

public void removeModelDecoder(ILcdModelDecoder aModelDecoder)

Removes the given model decoder from this container. Does nothing if the given decoder was not in this container. The corresponding ALcyFileTypeDescriptor is also removed.

If the constructor specifying an ILcyLucyEnv is used, the TLcyModelDecoderHolder object containing the ILcdModelDecoder aModelDecoder will be removed as service from the Lucy back-end (see ILcyLucyEnv.removeService(Object)).
Note: it is only possible to remove TLcyModelDecoderHolder instances which were registered using the addModelDecoder(com.luciad.model.ILcdModelDecoder, ALcyFileTypeDescriptor) method.

Specified by:

removeModelDecoder in interface ILcyModelDecoderContainer

Parameters:

aModelDecoder - The model decoder to remove.

See Also:

addModelDecoder(com.luciad.model.ILcdModelDecoder, ALcyFileTypeDescriptor)

getModelDecoderCount

public int getModelDecoderCount()

Description copied from interface: ILcyModelDecoderContainer

Returns the number of model decoders currently in this container.

Specified by:

getModelDecoderCount in interface ILcyModelDecoderContainer

Returns:

the number of model decoders currently in this container.

getModelDecoder

public ILcdModelDecoder getModelDecoder(int aIndex)

Description copied from interface: ILcyModelDecoderContainer

Returns the model decoder at the given index.

Specified by:

getModelDecoder in interface ILcyModelDecoderContainer

Parameters:

aIndex - The index of the asked model decoder. Make sure 0 <= aIndex < ILcyModelDecoderContainer.getModelDecoderCount()

Returns:

The model decoder at the given index.

getDecoderFileTypeDescriptor

public ALcyFileTypeDescriptor getDecoderFileTypeDescriptor(int aIndex)

Description copied from interface: ILcyModelDecoderContainer

Retrieves the file type descriptor at the given index, or null if the decoder was added with null as a descriptor.

Specified by:

getDecoderFileTypeDescriptor in interface ILcyModelDecoderContainer

Parameters:

aIndex - The index to retrieve the file type descriptor for.

Returns:

the file type descriptor at the given index.

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)

Loops over its associated list of ILcdModelDecoders to find a suitable ILcdModelDecoder. Suitable means that canDecodeSource returns true. If it can find such a suitable ILcdModelDecoder it returns true, false otherwise.

Specified by:

canDecodeSource in interface ILcdModelDecoder

Parameters:

aSourceName - The name of the source to decode.

Returns:

True if a suitable ILcdModelDecoder could be found, false otherwise.

See Also:

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

canDecodeSource

public boolean canDecodeSource(ILcdDataSource aDataSource)

Loops over its associated list of ILcdModelDecoders to find a suitable ILcdModelDecoder. Suitable means that canDecodeSource returns true. If it can find such a suitable ILcdModelDecoder it returns true, false otherwise.

Specified by:

canDecodeSource in interface ILcdModelDecoder

Parameters:

aDataSource - The object identifying the data source(s) to decode.

Returns:

True if a suitable ILcdModelDecoder could be found, false otherwise.

See Also:

ILcdModelDecoder.decodeSource(ILcdDataSource), ILcdModelDecoder.decodeModelMetadata(ILcdDataSource)

decode

public ILcdModel decode(String aSourceName)
                 throws IOException

Loops over its associated list of ILcdModelDecoders to find a suitable ILcdModelDecoder. Suitable means that canDecodeSource returns true.

It will first loop over all model decoders for which the associated ALcyFileTypeDescriptor accepts aSourceName. The decode will be delegated to the first of those decoders for which the canDecode returns true.

When none of those model decoders is suitable, it will loop over all available model decoders, and delegate the decode to the first suitable one.

Specified by:

decode in interface ILcdModelDecoder

Parameters:

aSourceName - The name of the source to decode.

Returns:

The model decoded by the first suitable ILcdModelDecoder

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)

decodeSource

public ILcdModel decodeSource(ILcdDataSource aDataSource)
                       throws IOException

Loops over its associated list of ILcdModelDecoders to find a suitable ILcdModelDecoder. Suitable means that canDecodeSource returns true.

The first suitable ILcdModelDecoder is used to decode the given source.

Specified by:

decodeSource in interface ILcdModelDecoder

Parameters:

aDataSource - The object identifying the data source(s) to decode.

Returns:

The model decoded by the first suitable ILcdModelDecoder

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 decodeSource(ILcdDataSource aDataSource) throws IOException {
   try {
     // Perform decoding ...
   } catch (RuntimeException e) {
     throw new IOException(e);
   }
 }
 

See Also:

ILcdModelDecoder.canDecodeSource(ILcdDataSource)