net.refractions.udig.ui
Class ImageCache

java.lang.Object
  net.refractions.udig.ui.ImageCache

public final class ImageCache
extends java.lang.Object

A weakly referenced cache of image descriptors to arrays of image instances (representing normal, gray and disabled images). This is used to hold images in memory while their descriptors are defined. When the image descriptors become weakly referred to, the corresponding images in the array of images will be disposed. Weak references of equivalent image descriptors are mapped to the same array of images (where equivalent descriptors are equals(Object)). It is recommended to use this class as a singleton, since it creates a thread for cleaning out images. It is the responsibility of the user to ensure that the image descriptors are kept around as long as the images are needed. The users of this cache should not explicitly dispose the images. Upon request of a disabled or gray image, the normal image will be created as well (if it was not already in the cache) in order to create the disabled or gray version of the image. This cache makes no guarantees on how long the cleaning process will take, or when exactly it will occur. This class may be instantiated; it is not intended to be subclassed.

Since:

3.1

Field Summary

static int	DISABLE Types of images supported by the image cache.
static int	GRAY
static int	REGULAR

Constructor Summary

ImageCache()
Constructs a new instance of ImageCache, and starts a thread to monitor the reference queue for image clean up.

ImageCache(int initialLoadCapacity)
Constructs a new instance of ImageCache, and starts a thread to monitor the reference queue for image clean up.

ImageCache(int initialLoadCapacity, float loadFactor)
Constructs a new instance of ImageCache, and starts a thread to monitor the reference queue for image clean up.

Method Summary

void	dispose() Cleans up all images in the cache.
Image	getImage(ImageDescriptor imageDescriptor) Returns the regular image for the given image descriptor.
Image	getImage(ImageDescriptor imageDescriptor, int typeOfImage) Returns the requested image for the given image descriptor and image type.
Image	getMissingImage() Returns the image to display when no image can be found, or none is specified.

Methods inherited from class java.lang.Object

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

Field Detail

DISABLE

public static final int DISABLE

Types of images supported by the image cache.

See Also:

Constant Field Values

GRAY

public static final int GRAY

See Also:

Constant Field Values

REGULAR

public static final int REGULAR

See Also:

Constant Field Values

Constructor Detail

ImageCache

public ImageCache()

Constructs a new instance of ImageCache, and starts a thread to monitor the reference queue for image clean up.

ImageCache

public ImageCache(int initialLoadCapacity)

Constructs a new instance of ImageCache, and starts a thread to monitor the reference queue for image clean up. If the passed initial load capacity is negative, the image map is created with the default HashMap constructor.

Parameters:

initialLoadCapacity - Initial load capacity for the image hash map.

ImageCache

public ImageCache(int initialLoadCapacity,
                  float loadFactor)

Constructs a new instance of ImageCache, and starts a thread to monitor the reference queue for image clean up. If the passed initial load capacity is negative or if the load factor is nonpositive, the image map is created with the default HashMap constructor.

Parameters:

initialLoadCapacity - Initial load capacity for the image hash map.

loadFactor - Load factor for the image hash map.

Method Detail

dispose

public final void dispose()

Cleans up all images in the cache. This disposes of all of the images, and drops references to them. This should only be called when the images and the image cache are no longer needed (i.e.: shutdown). Note that the image disposal is handled by the cleaner thread.

getImage

public final Image getImage(ImageDescriptor imageDescriptor)

Returns the regular image for the given image descriptor. This caches the result so that future attempts to get the image for an equivalent or identical image descriptor will only access the cache. When all references to equivalent image descriptors are dropped, the images (regular, gray and disabled) will be cleaned up if they have been created. This clean up makes no guarantees about how long or when it will take place.

Parameters:

descriptor - The image descriptor with which a regular image should be created; may be null.

Returns:

The regular image, either newly created or from the cache. This value is null if the image descriptor passed in is null. Note that a missing image will be returned if a problem occurs in the creation of the image.

getImage

public final Image getImage(ImageDescriptor imageDescriptor,
                            int typeOfImage)

Returns the requested image for the given image descriptor and image type. This caches the result so that future attempts to get the image for an equivalent or identical image descriptor will only access the cache. When all references to equivalent image descriptors are dropped, the images (regular, gray and disabled) will be cleaned up if they have been created. This clean up makes no guarantees about how long or when it will take place.

Parameters:

descriptor - The image descriptor with which the requested image should be created; may be null.

typeOfImage - The type of the desired image: ImageCache.DISABLED, ImageCache.GRAY or ImageCache.NORMAL.

Returns:

The image for the requested image type, either newly created or from the cache. This value is null if the image descriptor passed in is null, or if the image type is invalid. Note that a missing image will be returned if a problem occurs in the creation of the image.

getMissingImage

public final Image getMissingImage()

Returns the image to display when no image can be found, or none is specified. This image is only disposed when the cache is disposed.

Returns:

The image to display for missing images. This value will never be null.