com.tensegrity.graphics
Class ImagePool

java.lang.Object
  com.tensegrity.graphics.ImagePool

public class ImagePool

extends java.lang.Object

The ImagePool is the facility that takes over the work of pooling images. Pooling of images is necessary because they are most often frequently used objects and their memory consumption is very high.

NOTICE:When trying to store an image in the ImagePool with a key that is already in use the ImagePool throws an InvalidKeyException this is done because

• it is not much useful to restore the old image with the new one because this might have unwanted effect on all objects that makes use of the stored image.
• it might be possible that the old image isn't collectible by the garbage collector since some objects store the reference to the pooled image. Furthermore this would cancel the function of the ImagePool.

Therefore the object/application that makes use of the ImagePool is forced to handle this situation by itself. This handling can be something like the following:

• get the stored image from the ImagePool if it is sure that both images are the same.
• remove the old image explicitly from the ImagePool and reset all references to the removed image.
• store the image with another key.

Version:

$Id: ImagePool.java,v 1.21 2005/12/12 15:19:25 MichaelKegel Exp $

Author:

MichaelKegel

Field Summary

static java.lang.String

PATH_FILETIME_SEPARATOR Separator dividing the pathname of the file from the filetime

Method Summary

static void	clear() Removes all the pooled Rasters from the ImagePool.
static boolean	contains(Raster raster) Checks whether a raster is in the pool or not
static void	dump(java.io.PrintStream s) Dumps the ImagePool to the PrintStream given by s.
static Raster	get(java.lang.String key) Returns the Raster that is described through the String given by key if it is stored in the ImagePool.
static java.lang.Object	getKeyOf(Raster image) Searches for the Raster given by image in the pool and returns the key for that Raster.
static java.util.Iterator	iterator() Returns an iterator for all rasters in the image pool
static java.util.Iterator	keysIterator() Returns an iterator for all texture raster keys in the image pool
static Raster	loadAndPool(java.lang.Class referenceClass, java.lang.String key, java.lang.String resourceImagePath) Loads an image that is specified through the path given by resourceImagePath and adds the loaded image to the ImagePool.
static Raster	loadAndPool(java.lang.String resourceImagePath) Loads an image that is specified through the path given by resourceImagePath and adds the loaded image to the ImagePool.
static Raster	loadAndPool(java.lang.String resourceImagePath, java.lang.String key) Loads an image that is specified through the path given by resourceImagePath and adds the loaded image to the ImagePool.
static Raster	loadAndPool(java.lang.String key, java.net.URL imagepath)
static Raster	loadAndPool(java.net.URL imagepath) Loads an image that is specified through the path given by resourceImagePath and adds the loaded image to the ImagePool.
static void	pool(java.lang.String key, Raster image) Puts the Raster given by image into the ImagePool.
static int	size() Returns the number of the Rasters actually pooled in the .
static void	useThreadLocal() A call to this method configures the ImagePool to make use of the ThreadLocal class hence a pool is created for each Thread the ImagePool is used by.

Methods inherited from class java.lang.Object

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

Field Detail

PATH_FILETIME_SEPARATOR

public static final java.lang.String PATH_FILETIME_SEPARATOR

Separator dividing the pathname of the file from the filetime

See Also:

Constant Field Values

Method Detail

useThreadLocal

public static final void useThreadLocal()

A call to this method configures the ImagePool to make use of the ThreadLocal class hence a pool is created for each Thread the ImagePool is used by.
Notice: This configuration must be done before the ImagePool is in use by any Thread.

See Also:

ThreadLocal

pool

public static final void pool(java.lang.String key,
                              Raster image)
                       throws InvalidKeyException

Puts the Raster given by image into the ImagePool. Afterwards the Raster can be fetched from the ImagePool by using the description given by key. If there is already a Raster instance stored in the ImagePool that has the same description an InvalidArgumentException is thrown. This is done because it depends on the application how to handle this situation.

Parameters:

key - the description the Raster instance should stored into the ImagePool with

