MediaTracker Methods

The MediaTracker class defines four constants that are used as return values from the class's methods. These values serve as status indicators.

public static final int LOADING

The LOADING variable indicates that the particular image being checked is still loading.

public static final int ABORTED

The ABORTED variable indicates that the loading process for the image being checked aborted. For example, a timeout could have happened during the download. If something ABORTED during loading, it is possible to flush() the image to force a retry.

public static final int ERRORED

The ERRORED variable indicates that an error occurred during the loading process for the image being checked. For instance, the image file might not be available from the server (invalid URL) or the file format could be invalid. If an image has ERRORED, retrying it will fail.

public static final int COMPLETE

The COMPLETE flag means that the image being checked successfully loaded.

If COMPLETE, ABORTED, or ERRORED is set, the image has stopped loading. If you are checking multiple images, you can OR several of these values together to form a composite. For example, if you are loading several images and want to find out about any malfunctions, call statusAll() and check for a return value of ABORTED | ERRORED. Constructors

public MediaTracker (Component component)

The MediaTracker constructor creates a new MediaTracker object to track images to be rendered onto component.

The addImage() methods add objects for the MediaTracker to track. When placing an object under a MediaTracker's control, you must provide an identifier for grouping purposes. When multiple images are grouped together, you can perform operations on the entire group with a single request. For example, you might want to wait until all the images in an animation sequence are loaded before starting the animation; in this case, assigning the same ID to all the images makes good sense. However, when multiple images are grouped together, you cannot check on the status of a single image. The moral is: if you care about the status of individual images, put each into a group by itself.

Folklore has it that the identifier also serves as a loading priority, with a lower ID meaning a higher priority. This is not completely true. Current implementations start loading lower IDs first, but at most, this is implementation-specific functionality for the JDK. Furthermore, although an object with a lower identifier might be told to start loading first, the MediaTracker does nothing to ensure that it finishes first.

public synchronized void addImage (Image image, int id, int width, int height)

The addImage() method tells the MediaTracker instance that it needs to track the loading of image. The id is used as a grouping. Someone will eventually render the image at a scaled size of width x height. If width and height are both -1, the image will be rendered unscaled. If you forget to notify the MediaTracker that the image will be scaled and ask the MediaTracker to waitForID (id), it is possible that the image may not be fully ready when you try to draw it.

public void addImage (Image image, int id)

The addImage() method tells the MediaTracker instance that it needs to track the loading of image. The id is used as a grouping. The image will be rendered at its actual size, without scaling.

Images that have finished loading are still watched by the MediaTracker. The removeImage() methods, added in Java 1.1, allow you to remove objects from the MediaTracker. Once you no longer care about an image (usually after waiting for it to load), you can remove it from the tracker. Getting rid of loaded images results in better performance because the tracker has fewer objects to check. In Java 1.0, you can't remove an image from MediaTracker.

public void removeImage (Image image)

The removeImage() method tells the MediaTracker to remove all instances of image from its tracking list.

public void removeImage (Image image, int id)

The removeImage() method tells the MediaTracker to remove all instances of image from group id of its tracking list.

public void removeImage (Image image, int id, int width, int height)

This removeImage() method tells the MediaTracker to remove all instances of image from group id and scale width x height of its tracking list.

A handful of methods let you wait for a particular image, image group, all images, or a particular time period. They enable you to be sure that an image has finished trying to load prior to continuing. The fact that an image has finished loading does not imply it has successfully loaded. It is possible that an error condition arose, which caused loading to stop. You should check the status of the image (or group) for actual success.

public void waitForID (int id) throws InterruptedException

The waitForID() method blocks the current thread from running until the images added with id finish loading. If the wait is interrupted, waitForID() throws an InterruptedException.

public synchronized boolean waitForID (int id, long ms) throws InterruptedException

The waitForID() method blocks the current thread from running until the images added with id finish loading or until ms milliseconds have passed. If all the images have loaded, waitForID() returns true; if the timer has expired, it returns false, and one or more images in the id set have not finished loading. If ms is 0, it waits until all images added with id have loaded, with no timeout. If the wait is interrupted, waitForID() throws an InterruptedException.

public void waitForAll () throws InterruptedException

The waitForAll() method blocks the current thread from running until all images controlled by this MediaTracker finish loading. If the wait is interrupted, waitForAll() throws an InterruptedException.

