TLcdKML22ModelDecoder (LuciadLightspeed API documentation)

java.lang.Object
- com.luciad.format.xml.bind.schema.ALcdXMLModelDecoder
- - com.luciad.format.kml22.xml.TLcdKML22ModelDecoder

All Implemented Interfaces:: ILcdInputStreamFactoryCapable, ILcdModelDecoder

@LcdService(service=ILcdModelDecoder.class,
            priority=20000)
public class TLcdKML22ModelDecoder
extends ALcdXMLModelDecoder

This model decoder decodes KML (Keyhole Markup Language) files into ILcdModel objects.

Input files

File	Required	Entry point	Description
*.kml		x	A KML file
*.kmz		x	Zip archive containing a KML (.kml) file and possibly other resources

Supported file transfer protocols

This model decoder supports all transfer protocols that are supported by the inputStreamFactory of this decoder.

Model structure

This model decoder creates a TLcdKML22Kml model per KML file.
All models (TLcdKML22Kml instances) returned by this model decoder implement ILcdModelTreeNode,ILcd2DBoundsIndexedModel and ILcdIntegerIndexedModel.

A TLcdKML22Kml has a hierarchical structure, which is organized in accordance with the KML file. The following model implementations can be encountered in the KML model hierarchy:

KML container type	LuciadLightspeed KML class	Implemented LuciadLightspeed interfaces
KML	`TLcdKML22Kml`	`ILcdModelTreeNode, ILcd2DBoundsIndexedModel, ILcdIntegerIndexedModel`
Abstract container	`TLcdKML22AbstractContainer`	`ILcdModelTreeNode, ILcd2DBoundsIndexedModel, ILcdIntegerIndexedModel`
Document	`TLcdKML22Document`	`ILcdModelTreeNode, ILcd2DBoundsIndexedModel, ILcdIntegerIndexedModel`
Folder	`TLcdKML22Folder`	`ILcdModelTreeNode, ILcd2DBoundsIndexedModel, ILcdIntegerIndexedModel`
Network Link	`TLcdKML22NetworkLink`	`ILcdModelTreeNode`

For example, a sample KML file with the following file structure:


     <kml>
       <document>
         <folder>
           <placemark>...</placemark>
         </folder>
       </document>
     </kml>

will be decoded into the following model hierarchy:


     TLcdKML22Kml (implements ILcdModelTreeNode)
      |
      +-- TLcdKML22Document (implements ILcdModelTreeNode)
           |
           + TLcdKML22Folder (implements ILcdModelTreeNode) -> has placemark element.

Model descriptor

All models returned by this model decoder have a TLcdKML22ModelDescriptor.
All models returned by this model decoder will have a model descriptor with a TLcdKML22ResourceProvider. This is for convenience. The TLcdKML22ResourceProvider itself is not used in the decoded model, but can be used when constructing TLcdKML22DynamicModel instances. Note that only the root model will have this resource provider in its model decoder.
The type name of the model descriptor is the display name of this decoder.

Model reference

All models returned by this model decoder have a TLcdGeodeticReference, WGS84.
This model reference is imposed by the KML specification.

Model elements

The following table gives an overview of all possible elements that can occur in a model, together with the main LuciadLightspeed interfaces they implement:

KML type	LuciadLightspeed KML class	Implemented LuciadLightspeed interfaces
Placemark	`TLcdKML22Placemark`	`ILcdShapeList`
Ground overlay	`TLcdKML22GroundOverlay`	`ILcdBounded`
Screen overlay	`TLcdKML22ScreenOverlay`
Photo overlay	`TLcdKML22PhotoOverlay`	`ILcdBounded`
DAE (3D) model	`TLcdKML223DModel`	`ILcdBounded`

Useful settings