image - the Raster to put into the ImagePool

Throws:

InvalidArgumentException - if the given key or image is null

InvalidKeyException - is thrown when the given key is already in use

get

public static final Raster get(java.lang.String key)

Returns the Raster that is described through the String given by key if it is stored in the ImagePool. If the described Raster is not stored in the ImagePool null is returned.

Parameters:

key - the description of the Raster

Returns:

Raster an instance of the requested Raster or null

loadAndPool

public static final Raster loadAndPool(java.lang.String resourceImagePath)
                                throws ImagePoolingException

Loads an image that is specified through the path given by resourceImagePath and adds the loaded image to the ImagePool.

An ImagePoolingException is thrown whenever something went wrong while the process of loading and pooling the image.

Parameters:

resourceImagePath - the path for the image to load.

Returns:

the raster

Throws:

ImagePoolingException - is thrown when something went wrong while the image is loaded and pooled

loadAndPool

public static final Raster loadAndPool(java.lang.String resourceImagePath,
                                       java.lang.String key)
                                throws ImagePoolingException

Loads an image that is specified through the path given by resourceImagePath and adds the loaded image to the ImagePool.

An ImagePoolingException is thrown whenever something went wrong while the process of loading and pooling the image.

Parameters:

resourceImagePath - the path for the image to load.

key - the key under which the raster will be stored

Returns:

the raster

Throws:

ImagePoolingException - is thrown when something went wrong while the image is loaded and pooled

loadAndPool

public static final Raster loadAndPool(java.lang.Class referenceClass,
                                       java.lang.String key,
                                       java.lang.String resourceImagePath)
                                throws ImagePoolingException

Loads an image that is specified through the path given by resourceImagePath and adds the loaded image to the ImagePool.

An ImagePoolingException is thrown whenever something went wrong while the process of loading and pooling the image.

Parameters:

referenceClass - The reference class for laoding resources

resourceImagePath - the path for the image to load.

key - the key under which the raster will be stored

Returns:

the raster

Throws:

ImagePoolingException - is thrown when something went wrong while the image is loaded and pooled

loadAndPool

public static final Raster loadAndPool(java.net.URL imagepath)
                                throws ImagePoolingException

Loads an image that is specified through the path given by resourceImagePath and adds the loaded image to the ImagePool.

An ImagePoolingException is thrown whenever something went wrong while the process of loading and pooling the image.

Parameters:

imagepath - the path for the image to load.

Throws:

ImagePoolingException - is thrown when something went wrong while the image is loaded and pooled

loadAndPool

public static final Raster loadAndPool(java.lang.String key,
                                       java.net.URL imagepath)
                                throws ImagePoolingException

Throws:

ImagePoolingException

getKeyOf

public static final java.lang.Object getKeyOf(Raster image)

Searches for the Raster given by image in the pool and returns the key for that Raster. If the Raster is not part of the pool null is returned.

Parameters:

image - the Raster instance to search the key for

Returns:

Object the key for the given Raster or null

size

public static final int size()

Returns the number of the Rasters actually pooled in the .

Returns:

int the number of pooled Rasters

clear

public static final void clear()

Removes all the pooled Rasters from the ImagePool. Notice that this only can be done when it is sure that the pooled Rasters are no longer referenced by any object. Otherwise these objects have a weak reference.

iterator

public static java.util.Iterator iterator()

Returns an iterator for all rasters in the image pool

Returns:

an iterator for all rasters in the image pool

keysIterator

public static java.util.Iterator keysIterator()

Returns an iterator for all texture raster keys in the image pool

Returns:

an iterator for all keys in the image pool

contains

public static boolean contains(Raster raster)

Checks whether a raster is in the pool or not

Parameters:

raster - The raster to check

Returns:

true, if the raster is in the pool

dump

public static final void dump(java.io.PrintStream s)

Dumps the ImagePool to the PrintStream given by s.

Parameters:

s - the PrintStream to dump the ImagePool to