com.luciad.format.kml22.util

LuciadLightspeedClass 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 Summary

Modifier and Type	Method and Description
void	addImageResourceListener(TLcdKML22Link aLink, ILcdKML22ResourceListener aResourceListener) Adds a resource listener to the given link.
void	clearImageCache() Clears the image cache of this resource provider.
ELcdKML22ResourceStatus	getImageStatus(String aImageHref, String aKMLSource) Gets the status of the image.
ELcdKML22ResourceStatus	getImageStatus(TLcdKML22Link aLink, TLcdKML22Parameters aParameters) Gets the status of the image.
void	removeImageResourceListener(TLcdKML22Link aLink, ILcdKML22ResourceListener aResourceListener) Removes a resource listener from the given link.
Image	retrieveImage(String aImageHref, String aKMLSourceFile) Retrieves an image, given a kml source file and a an image href.
void	retrieveImage(String aImageHref, String aKMLSourceFile, ILcdKML22ResourceListener aResourceListener) An asynchronous version of retrieveImage that loads an image in the background.
Image	retrieveImage(TLcdKML22Link aLink, TLcdKML22Parameters aParameters) Retrieves an image given a link and a parameter map.
void	retrieveImage(TLcdKML22Link aLink, TLcdKML22Parameters aParameterProvider, ILcdKML22ResourceListener aResourceListener) An asynchronous version of retrieveImage.
Image	updateImage(TLcdKML22Link aLink, TLcdKML22Parameters aParameterMap) Updates the given image, if it was already in cache.
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).

Methods inherited from class java.lang.Object

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

Method Detail

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:

retrieveImage(com.luciad.format.kml22.model.util.TLcdKML22Link, com.luciad.format.kml22.model.TLcdKML22Parameters)

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:

retrieveImage(String, String )

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(com.luciad.format.kml22.model.util.TLcdKML22Link, ILcdKML22ResourceListener)

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:

addImageResourceListener(com.luciad.format.kml22.model.util.TLcdKML22Link, ILcdKML22ResourceListener)

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.