KML models can contain dynamic contents. In order to enable dynamic contents, a static KML model (TLcdKML22Kml instance) needs to be wrapped in a TLcdKML22DynamicModel. This model will resolve and include dynamic contents on-the-fly.
In order to be rendered with the correct object order, a TLcdKMl22DynamicModel can be wrapped in a TLcdKML22RenderableModel. This model will flatten the model hierarchy of a TLcdKML22Kml and make sure all objects are processed (via either applyOnInteract or elements in the right order.

Sample code

Decoding and visualizing KML data on a Lightspeed view:

    //First create the model
    ILcdModelDecoder decoder =
        new TLcdCompositeModelDecoder(TLcdServiceLoader.getInstance(ILcdModelDecoder.class));
    ILcdModel model = decoder.decode("Data/Kml/luciad.kml");

    //Create a layer for the model using the layer builder
    ILspLayer layer = TLspKML22LayerBuilder.newBuilder()
                                           .model(model)
                                           .build();

    //Add the layer to the Lightspeed view (an ILspView)
    view.addLayer(layer);

Decoding and visualizing KML data on a GXY view:

    //First create the model
    ILcdModelDecoder decoder =
        new TLcdCompositeModelDecoder(TLcdServiceLoader.getInstance(ILcdModelDecoder.class));
    ILcdModel model = decoder.decode("Data/Kml/luciad.kml");

    //Create a layer for the model
    ILcdGXYLayer layer = new TLcdKML22GXYLayerFactory().createGXYLayer(model);
    //Wrap the layer with an async layer wrapper to ensure
    //that the view remains responsive while data is being painted
    layer = ILcdGXYAsynchronousLayerWrapper.create(layer);

    //Add the async layer to the GXY view (an ILcdGXYView)
    view.addGXYLayer(layer);

Performance tips

Thread safety

The decoding of models is thread-safe.

Supported versions and specifications

This model decoder fully supports OGC KML version 2.2 (namespace http://www.opengis.net/kml/2.2).
The following namespaces are also recognized:
- http://www.opengis.net/kml/2.0
- http://www.opengis.net/kml/2.1
- http://earth.google.com/kml/2.0
- http://earth.google.com/kml/2.1
- http://earth.google.com/kml/2.2
Although these versions are not fully supported, most of the files will be handled correctly by this decoder.

Known limitations

No support for PhotoOverlays.
No support for cookies and other advanced network support.

Since:: 10.0

Constructor Summary

Constructors
Constructor and Description

TLcdKML22ModelDecoder()
Creates a new TLcdKML22ModelDecoder that is capable of decoding KML files

Constructors
Constructor and Description
`TLcdKML22ModelDecoder()` Creates a new `TLcdKML22ModelDecoder` that is capable of decoding KML files

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`canDecodeSource(String aSourceName)` Checks whether this model decoder can decode the specified data source.
`ILcdModel`	`decode(Source aSource)` Creates a new model from the given data source.
`ILcdModel`	`decode(String aSourceName)` Creates a new model from the given data source.
`ILcdModel`	`decode(String aSourceName, InputStream aInputStream, Map<String,String> aExtraParameters)` A decode method that supplies an additional map of parameters that can be used to query a server.
`String`	`getDisplayName()` Returns a short, displayable name for the format that is decoded by this `ILcdModelDecoder`.
`EntityResolver2`	`getEntityResolver()` Returns the `org.xml.sax.ext.EntityResolver2` that is used for creating input sources for XSD schemas.
`ILcdExceptionHandler`	`getExceptionHandler()` Gets the exception handler used by this model decoder
`ILcdInputStreamFactory`	`getInputStreamFactory()` Returns the `ILcdInputStreamFactory` that is used for creating input streams.
`TLcdKML22ResourceProvider`	`getResourceProvider()` Gets the resource provider used by this model decoder.
`XMLInputFactory`	`getXMLInputFactory()` Returns the `javax.xml.stream.XMLInputFactory` that is used by this decoder for creating `javax.xml.stream.XMLStreamReader` instances.
`boolean`	`isUseApplicationSchemaCache()` Returns if application schemas are cached.
`void`	`setEntityResolver(EntityResolver2 aEntityResolver)` Sets the `org.xml.sax.ext.EntityResolver2` to be used for creating input sources for XSD schemas.
`void`	`setExceptionHandler(ILcdExceptionHandler aExceptionHandler)` Sets the exception handler to use by this model decoder.
`void`	`setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)` Sets the `ILcdInputStreamFactory` to be used for creating input streams.
`void`	`setResourceProvider(TLcdKML22ResourceProvider aResourceProvider)` Sets the resource provider this model decoder should use.
`void`	`setUseApplicationSchemaCache(boolean aUseCache)` Enables or disables application schema caching depending on the parameter value.
`void`	`setXMLInputFactory(XMLInputFactory aXMLInputFactory)` Sets the `javax.xml.stream.XMLInputFactory` to be used by this decoder for creating `javax.xml.stream.XMLStreamReader` instances.

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
canDecodeSource, decodeModelMetadata, decodeModelMetadata, decodeSource, discoverDataSources

- Constructor Detail
  - TLcdKML22ModelDecoder
```
public TLcdKML22ModelDecoder()
```
    Creates a new TLcdKML22ModelDecoder that is capable of decoding KML files
    
    The TLcdKML22ModelDecoder will create a resource provider that can be retrieved using the getResourceProvider() method.
- Method Detail
  - getDisplayName
```
public String getDisplayName()
```
    Description copied from interface: ILcdModelDecoder
    
    Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.
    
    Returns:
    
    the displayable name of this ILcdModelDecoder.
  - canDecodeSource
```
public boolean canDecodeSource(String aSourceName)
```
    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.
    
    Parameters:
    
    aSourceName - 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:
    
    ILcdModelDecoder.decode(String), ILcdModelDecoder.decodeModelMetadata(String)
  - decode
```
public ILcdModel decode(String aSourceName)
                 throws IOException
```
    Description copied from interface: ILcdModelDecoder
    
    Creates a new model from the given data source.
    Parameters:
    
    aSourceName - 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); } }
    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)
  - decode
