com.ccg.awt
Class ImageHolder

java.lang.Object
  com.ccg.awt.ImageHolder

public class ImageHolder
extends Object

A generic method to cache Image objects in. Unfortunately, it is difficult to work with (at least load) bitmaps in a generic fashion under Java. This is especially frustrating when one is creating generic components that one wants to allow to be used in either a stand alone application or Applet.

This class was designed to provide a lookup table of Image objects based on name values. It is designed such that both Java applications and applets should be able to populate (fill) it with bitmaps. This cache can then be used in turn by the generic components to fetch their necessary Image objects from without worrying about where they came from.

Typically Image objects are only put into the cache once they are fully available (loaded).

Since:

1.0

Version:

$Revision: 1.3 $

Author:

$Author: pkb $

See Also:

ImageButton.set(com.ccg.util.TagLookup, com.ccg.awt.ImageHolder)

Constructor Summary

ImageHolder()
Initializes the cache with zero images available.

Method Summary

Image	getImage(String name) Retrieve a image from the cache.
Image	getImage(String name, Component ac) Get/load/add a image from/to the cache.
Enumeration	getKeys() Get a Enumeration of all the keys added to the table.
boolean	putImage(String key, Image im) Add a image to the cache.
Image	removeImage(String name) Remove a image from the cache.
Object[]	waitForImages(Applet from, URL base, String tag) Load a set of images from the parameters associated with an applet.
Object[]	waitForImages(Applet from, URL base, String[] tags, String[] imNames) Load a set of images for a applet.
Object[]	waitForImages(String[] names, Image[] images, Component c) Load a set of images (if not present) and add them to the cache.
Object[]	waitForPropertyFileImages(Applet from, URL base, String pfile) Load a set of images for a applet via property file.

Methods inherited from class java.lang.Object

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

Constructor Detail

ImageHolder

public ImageHolder()

Initializes the cache with zero images available.

Since:

1.0

See Also:

putImage(java.lang.String, java.awt.Image), getImage(java.lang.String), waitForImages(String[], Image[], Component)

Method Detail

putImage

public boolean putImage(String key,
                        Image im)

Add a image to the cache.

Parameters:

key - The key name to file the image under. Use this value to retrieve the image from the cache when you need it. You can pass null, but nothing will be added.

im - The image to add to the cache (null is OK - but it won't be added).

Returns:

true if your image was added to the cache. false if either parameter was null.

Since:

1.0

See Also:

getImage(java.lang.String)

getImage

public Image getImage(String name)

Retrieve a image from the cache.

Parameters:

key - The key name to the image had been filed under. You can pass null, but you'll get null back.

Returns:

The image which had be previously put into the cache with the associated key name, or null if no such entry exists.

Since:

1.0

See Also:

putImage(java.lang.String, java.awt.Image)

getKeys

public Enumeration getKeys()

Get a Enumeration of all the keys added to the table.

Returns:

A Enumeration of all of the keys in the table.

Since:

1.0

See Also:

getImage(java.lang.String)

removeImage

public Image removeImage(String name)

Remove a image from the cache. This method permanently removes a image (if it exists) from the cache. After invoking this method, subsequent calls to getImage(java.lang.String) with the same key value will return null.

Parameters:

key - The key name of the image that it was filed under. You can pass null, but you'll get null back.

Returns:

The image which is now removed from the cache, or null if no such entry exists.

Since:

1.0

See Also:

getImage(java.lang.String)

getImage

public Image getImage(String name,
                      Component ac)

Get/load/add a image from/to the cache. This method is a convienent way for stand alone Java applications to retrieve images. It works in the following fashion:

• If a image is already available in the cache with the specified "name", it will be immediately returned.
• Otherwise an attempt will be made to load the image.
• If the image is successfully loaded, it will be added to the cache and returned.
• Otherwise, null will be returned.

Parameters:

name - Name of the image to load. Any form recognized by ImageUtility.loadImage(java.awt.Image, java.awt.Component) may be used. This will also be the "key" associated with the image for later retrieval.

c - The Component to use if we need to load the image (must not be null).

Returns:

ret-description

Since:

1.0

See Also:

waitForImages(java.lang.String[], java.awt.Image[], java.awt.Component), ImageUtility.loadImage(java.awt.Image, java.awt.Component), ImageDemo.html

waitForImages

public Object[] waitForImages(String[] names,
                              Image[] images,
                              Component c)
                       throws InterruptedException

Load a set of images (if not present) and add them to the cache. This method will check to see if images for the set of keys specified are already in the cache. For any image that is not present, it will be loaded (using a MediaTracker) and added to the cache.

This means that if this method needs to load images, it will block the current thread of execution until the images are loaded (so you may want to do this in a separate thread if using it from a applet).

Parameters:

names - The key names to store the images under in the cache (you can pass null - but you get null back, or have null entries - resulting in null entries returned).

images - The images to load if not already in the cache (you can pass null - but you get null back, or have null entries - resulting in null entries returned).

Returns:

null if either the "names" or "images" were null or not the same length, otherwise an array where each entry is one of the following types of objects: a Image - if succesully loaded and added to the cache, a Integer - with the MediaTracker's return code for an unsuccessful load, or null if either the name or image entry was null.

Throws:

InterruptedException - If we needed to load the images and our thread of execution was interrupted.

Since:

1.0

See Also:

getImage(String,Component)

waitForImages

public Object[] waitForImages(Applet from,
                              URL base,
                              String tag)
                       throws InterruptedException,
                              MalformedURLException

Load a set of images from the parameters associated with an applet. This method allows a Applet to load a set of image files which are defined by the applet's parameters (at run time). For example, suppose the HTML file which started up your applet has the following parameters defined:

 <param name=image.0 value=up>
 <param name=image.1 value=dn>
 
 <param name=up value=buttonUp.jpg>
 <param name=dn value=buttonDn.jpg>
 

You could use the following code fragment to initialize a ImageHolder such that a get("up") would return the "buttonUp.jpg" image and a get("dn") would return the "buttonDn.jpg" image:

 ImageHolder _images;
 
 public void init() {
   _images = new ImageHolder();
   _images.waitForImages(this,getDocumentBase(),"image");
 }
 

A word of caution, this method blocks until ALL the images are retrieved - so you may want to move to a separate thread (especially if the images are not imbedded in the same JAR file as the applet code).

Parameters:

from - Applet we will use to lookup parameter definitions from.

URL - This is typically the Applet.getDocumentBase() document base} or @link Applet#getCodeBase code base} URL or null. If you pass null, then images will be searched for in the applets "CLASSPATH" (allowing you to bundle them in JAR files).

