com.luciad.format.kml22.util

LuciadFusionClass TLcdKML22DocumentProvider

java.lang.Object

com.luciad.format.kml22.util.TLcdKML22DocumentProvider

public class TLcdKML22DocumentProvider
extends Object

Provider of KML documents.

Documents can be retrieved synchronously or asynchronously. The provider keeps a cache of documents to optimize performance. Documents can also be queried for their status. This status describes whether they are cached or not.

A template for the usage of retrieving documents is as follows:

 
    //variables used in this template
    TLcdKML22DocumentProvider documentProvider;
    TLcdKML22Link link;
    TLcdKML22Parameters parameters;
    ILcdKML22ResourceListener callbackFunction;

    //the template

    //obtain the status of the document to decide what to do
    ELcdKML22ResourceStatus documentStatus = documentProvider.getDocumentStatus( link, parameters );
    TLcdKML22Kml kml = null;
    switch ( documentStatus ) {
      case CACHED:
        //the resource is cached, so you can retrieve it synchronously without blocking the calling
        //thread
        kml = documentProvider.retrieveDocument( link,parameters );
        break;
      case LOADING:
        //the resource is being loaded. Use a temporary KML file instead.
        kml = getTemporaryKMLFile();
        break;
      case FAULTY:
        //the resource is unavailable because it is faulty. A fallback mechanism should be used here
        //because the resource itself can't be retried.
        kml = getFallbackKMLFile();
        break;
      case NOT_CACHED:
        //the resource is not cached. Start an asynchronous retrieve and used a temporary value instead.
        documentProvider.retrieveDocument( link, parameters,callbackFunction );
        kml = getTemporaryKMLFile();
        break;
    }
   
 

Since:

10.0

Method Summary

Modifier and Type	Method and Description
void	addDocument(TLcdKML22Kml aKmlDocument, String aSourceName) Adds a document to this resource provider.
void	addDocumentResourceListener(TLcdKML22Link aLink, ILcdKML22ResourceListener aResourceListener) Adds a resource listener to the given link.
void	clearDocumentCache() Clears the document cache of this resource provider.
ELcdKML22ResourceStatus	getDocumentStatus(String aHref, String aKMLDocumentSource) Gets the status of a document based on a reference and a document of origin.
ELcdKML22ResourceStatus	getDocumentStatus(TLcdKML22Link aLink, TLcdKML22Parameters aParameters) Gets the status of a document based on a link and a parameter map of origin.
void	removeDocumentResourceListener(TLcdKML22Link aLink, ILcdKML22ResourceListener aResourceListener) Removes a resource listener from the given link.
TLcdKML22Kml	retrieveDocument(String aHref, String aKMLDocumentSource) Retrieves a document based on a given url.
void	retrieveDocument(String aHref, String aKMLDocumentSource, ILcdKML22ResourceListener aCallBackFunction) Asynchronous version of retrieve document for a given href and kml document source.
TLcdKML22Kml	retrieveDocument(TLcdKML22Link aLink, TLcdKML22Parameters aParameterProvider) Retrieves a document based on the given link.
void	retrieveDocument(TLcdKML22Link aLink, TLcdKML22Parameters aParameterMap, ILcdKML22ResourceListener aCallbackFunction) Asynchronous version of retrieve document for a given link and parameter map document source.
TLcdKML22Kml	updateDocument(TLcdKML22Link aLink, TLcdKML22Parameters aParameters) Updates the given link to a document.
void	updateDocument(TLcdKML22Link aLink, TLcdKML22Parameters aParameters, ILcdKML22ResourceListener aCallbackFunction) An asynchronous version of updateDocument(com.luciad.format.kml22.model.util.TLcdKML22Link, com.luciad.format.kml22.model.TLcdKML22Parameters, ILcdKML22ResourceListener)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

retrieveDocument

public TLcdKML22Kml retrieveDocument(TLcdKML22Link aLink,
                                     TLcdKML22Parameters aParameterProvider)

Retrieves a document based on the given link. If a KML parameter map is supplied, the resource provider will also take the parameters into consideration while caching the document. Otherwise it will retrieve the document regardless of any parameters.

Parameters:

aLink - A given link that refers to a kml document

aParameterProvider - An optional parameter map that contains parameters for this resource provider. To prevent concurrent modification exceptions, this object must not be modified while this method is running.

Returns:

A kml document, either from cache or loaded from the link. This method will return null if the document was not found or could not be parsed.

retrieveDocument

public TLcdKML22Kml retrieveDocument(String aHref,
                                     String aKMLDocumentSource)

Retrieves a document based on a given url.

Parameters:

aHref - A reference to the document, either absolute or relative.

aKMLDocumentSource - If the given href is relative, this must be set to the path of the requesting kml document. (Can be null)

Returns:

A KML document. This method will return null if the document was not found or could not be parsed.

retrieveDocument

public void retrieveDocument(String aHref,
                             String aKMLDocumentSource,
                             ILcdKML22ResourceListener aCallBackFunction)