```
public ILcdModel decode(String aSourceName,
                        InputStream aInputStream,
                        Map<String,String> aExtraParameters)
                 throws IOException
```
    A decode method that supplies an additional map of parameters that can be used to query a server.
    
    Parameters:
    
    aSourceName - The source name of the file
    
    aInputStream - An inputstream that should be used
    
    aExtraParameters - Additional parameters that should be passed to the server
    
    Returns:
    
    A TLcdKML22Kml
    
    Throws:
    
    IOException - if the file could not be found or decoded
  - getInputStreamFactory
```
public ILcdInputStreamFactory getInputStreamFactory()
```
    Description copied from class: ALcdXMLModelDecoder
    
    Returns the ILcdInputStreamFactory that is used for creating input streams.
    
    Specified by:
    
    getInputStreamFactory in interface ILcdInputStreamFactoryCapable
    
    Specified by:
    
    getInputStreamFactory in class ALcdXMLModelDecoder
    
    Returns:
    
    the ILcdInputStreamFactory that is used for creating input streams.
    
    See Also:
    
    ALcdXMLModelDecoder.setInputStreamFactory(com.luciad.io.ILcdInputStreamFactory)
  - setInputStreamFactory
```
public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
```
    Description copied from class: ALcdXMLModelDecoder
    
    Sets the ILcdInputStreamFactory to be used for creating input streams. If the configured entity resolver implements ILcdInputStreamFactoryCapable, it is also configured with this factory.
    
    Specified by:
    
    setInputStreamFactory in interface ILcdInputStreamFactoryCapable
    
    Specified by:
    
    setInputStreamFactory in class ALcdXMLModelDecoder
    
    Parameters:
    
    aInputStreamFactory - the input stream factory to be used by this model decoder.
    
    See Also:
    
    ALcdXMLModelDecoder.getInputStreamFactory()
  - getExceptionHandler
```
public ILcdExceptionHandler getExceptionHandler()
```
    Gets the exception handler used by this model decoder
    
    Returns:
    
    an ILcdExceptionHandler
  - setExceptionHandler
```
public void setExceptionHandler(ILcdExceptionHandler aExceptionHandler)
```
    Sets the exception handler to use by this model decoder.
    
    Not all KML files are properly formatted. KML files can refer to non-existent resources, or have a structure that does not conform to the OGC standard. The exception handler will be informed of such problems. If no ILcdExceptionHandler is set, the exceptions will be logged to the LuciadLightspeed logging framework.
    
    Parameters:
    
    aExceptionHandler - an ILcdExceptionHandler
  - getResourceProvider
```
public TLcdKML22ResourceProvider getResourceProvider()
```
    Gets the resource provider used by this model decoder.
    
    Returns:
    
    a TLcdKML22ResourceProvider
  - setResourceProvider
```
public void setResourceProvider(TLcdKML22ResourceProvider aResourceProvider)
```
    Sets the resource provider this model decoder should use.
    
    Note that the constructor will already create a resource provider, and this method should not be called unless you want to change the default resource provider
    
    Parameters:
    
    aResourceProvider - a TLcdKML22ResourceProvider
  - getEntityResolver
