Package com.luciad.format.kml22.util

Class 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 Details

    • 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.