tag - The "tag" to use to iterate through (like "image"). Should not be null, but null is handled and returns you a zero length result array.

Returns:

An array of objects (never null but may be zero length) with the resulting images loaded (or error codes) in the form described by the waitForImages method.

Throws:

InterruptedException - If we needed to load the images and our thread of execution was interrupted.

MalformedURLException - If any of the image's specified to be loaded were URL based and not in a proper form.

Since:

1.0

See Also:

waitForImages(Applet,URL,String[],String[])

waitForImages

public Object[] waitForImages(Applet from,
                              URL base,
                              String[] tags,
                              String[] imNames)
                       throws InterruptedException,
                              MalformedURLException

Load a set of images for a applet. This method allows a Applet to load a specific set of image files for a specific set of "key" names. The names of the images to load can either be specified explicitly (by passing a non-null array array of image names to load), or defined by parameter values for the key names in the HTML code which starts up your applet (allowing simple run time configuration). For example, suppose the HTML file which started up your applet has the following parameters defined:

 <param name=up value=buttonUp.jpg>
 <param name=dn value=buttonDn.jpg>
 

You could use the following code fragment to initialize a ImageHolder such that a get("up") would return the "buttonUp.jpg" image and a get("dn") would return the "buttonDn.jpg" image:

 ImageHolder _images;
 
 public void init() {
   _images = new ImageHolder();
   String[] tags = { "up", "dn" };
   _images.waitForImages(this,getDocumentBase(),tags,null);
 }
 

A word of caution, this method blocks until ALL the images are retrieved - so you may want to move to a separate thread (especially if the images are not imbedded in the same JAR file as the applet code).

Parameters:

from - Applet we will use to lookup parameter definitions from.

URL - This is typically the Applet.getDocumentBase() document base} or @link Applet#getCodeBase code base} URL or null. If you pass null, then images will be searched for in the applets "CLASSPATH" (allowing you to bundle them in JAR files).

tags - The "tags" to use to associate with each image file loaded (and to optionally use if we need to fetch the image names from the applet's parameters). Should not be null, but null is handled and returns you a zero length result array.

images - The "images" to load and associate with each of the "tags". If you pass null, we will create this array for you by looking up each image name from the applet's parameter value for each of the tags specified. If you pass a non-null array that is different in length than the array of tags specified, nothing is done and a zero length array is returned.

Returns:

An array of objects (never null but may be zero length) with the resulting images loaded (or error codes) in the form described by the waitForImages method.

Throws:

InterruptedException - If we needed to load the images and our thread of execution was interrupted.

MalformedURLException - If any of the image's specified to be loaded were URL based and not in a proper form.

Since:

1.0

See Also:

waitForImages(Applet,URL,String), TagLookup.getStrings(com.ccg.util.Lookup, java.lang.String[])

waitForPropertyFileImages

public Object[] waitForPropertyFileImages(Applet from,
                                          URL base,
                                          String pfile)
                                   throws InterruptedException,
                                          MalformedURLException

Load a set of images for a applet via property file. This method allows a Applet to load a specific set of image files based on the contents of a named property file. The key names of the images must appear first followed by the resource corresponding to the actual image. That is the property file should look something like:

 jump=image/human_jump.jpg
 run=image/human_run.gif
 

If the above property file was stored in "images/human.properties" (relative to the applet's document base), you could use the following code fragment to initialize a ImageHolder such that a get("jump") would return the "image/human_jump.jpg" image and a get("run") would return the "image/human_run.gif" image:

 ImageHolder _images;
 
 public void init() {
   _images = new ImageHolder();
   _images.waitForImages(this,getDocumentBase(),"images/human.properties");
 }
 

A word of caution, this method blocks until ALL the images are retrieved - so you may want to move to a separate thread (especially if the images are not imbedded in the same JAR file as the applet code).

Parameters:

from - Applet we will use to lookup parameter definitions from.

URL - This is typically the Applet.getDocumentBase() document base} or @link Applet#getCodeBase code base} URL or null. If you pass null, then images will be searched for in the applets "CLASSPATH" (allowing you to bundle them in JAR files).

pfile - The property file to load relative to the URL passed. Should not be null, but null is handled and returns you a zero length result array.

images - The "images" to load and associate with each of the "tags". If you pass null, we will create this array for you by looking up each image name from the applet's parameter value for each of the tags specified. If you pass a non-null array that is different in length than the array of tags specified, nothing is done and a zero length array is returned.

Returns:

An array of objects (never null but may be zero length) with the resulting images loaded (or error codes) in the form described by the waitForImages method.

Throws:

InterruptedException - If we needed to load the images and our thread of execution was interrupted.

MalformedURLException - If any of the image's specified to be loaded were URL based and not in a proper form.

Since:

1.0

See Also:

waitForImages(Applet,URL,String), TagLookup.getStrings(com.ccg.util.Lookup, java.lang.String[])