Asynchronous version of retrieve document for a given href and kml document source. This method will load a document in a background thread and notify the callback function when it is done.

Note that this method should only be called once for a resource. The callback function will be notified when this method is done working. You can also poll the availability of the resource with the getDocumentStatus(String, String, com.luciad.format.kml22.model.util.TLcdKML22Link, com.luciad.format.kml22.model.TLcdKML22Parameters) method.

Parameters:

aHref - A reference to the document, either absolute or relative.

aKMLDocumentSource - If the given href is relative, this must be set to the path of the requesting kml document. (Can be null)

aCallBackFunction - A function to notify when the document has been loaded.

getDocumentStatus

public ELcdKML22ResourceStatus getDocumentStatus(String aHref,
                                                 String aKMLDocumentSource)

Gets the status of a document based on a reference and a document of origin.

Parameters:

aHref - An absolute or relative reference to the document

aKMLDocumentSource - an absolute reference to the document requesting the document status. This should not be null if the aHref parameter is given relatively.

Returns:

An ELcdKML22ResourceStatus

retrieveDocument

public void retrieveDocument(TLcdKML22Link aLink,
                             TLcdKML22Parameters aParameterMap,
                             ILcdKML22ResourceListener aCallbackFunction)

Asynchronous version of retrieve document for a given link and parameter map document source. This method will load a document in a background thread and notify the callback function when it is done.

Note that this method should only be called once for a resource. The callback function will be notified when this method is done working. You can also poll the availability of the resource with the getDocumentStatus(String, String, com.luciad.format.kml22.model.util.TLcdKML22Link, com.luciad.format.kml22.model.TLcdKML22Parameters) method.

Parameters:

aLink - A given link that refers to a kml document

aParameterMap - An optional parameter map that supplies parameters to this resource provider. To prevent concurrent modification exceptions, this object must not be modified while this method is running.

aCallbackFunction - A callback function to notify when the document has been retrieved.

getDocumentStatus

public ELcdKML22ResourceStatus getDocumentStatus(TLcdKML22Link aLink,
                                                 TLcdKML22Parameters aParameters)

Gets the status of a document based on a link and a parameter map of origin.

Parameters:

aLink - a link to the document

aParameters - A list of parameters that should be used to obtain the document. To prevent concurrent modification exceptions, this should not be modified while this method is running.

Returns:

An ELcdKML22ResourceStatus

addDocument

public void addDocument(TLcdKML22Kml aKmlDocument,
                        String aSourceName)

Adds a document to this resource provider. The document will be cached, and future retrieves will not fetch this document again, but instead return the version that was cached.

Parameters:

aKmlDocument - The kml document to add to this resource provider

aSourceName -

An absolute reference to the document in question. This source name will be used to cache the kml document, so that calling retrieveDocument(aSourceName ,null), will retrieve the aKmlDocument parameter.

For kmz files it is important to make sure that you have an absolute identifier to the kml document. This is done by adding an exclamation mark "!" right after the kmz file, and pointing to the internal kml document in a relative fashion

For instance: If you have a "/document.kmz" file that contains a "doc.kml" file, the full source name would become: "/document.kmz!doc.kml".

updateDocument

public TLcdKML22Kml updateDocument(TLcdKML22Link aLink,
                                   TLcdKML22Parameters aParameters)

Updates the given link to a document.

If the document wasn't previously added or retrieved by this resource provider, it will perform a synchronous retrieve.

Parameters:

aLink - The link to the document that needs to be updated

aParameters - The KML parameter map that contains all necessary parameters

Returns:

An updated version of the document; Null if something went wrong with the update.

updateDocument

public void updateDocument(TLcdKML22Link aLink,
                           TLcdKML22Parameters aParameters,
                           ILcdKML22ResourceListener aCallbackFunction)

An asynchronous version of updateDocument(com.luciad.format.kml22.model.util.TLcdKML22Link, com.luciad.format.kml22.model.TLcdKML22Parameters, ILcdKML22ResourceListener)

The given callback function will be notified when the update is complete.

Parameters:

aLink - The link to the document that needs to be updated

aParameters - The KML parameter map that contains all necessary parameters

aCallbackFunction - The callback function to notify when the update is complete

clearDocumentCache

public void clearDocumentCache()

Clears the document cache of this resource provider. This method can be used if files have been changed, and the cache of the resource provider is invalid.

Note that this method will not update documents that already exist in a layer.

addDocumentResourceListener

public void addDocumentResourceListener(TLcdKML22Link aLink,
                                        ILcdKML22ResourceListener aResourceListener)

Adds a resource listener to the given link.

Parameters:

aLink - A link to a document

aResourceListener - A resource listener which will be notified when the given link is changed.

Throws:

NullPointerException - If any of the parameters are null.

removeDocumentResourceListener

public void removeDocumentResourceListener(TLcdKML22Link aLink,
                                           ILcdKML22ResourceListener aResourceListener)

Removes a resource listener from the given link.

Parameters:

aLink - A link to a document

aResourceListener - A resource listener to be removed from the given link.

Throws:

NullPointerException - If any of the parameters are null.