```
public EntityResolver2 getEntityResolver()
```
    Description copied from class: ALcdXMLModelDecoder
    
    Returns the org.xml.sax.ext.EntityResolver2 that is used for creating input sources for XSD schemas. This entity resolver will only be used to resolve extension schemas that are not already configured on this decoder.
    
    Specified by:
    
    getEntityResolver in class ALcdXMLModelDecoder
    
    Returns:
    
    the entity resolver to be used for creating input sources for XSD schemas.
  - getXMLInputFactory
```
public XMLInputFactory getXMLInputFactory()
```
    Description copied from class: ALcdXMLModelDecoder
    
    Returns the javax.xml.stream.XMLInputFactory that is used by this decoder for creating javax.xml.stream.XMLStreamReader instances.
    
    Specified by:
    
    getXMLInputFactory in class ALcdXMLModelDecoder
    
    Returns:
    
    the javax.xml.stream.XMLInputFactory that is used by this decoder for creating javax.xml.stream.XMLStreamReader instances.
  - isUseApplicationSchemaCache
```
public boolean isUseApplicationSchemaCache()
```
    Description copied from class: ALcdXMLModelDecoder
    
    Returns if application schemas are cached. When application schemas are cached, the decoder caches all applications schemas it encounters. When a certain schema is referenced during decoding, only if the schema is not found in the cache, it will be resolved. The default is not to cache.
    
    Note that in case multiple application schemas use the same namespace URI, it is not possible to turn on application schema caching because the decoder will not be able to discern between the different schemas.
    
    Specified by:
    
    isUseApplicationSchemaCache in class ALcdXMLModelDecoder
    
    Returns:
    
    if application schemas are cached
  - setEntityResolver
```
public void setEntityResolver(EntityResolver2 aEntityResolver)
```
    Description copied from class: ALcdXMLModelDecoder
    
    Sets the org.xml.sax.ext.EntityResolver2 to be used for creating input sources for XSD schemas.
    
    When the entity resolver is unable to find a schema (i.e. the resolveEntity method returns null), the ALcdXMLModelDecoder.getInputStreamFactory() is used to create an appropriate input stream for the given system id of the schema.
    
    Specified by:
    
    setEntityResolver in class ALcdXMLModelDecoder
    
    Parameters:
    
    aEntityResolver - the entity resolver to be used for creating input sources for XSD schemas.
  - setUseApplicationSchemaCache
```
public void setUseApplicationSchemaCache(boolean aUseCache)
```
    Description copied from class: ALcdXMLModelDecoder
    
    Enables or disables application schema caching depending on the parameter value.
    
    Specified by:
    
    setUseApplicationSchemaCache in class ALcdXMLModelDecoder
    
    Parameters:
    
    aUseCache - if true, application schema caching is turned on. If false, caching is turned off.
  - setXMLInputFactory
```
public void setXMLInputFactory(XMLInputFactory aXMLInputFactory)
```
    Description copied from class: ALcdXMLModelDecoder
    
    Sets the javax.xml.stream.XMLInputFactory to be used by this decoder for creating javax.xml.stream.XMLStreamReader instances.
    
    Specified by:
    
    setXMLInputFactory in class ALcdXMLModelDecoder
    
    Parameters:
    
    aXMLInputFactory - the javax.xml.stream.XMLInputFactory to be used by this decoder for creating javax.xml.stream.XMLStreamReader instances.
  - decode
```
public ILcdModel decode(Source aSource)
                 throws IOException
```
    Creates a new model from the given data source.
    
    Overrides:
    
    decode in class ALcdXMLModelDecoder
    
    Parameters:
    
    aSource - the source to read the model from
    
    Throws:
    
    UnsupportedOperationException - in case the decoder is not able to decode from the source
    
    IOException
    
    See Also:
    
    decode(String)

LuciadLightspeedClass TLcdKML22ModelDecoder

Input files

Supported file transfer protocols

Model structure

Model descriptor

Model reference

Model elements

Useful settings

Sample code

Performance tips

Thread safety

Supported versions and specifications

Known limitations

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface com.luciad.model.ILcdModelDecoder

Constructor Detail

TLcdKML22ModelDecoder

Method Detail

getDisplayName

canDecodeSource

decode

decode

getInputStreamFactory

setInputStreamFactory

getExceptionHandler

setExceptionHandler

getResourceProvider

setResourceProvider

getEntityResolver

getXMLInputFactory

isUseApplicationSchemaCache

setEntityResolver

setUseApplicationSchemaCache

setXMLInputFactory

decode