Package com.luciad.format.kml22.util

Class TLcdKML22ImageProvider

java.lang.Object
com.luciad.format.kml22.util.TLcdKML22ImageProvider
public class TLcdKML22ImageProvider extends Object

Provider of images used in KML documents.

Images can be retrieved synchronously or asynchronously. The provider keeps a cache of images to optimize performance.

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

 
   //variables used in this template
    TLcdKML22ImageProvider imageProvider;
    TLcdKML22Link link;
    TLcdKML22Parameters parameters;
    ILcdKML22ResourceListener callbackFunction;

    //the template

    //obtain the status of the image to decide what to do
    ELcdKML22ResourceStatus imageStatus = imageProvider.getImageStatus( link,parameters );
    Image image = null;
    switch ( imageStatus ) {
      case CACHED:
        //the resource is cached, so you can retrieve it synchronously without blocking the calling
        //thread
        image = imageProvider.retrieveImage( link, parameters );
        break;
      case LOADING:
        //the resource is being loaded. Use a temporary value instead.
        image = getLoadingImage();
        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.
        image = getFaultyImage();
        break;
      case NOT_CACHED:
        //the resource is not cached. Start an asynchronous retrieve and used a temporary value instead.
        imageProvider.retrieveImage( link,parameters,callbackFunction );
        image = getLoadingImage();
        break;
    }
Since:
10.0

  • Method Details

    • retrieveImage

      public Image retrieveImage(String aImageHref, String aKMLSourceFile)

      Retrieves an image, given a kml source file and a an image href. The kml source file is used in case the image href is given relatively instead of absolutely, or if the image is contained within a zipped kmz file.

      This method caches its results.

      If the image is not available in the cache, this method will block the calling thread while it is retrieving the image

      To check the availability of an image, use the getImageStatus(String, String) method.

      Parameters:
      aImageHref - An absolute or relative reference to an image file.
      aKMLSourceFile - An absolute reference to the kml source file from which this request originates.
      Returns:
      A valid Image, or null if the image was not found.

    • retrieveImage

      public Image retrieveImage(TLcdKML22Link aLink, TLcdKML22Parameters aParameters)

      Retrieves an image given a link and a parameter map.

      This method caches its results.

      If the image is not available in the cache, this method will block the calling thread while it is retrieving the image.

      To check the availability of an image, use the getImageStatus(TLcdKML22Link, TLcdKML22Parameters) method.

      Parameters:
      aLink - The link which links to an image.
      aParameters - A KML parameter map that can provide all necessary (view based) parameters. To prevent concurrent modification exceptions, this object must not be modified while this method is running.
      Returns:
      An Image, either fetched from cache, or retrieved from the link and then cached. This method can return null if the image was not found.

    • retrieveImage

      public void retrieveImage(TLcdKML22Link aLink, TLcdKML22Parameters aParameterProvider, ILcdKML22ResourceListener aResourceListener)

      An asynchronous version of retrieveImage. The additional third parameter is a resource listener that should be notified when the requested image has been loaded.

      This method does not block the calling thread. The result will be cached in this image provider.

      Parameters:
      aLink - A link to an image file
      aParameterProvider - A valid KML parameter map for view based parameters. Must be cloned in advance to avoid concurrent modification exceptions.
      aResourceListener - A resource listener that should be notified after the image has been loaded.
      See Also:

    • getImageStatus

      public ELcdKML22ResourceStatus getImageStatus(TLcdKML22Link aLink, TLcdKML22Parameters aParameters)

      Gets the status of the image.

      Parameters:
      aLink - A link to the image
      aParameters - The parameters used to retrieve the image. To prevent concurrent modification exceptions, this object must not be modified while this method is running.
      Returns:
      An ELcdKML22ResourceStatus

    • retrieveImage

      public void retrieveImage(String aImageHref, String aKMLSourceFile, ILcdKML22ResourceListener aResourceListener)

      An asynchronous version of retrieveImage that loads an image in the background. The additional third parameter is a resource listener that should be notified when the requested image has been loaded.

      This method does not block the calling thread.

      Parameters:
      aImageHref - An absolute or relative reference to an image file.
      aKMLSourceFile - An absolute reference to the kml source file from which this request originates.
      aResourceListener - A resource listener that should be notified after the image has been loaded.
      See Also:

    • getImageStatus

      public ELcdKML22ResourceStatus getImageStatus(String aImageHref, String aKMLSource)

      Gets the status of the image.

      Parameters:
      aImageHref - A link to the image
      aKMLSource - An absolute reference of the document that contains this resource
      Returns:
      An ELcdKML22ResourceStatus

    • clearImageCache

      public void clearImageCache()

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

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

    • addImageResourceListener

      public void addImageResourceListener(TLcdKML22Link aLink, ILcdKML22ResourceListener aResourceListener)

      Adds a resource listener to the given link.

      The listener will be notified of updates to the image

      Parameters:
      aLink - A link to an image
      aResourceListener - A resource listener which will be notified when the given link is changed.
      Throws:
      NullPointerException - If any of the parameters are null.
      See Also:

    • removeImageResourceListener

      public void removeImageResourceListener(TLcdKML22Link aLink, ILcdKML22ResourceListener aResourceListener)
      Removes a resource listener from the given link.
      Parameters:
      aLink - A link to an image
      aResourceListener - A resource listener to be removed from the given link.
      Throws:
      NullPointerException - If any of the parameters are null.
      See Also:

    • updateImage

      public Image updateImage(TLcdKML22Link aLink, TLcdKML22Parameters aParameterMap)
      Updates the given image, if it was already in cache. If image was not yet in cache, it will perform a retrieve and put it into the cache.
      Parameters:
      aLink - A link to an image
      aParameterMap - A KML parameter map that provides all necessary (view based) parameters. To prevent concurrent modification exceptions, this object must not be modified while this method is running.
      Returns:
      the updated image; null if something went wrong with the update

    • updateImage

      public void updateImage(TLcdKML22Link aLink, TLcdKML22Parameters aParameterMap, ILcdKML22ResourceListener aCallBackFunction)
      The asynchronous version of updateImage(com.luciad.format.kml22.model.util.TLcdKML22Link, com.luciad.format.kml22.model.TLcdKML22Parameters). The given callback function will be notified when the update is complete.
      Parameters:
      aLink - A link to an image
      aParameterMap - A KML parameter map that provides all necessary (view based) parameters. To prevent concurrent modification exceptions, this object must not be modified while this method is running.
      aCallBackFunction - The callback function to notify when the resource is ready.