public synchronized boolean waitForAll (long ms) throws InterruptedException

The waitForAll() method blocks the current thread from running until all images controlled by this MediaTracker finish loading or until ms milliseconds have passed. If all the images have loaded, waitForAll() returns true; if the timer has expired, it returns false, and one or more images have not finished loading. If ms is 0, it waits until all images have loaded, with no timeout. When you interrupt the waiting, waitForAll() throws an InterruptedException.

Several methods are available to check on the status of images loading. None of these methods block, so you can continue working while images are loading.

public boolean checkID (int id)

The checkID() method determines if all the images added with the id tag have finished loading. The method returns true if all images have completed loading (successfully or unsuccessfully). Since this can return true on error, you should also use isErrorID() to check for errors. If loading has not completed, checkID() returns false. This method does not force images to start loading.

public synchronized boolean checkID (int id, boolean load)

The checkID() method determines if all the images added with the id tag have finished loading. If the load flag is true, any images in the id group that have not started loading yet will start. The method returns true if all images have completed loading (successfully or unsuccessfully). Since this can return true on error, you should also use isErrorID() to check for errors. If loading has not completed, checkID() returns false.

public boolean checkAll ()

The checkAll() method determines if all images associated with the MediaTracker have finished loading. The method returns true if all images have completed loading (successfully or unsuccessfully). Since this can return true on error, you should also use isErrorAny() to check for errors. If loading has not completed, checkAll() returns false. This method does not force images to start loading.

public synchronized boolean checkAll (boolean load)

The checkAll() method determines if all images associated with the MediaTracker have finished loading. If the load flag is true, any image that has not started loading yet will start. The method returns true if all images have completed loading (successfully or unsuccessfully). Since this can return true on error, you should also use isErrorAny() to check for errors. If loading has not completed, checkAll() returns false.

public int statusID (int id, boolean load)

The statusID() method checks on the load status of the images in the id group. If there are multiple images in the group, the results are ORed together. If the load flag is true, any image in the id group that has not started loading yet will start. The return value is some combination of the class constants LOADING, ABORTED, ERRORED, and COMPLETE.

public int statusAll (boolean load)

The statusAll() method determines the load status of all the images associated with the MediaTracker. If this MediaTracker is watching multiple images, the results are ORed together. If the load flag is true, any image that has not started loading yet will start. The return value is some combination of the class constants LOADING, ABORTED, ERRORED, and COMPLETE.

public synchronized boolean isErrorID (int id)

The isErrorId() method checks whether any media in the id group encountered an error while loading. If any image resulted in an error, isErrorId() returns true; if there were no errors, it returns false.

public synchronized boolean isErrorAny ()

The isErrorAny() method checks to see if any image associated with the MediaTracker encountered an error. If there was an error, the method returns true; if none, false.

public synchronized Object[] getErrorsID (int id)

The getErrorsID() method returns an array of the objects that encountered errors in the group ID during loading. If loading caused no errors, the method returns null. The return type is an Object array instead of an Image array because MediaTracker will eventually support additional media types.

public synchronized Object[] getErrorsAny ()

The getErrorsAny() method returns an array of all the objects that encountered an error during loading. If there were no errors, the method returns null. The return type is an Object array instead of an Image array because MediaTracker will eventually support additional media types.

Using a MediaTracker

The init() method improves the AnimateApplet from Example 2.2 to ensure that images load before the animation sequence starts. Waiting for images to load is particularly important if there is a slow link between the computer on which the applet is running and the server for the image files. Note that in a few cases, like interlaced GIF files, you might be willing to display an image before it has completely loaded. However, judicious use of MediaTracker will give you much more control over your program's behavior.

The new init() method creates a MediaTracker, puts all the images in the animation sequence under the tracker's control, and then calls waitForAll() to wait until the images are loaded. Once the images are loaded, it calls isErrorsAny() to make sure that the images loaded successfully.

public void init () {
    MediaTracker mt = new MediaTracker (this);
    im = new Image[numImages];
    for (int i=0;i<numImages;i++) {
        im[i] = getImage (getDocumentBase(), "clock"+i+".jpg");
        mt.addImage (im[i], i);
    }
    try {
        mt.waitForAll();
        if (mt.isErrorAny())
            System.out.println ("Error loading images");
    } catch (Exception e) {
        e.printStackTrace ();
    }
}