MediaTracker.java: Reindented tabs to spaces.

2005-04-19  Roman Kennke  <roman@kennke.org>

	* java/awt/MediaTracker.java:
	Reindented tabs to spaces.

2005-04-19  Roman Kennke  <roman@kennke.org>

	* java/awt/MediaTracker.java
	(MediaEntry.imageUpdate): Removed check for SOMEBITS, this
	confused the media tracker and lead to lockups. The LOADING
	bit is handled on other places.
	(addImage): Removed the 'start image tracking' stuff. This
	is not necessary and could confuse the media tracker.
	(checkAll): Improved the check for image status so that
	images that already complete images are detected. Also now
	are really all images checked and if necessary loaded. Before
	the method bailed out after the first incomplete image.
	(statusAll): Detect images that are complete after the
	call to Component.prepareImage(..).
	(checkID): The same as in checkAll.
	(statusID): The same as in statusAll.

2005-04-19  Roman Kennke  <roman@kennke.org>

	* java/awt/MediaTracker.java
	(addImage): Synchronized list access.
	(waitForAll): Fixed comparison of time (changed < to >).
	(waitForID): Fixed comparison of time (changed < to >).
	(removeImage): Synchronized list access.

2005-04-19  Roman Kennke  <roman@kennke.org>

	* java/awt/MediaTracker.java
	Added API documentation.

2005-04-19  Roman Kennke  <roman@kennke.org>

	* java/awt/MediaTracker.java
	(MediaEntry.imageUpdate): Fixed flags. The different flags
	must not be ORed together.
	(checkAll): Modified to handle different meaning of the flags.
	(waitForAll): Fixed so that it waits maximum the
	specified amount of milliseconds.
	(statusAll): Modified to handle different meaning of the flags.
	(waitForID): Fixed so that it waits maximum the
	specified amount of milliseconds.

From-SVN: r98374

2 files changed, 439 insertions, 128 deletions

diff --git a/libjava/ChangeLog b/libjava/ChangeLog
index 378723b..6360762 100644
--- a/libjava/ChangeLog
+++ b/libjava/ChangeLog
@@ -1,3 +1,50 @@
+2005-04-19  Roman Kennke  <roman@kennke.org>
+
+	* java/awt/MediaTracker.java:
+	Reindented tabs to spaces.
+
+2005-04-19  Roman Kennke  <roman@kennke.org>
+
+	* java/awt/MediaTracker.java
+	(MediaEntry.imageUpdate): Removed check for SOMEBITS, this
+	confused the media tracker and lead to lockups. The LOADING
+	bit is handled on other places.
+	(addImage): Removed the 'start image tracking' stuff. This
+	is not necessary and could confuse the media tracker.
+	(checkAll): Improved the check for image status so that
+	images that already complete images are detected. Also now
+	are really all images checked and if necessary loaded. Before
+	the method bailed out after the first incomplete image.
+	(statusAll): Detect images that are complete after the
+	call to Component.prepareImage(..).
+	(checkID): The same as in checkAll.
+	(statusID): The same as in statusAll.
+
+2005-04-19  Roman Kennke  <roman@kennke.org>
+
+	* java/awt/MediaTracker.java
+	(addImage): Synchronized list access.
+	(waitForAll): Fixed comparison of time (changed < to >).
+	(waitForID): Fixed comparison of time (changed < to >).
+	(removeImage): Synchronized list access.
+
+2005-04-19  Roman Kennke  <roman@kennke.org>
+
+	* java/awt/MediaTracker.java
+	Added API documentation.
+
+2005-04-19  Roman Kennke  <roman@kennke.org>
+
+	* java/awt/MediaTracker.java
+	(MediaEntry.imageUpdate): Fixed flags. The different flags
+	must not be ORed together.
+	(checkAll): Modified to handle different meaning of the flags.
+	(waitForAll): Fixed so that it waits maximum the
+	specified amount of milliseconds.
+	(statusAll): Modified to handle different meaning of the flags.
+	(waitForID): Fixed so that it waits maximum the
+	specified amount of milliseconds.
+
 2005-04-19  vid Gilbert <david.gilbert@object-refinery.com>
 
 	* java/awt/Font.java (decode): Handle null argument and allow
diff --git a/libjava/java/awt/MediaTracker.java b/libjava/java/awt/MediaTracker.java
index e69832d..2c51fbd 100644
--- a/libjava/java/awt/MediaTracker.java
+++ b/libjava/java/awt/MediaTracker.java
@@ -45,95 +45,191 @@ import java.util.ArrayList;
   * This class is used for keeping track of the status of various media
   * objects.
   *
+  * Media objects are tracked by assigning them an ID. It is possible
+  * to assign the same ID to mutliple objects, effectivly grouping them
+  * together. In this case the status flags ({@link #statusID}) and error flag
+  * (@link #isErrorID} and {@link #getErrorId}) are ORed together. This
+  * means that you cannot say exactly which media object has which status,
+  * at most you can say that there <em>are</em> certain media objects with
+  * some certain status.
+  * 
+  * At the moment only images are supported by this class.
+  *
   * @author Aaron M. Renn (arenn@urbanophile.com)
   * @author Bryce McKinlay
   */
 public class MediaTracker implements java.io.Serializable
 {
+  /** Indicates that the media is still loading. */
   public static final int LOADING = 1 << 0;
+
+  /** Indicates that the loading operation has been aborted. */
   public static final int ABORTED = 1 << 1;
+
+  /** Indicates that an error has occured during loading of the media. */
   public static final int ERRORED = 1 << 2;
+
+  /** Indicates that the media has been successfully and completely loaded. */
   public static final int COMPLETE = 1 << 3;
-  
+
+  /** The component on which the media is eventually been drawn. */
   Component target;
+
+  /** The head of the linked list of tracked media objects. */
   MediaEntry head;
 
+  /** Our serialVersionUID for serialization. */
   static final long serialVersionUID = -483174189758638095L;
 
+  /**
+   * This represents a media object that is tracked by a MediaTracker.
+   * It also implements a simple linked list.
+   */
   // FIXME: The serialized form documentation says MediaEntry is a 
   // serializable field, but the serialized form of MediaEntry itself
   // doesn't appear to be documented.
   class MediaEntry implements ImageObserver
   {
+    /** The ID of the media object. */
     int id;
+
+    /** The media object. (only images are supported ATM). */
     Image image;
+
+    /** The link to the next entry in the list. */
     MediaEntry next;
+
+    /** The tracking status. */
     int status;
+
+    /** The width of the image. */
     int width;
+
+    /** The height of the image. */
     int height;
     
+    /**
+     * Receives notification from an {@link java.awt.image.ImageProducer}
+     * that more data of the image is available.
+     *
+     * @param img the image that is updated
+     * @param flags flags from the ImageProducer that indicate the status
+     *        of the loading process
+     * @param x the X coordinate of the upper left corner of the image
+     * @param y the Y coordinate of the upper left corner of the image
+     * @param width the width of the image
+     * @param height the height of the image
+     *
+     * @return <code>true</code> if more data is needed, <code>false</code>
+     *         otherwise
+     *
+     * @see {@link java.awt.image.ImageObserver}
+     */
     public boolean imageUpdate(Image img, int flags, int x, int y, 
-			       int width, int height)
+                               int width, int height)
     {
       if ((flags & ABORT) != 0)
-        status = ABORTED | COMPLETE;
+        status = ABORTED;
       else if ((flags & ERROR) != 0)
-        status = ERRORED | COMPLETE;
+        status = ERRORED;
       else if ((flags & ALLBITS) != 0)
         status = COMPLETE;
-      else if ((flags & SOMEBITS) != 0)
-        status = LOADING;
       else
         status = 0;
 
-      if ((status & COMPLETE) == COMPLETE)
-      {
-        synchronized (MediaTracker.this)
+      synchronized (MediaTracker.this)
         {
           MediaTracker.this.notifyAll();
         }
-      }
+
       // If status is not COMPLETE then we need more updates.
-      return (status & COMPLETE) == 0;
+      return ((status & (COMPLETE | ERRORED | ABORTED)) == 0);
     }
   }
 
+  /**
+   * Constructs a new MediaTracker for the component <code>c</code>. The
+   * component should be the component that uses the media (i.e. draws it).
+   *
+   * @param c the Component that wants to use the media
+   */
   public MediaTracker(Component c)
   {
     target = c;
   }
 
+  /**
+   * Adds an image to the tracker with the specified <code>ID</code>.
+   *
+   * @param image the image to be added
+   * @param id the ID of the tracker list to which the image is added
+   */
   public void addImage(Image image, int id)
   {
     MediaEntry e = new MediaEntry();
     e.id = id;
     e.image = image;
-    e.next = head;
-    head = e;
-    // Start tracking image status.
-    int flags = target.checkImage(image, e);
-    e.imageUpdate(image, flags, -1, -1, -1, -1);
+    synchronized(this)
+      {
+        e.next = head;
+        head = e;
+      }
   }
 
+  /**
+   * Adds an image to the tracker with the specified <code>ID</code>.
+   * The image is expected to be rendered with the specified width and
+   * height.
+   *
+   * @param image the image to be added
+   * @param id the ID of the tracker list to which the image is added
+   * @param width the width of the image
+   * @param height the height of the image
+   */
   public void addImage(Image image, int id, int width, int height)
   {
     MediaEntry e = new MediaEntry();
     e.id = id;
     e.image = image;
-    e.next = head;
     e.width = width;
     e.height = height;
-    head = e;
-    // Start tracking image status.
-    int flags = target.checkImage(image, width, height, e);
-    e.imageUpdate(image, flags, -1, -1, width, height);
+    synchronized(this)
+      {
+        e.next = head;
+        head = e;
+      }
   }
 
+  /**
+   * Checks if all media objects have finished loading, i.e. are
+   * {@link #COMPLETE}, {@link #ABORTED} or {@link #ERRORED}.
+   *
+   * If the media objects are not already loading, a call to this
+   * method does <em>not</em> start loading. This is equivalent to
+   * a call to <code>checkAll(false)</code>.
+   *
+   * @return if all media objects have finished loading either by beeing
+   *         complete, have been aborted or errored.
+   */
   public boolean checkAll()
   {
     return checkAll(false);
   }
 
+  /**
+   * Checks if all media objects have finished loading, i.e. are
+   * {@link #COMPLETE}, {@link #ABORTED} or {@link #ERRORED}.
+   *
+   * If the media objects are not already loading, and <code>load</code>
+   * is <code>true</code> then a call to this
+   * method starts loading the media objects.
+   *
+   * @param load if <code>true</code> this method starts loading objects
+   *        that are not already loading
+   *
+   * @return if all media objects have finished loading either by beeing
+   *         complete, have been aborted or errored.
+   */
   public boolean checkAll(boolean load)
   {
     MediaEntry e = head;
@@ -141,37 +237,53 @@ public class MediaTracker implements java.io.Serializable
     
     while (e != null)
       {
-	if ((e.status & COMPLETE) == 0)
-	  {
-	    if (load)
-	      {
-		result = false;
-	        if (e.status == 0)
-		  {
-		    target.prepareImage(e.image, e);
-		    e.status = LOADING;
-		  }
-	      }
-	    else
-	      return false;
-	  }
-	e = e.next;
+        if ((e.status & (COMPLETE | ERRORED | ABORTED)) == 0)
+          {
+            if (load && ((e.status & LOADING) == 0))
+              {
+                e.status = LOADING;
+                result = false;
+                boolean complete = target.prepareImage(e.image, e);
+                if (complete)
+                  {
+                    e.status = COMPLETE;
+                    result = true;
+                  }
+              }
+            else
+              result = false;
+          }
+        e = e.next;
       }
     return result;
   }
 
+  /**
+   * Checks if any of the registered media objects has encountered an error
+   * during loading.
+   *
+   * @return <code>true</code> if at least one media object has encountered
+   *         an error during loading, <code>false</code> otherwise
+   *
+   */
   public boolean isErrorAny()
   {
     MediaEntry e = head;    
     while (e != null)
       {
         if ((e.status & ERRORED) != 0)
-	  return true;
+          return true;
         e = e.next;
       }
     return false;
   }
 
+  /**
+   * Returns all media objects that have encountered errors during loading.
+   *
+   * @return an array of all media objects that have encountered errors
+   *         or <code>null</code> if there were no errors at all
+   */
   public Object[] getErrorsAny()
   {
     MediaEntry e = head;
@@ -179,11 +291,11 @@ public class MediaTracker implements java.io.Serializable
     while (e != null)
       {
         if ((e.status & ERRORED) != 0)
-	  {
-	    if (result == null)
-	      result = new ArrayList();
-	    result.add(e.image);
-	  }
+          {
+            if (result == null)
+              result = new ArrayList();
+            result.add(e.image);
+          }
         e = e.next;
       }
     if (result == null)
@@ -192,6 +304,13 @@ public class MediaTracker implements java.io.Serializable
       return result.toArray();
   }
 
+  /**
+   * Waits for all media objects to finish loading, either by completing
+   * successfully or by aborting or encountering an error.
+   *
+   * @throws InterruptedException if another thread interrupted the
+   *         current thread while waiting
+   */
   public void waitForAll() throws InterruptedException
   {
     synchronized (this)
@@ -201,20 +320,51 @@ public class MediaTracker implements java.io.Serializable
     }
   }
 
+  /**
+   * Waits for all media objects to finish loading, either by completing
+   * successfully or by aborting or encountering an error.
+   *
+   * This method waits at most <code>ms</code> milliseconds. If the
+   * media objects have not completed loading within this timeframe, this
+   * method returns <code>false</code>, otherwise <code>true</code>.
+   *
+   * @param ms timeframe in milliseconds to wait for the media objects to
+   *        finish
+   *
+   * @return <code>true</code> if all media objects have successfully loaded
+   *         within the timeframe, <code>false</code> otherwise
+   *
+   * @throws InterruptedException if another thread interrupted the
+   *         current thread while waiting
+   */
   public boolean waitForAll(long ms) throws InterruptedException
   {
     long start = System.currentTimeMillis();
+    boolean result = checkAll(true);
     synchronized (this)
     {
-      while (!checkAll(true))
-        wait(ms);
+      while (result == false)
+        {
+          wait(ms);
+          result = checkAll(true);
+          if ((System.currentTimeMillis() - start) > ms)
+            break;
+        }
     }
-    if ((System.currentTimeMillis() - start) < ms)
-      return true;
-    else
-      return false;
+
+    return result;
   }
 
+  /**
+   * Returns the status flags of all registered media objects ORed together.
+   * If <code>load</code> is <code>true</code> then media objects that
+   * are not already loading will be started to load.
+   *
+   * @param load if set to <code>true</code> then media objects that are
+   *        not already loading are started
+   *
+   * @return the status flags of all tracked media objects ORed together
+   */
   public int statusAll(boolean load)
   {
     int result = 0;
@@ -222,21 +372,44 @@ public class MediaTracker implements java.io.Serializable
     while (e != null)
       {
         if (load && e.status == 0)
-	  {
-	    target.prepareImage(e.image, e);
-	    e.status = LOADING;
-	  }
+          {
+            boolean complete = target.prepareImage(e.image, e);
+            if (complete)
+              e.status = COMPLETE;
+            else
+              e.status = LOADING;
+          }
         result |= e.status;
-	e = e.next;
+        e = e.next;
       }
     return result;
   }
 
+  /**
+   * Checks if the media objects with <code>ID</code> have completed loading.
+   *
+   * @param id the ID of the media objects to check
+   *
+   * @return <code>true</code> if all media objects with <code>ID</code>
+   *         have successfully finished
+   */
   public boolean checkID(int id)
   {
     return checkID(id, false);
   }
 
+  /**
+   * Checks if the media objects with <code>ID</code> have completed loading.
+   * If <code>load</code> is <code>true</code> then media objects that
+   * are not already loading will be started to load.
+   *
+   * @param id the ID of the media objects to check
+   * @param load if set to <code>true</code> then media objects that are
+   *        not already loading are started
+   *
+   * @return <code>true</code> if all media objects with <code>ID</code>
+   *         have successfully finished
+   */
   public boolean checkID(int id, boolean load)
   {
     MediaEntry e = head;
@@ -244,37 +417,57 @@ public class MediaTracker implements java.io.Serializable
     
     while (e != null)
       {
-	if (e.id == id && ((e.status & COMPLETE) == 0))
-	  {
-	    if (load)
-	      {
-		result = false;
-	        if (e.status == 0)
-		  {
-		    target.prepareImage(e.image, e);
-		    e.status = LOADING;
-		  }
-	      }
-	    else
-	      return false;
-	  }
-	e = e.next;
+        if (e.id == id && ((e.status & (COMPLETE | ABORTED | ERRORED)) == 0))
+          {
+            if (load && ((e.status & LOADING) == 0))
+              {
+                e.status = LOADING;
+                result = false;
+                boolean complete = target.prepareImage(e.image, e);
+                if (complete)
+                  {
+                    e.status = COMPLETE;
+                    result = true;
+                  }
+              }
+            else
+              result = false;
+          }
+        e = e.next;
       }
     return result;
   }
 
+  /**
+   * Returns <code>true</code> if any of the media objects with <code>ID</code>
+   * have encountered errors during loading, false otherwise.
+   *
+   * @param id the ID of the media objects to check
+   *
+   * @return <code>true</code> if any of the media objects with <code>ID</code>
+   *         have encountered errors during loading, false otherwise
+   */
   public boolean isErrorID(int id)
   {
     MediaEntry e = head;    
     while (e != null)
       {
         if (e.id == id && ((e.status & ERRORED) != 0))
-	  return true;
+          return true;
         e = e.next;
       }
     return false;
   }
 
+  /**
+   * Returns all media objects with the specified ID that have encountered
+   * an error.
+   *
+   * @param id the ID of the media objects to check
+   *
+   * @return an array of all media objects  with the specified ID that
+   *         have encountered an error
+   */
   public Object[] getErrorsID(int id)
   {
     MediaEntry e = head;
@@ -282,11 +475,11 @@ public class MediaTracker implements java.io.Serializable
     while (e != null)
       {
         if (e.id == id && ((e.status & ERRORED) != 0))
-	  {
-	    if (result == null)
-	      result = new ArrayList();
-	    result.add(e.image);
-	  }
+          {
+            if (result == null)
+              result = new ArrayList();
+            result.add(e.image);
+          }
         e = e.next;
       }
     if (result == null)
@@ -295,6 +488,15 @@ public class MediaTracker implements java.io.Serializable
       return result.toArray();
   }
 
+  /**
+   * Waits for all media objects with the specified ID to finish loading,
+   * either by completing successfully or by aborting or encountering an error.
+   *
+   * @param id the ID of the media objects to wait for
+   *
+   * @throws InterruptedException if another thread interrupted the
+   *         current thread while waiting
+   */
   public void waitForID(int id) throws InterruptedException
   {
     MediaEntry e = head;
@@ -305,21 +507,56 @@ public class MediaTracker implements java.io.Serializable
     }
   }
 
+  /**
+   * Waits for all media objects with the specified ID to finish loading,
+   * either by completing successfully or by aborting or encountering an error.
+   *
+   * This method waits at most <code>ms</code> milliseconds. If the
+   * media objects have not completed loading within this timeframe, this
+   * method returns <code>false</code>, otherwise <code>true</code>.
+   *
+   * @param id the ID of the media objects to wait for
+   * @param ms timeframe in milliseconds to wait for the media objects to
+   *        finish
+   *
+   * @return <code>true</code> if all media objects have successfully loaded
+   *         within the timeframe, <code>false</code> otherwise
+   *
+   * @throws InterruptedException if another thread interrupted the
+   *         current thread while waiting
+   */
   public boolean waitForID(int id, long ms) throws InterruptedException
   {
     MediaEntry e = head;
     long start = System.currentTimeMillis();
+    boolean result = checkID(id, true);
+
     synchronized (this)
     {
-      while (checkID (id, true) == false)
-        wait(ms);
-    }  
-    if ((System.currentTimeMillis() - start) < ms)
-      return true;
-    else
-      return false;
+      while (result == false)
+        {
+          wait(ms);
+          result = checkID(id, true);
+          if ((System.currentTimeMillis() - start) > ms)
+            break;
+        }
+    }
+
+    return result;
   }
 
+  /**
+   * Returns the status flags of the media objects with the specified ID
+   * ORed together.
+   *
+   * If <code>load</code> is <code>true</code> then media objects that
+   * are not already loading will be started to load.
+   *
+   * @param load if set to <code>true</code> then media objects that are
+   *        not already loading are started
+   *
+   * @return the status flags of all tracked media objects ORed together
+   */
   public int statusID(int id, boolean load)
   {
     int result = 0;
@@ -327,73 +564,100 @@ public class MediaTracker implements java.io.Serializable
     while (e != null)
       {
         if (e.id == id)
-	  {
+          {
             if (load && e.status == 0)
-	      {
-		target.prepareImage(e.image, e);
-		e.status = LOADING;
-	      }
+              {
+                boolean complete = target.prepareImage(e.image, e);
+                if (complete)
+                  e.status = COMPLETE;
+                else
+                  e.status = LOADING;
+              }
             result |= e.status;
-	  }
-	e = e.next;
+          }
+        e = e.next;
       }
     return result;
   }
 
+  /**
+   * Removes an image from this MediaTracker.
+   *
+   * @param image the image to be removed
+   */
   public void removeImage(Image image)
   {
-    MediaEntry e = head;
-    MediaEntry prev = null;
-    while (e != null)
+    synchronized (this)
       {
-        if (e.image == image)
-	  {
-	    if (prev == null)
-	      head = e.next;
-	    else
-	      prev.next = e.next;
-	  }
-	prev = e;
-	e = e.next;
+        MediaEntry e = head;
+        MediaEntry prev = null;
+        while (e != null)
+          {
+            if (e.image == image)
+              {
+                if (prev == null)
+                  head = e.next;
+                else
+                  prev.next = e.next;
+              }
+            prev = e;
+            e = e.next;
+          }
       }
   }
 
+  /**
+   * Removes an image with the specified ID from this MediaTracker.
+   *
+   * @param image the image to be removed
+   */
   public void removeImage(Image image, int id)
   {
-    MediaEntry e = head;
-    MediaEntry prev = null;
-    while (e != null)
+    synchronized (this)
       {
-        if (e.id == id && e.image == image)
-	  {
-	    if (prev == null)
-	      head = e.next;
-	    else
-	      prev.next = e.next;
-	  }
-	else
-	  prev = e;
-	e = e.next;
-      }  
+        MediaEntry e = head;
+        MediaEntry prev = null;
+        while (e != null)
+          {
+            if (e.id == id && e.image == image)
+              {
+                if (prev == null)
+                  head = e.next;
+                else
+                  prev.next = e.next;
+              }
+            else
+              prev = e;
+            e = e.next;
+          }
+      }
   }
 
+  /**
+   * Removes an image with the specified ID and scale from this MediaTracker.
+   *
+   * @param image the image to be removed
+   */
   public void removeImage(Image image, int id, int width, int height)
   {
-    MediaEntry e = head;
-    MediaEntry prev = null;
-    while (e != null)
+    synchronized (this)
       {
-        if (e.id == id && e.image == image
-	    && e.width == width && e.height == height)
-	  {
-	    if (prev == null)
-	      head = e.next;
-	    else
-	      prev.next = e.next;
-	  }
-	else
-	  prev = e;
-	e = e.next;
+        MediaEntry e = head;
+        MediaEntry prev = null;
+        while (e != null)
+          {
+            if (e.id == id && e.image == image
+                && e.width == width && e.height == height)
+              {
+                if (prev == null)
+                  head = e.next;
+                else
+                  prev.next = e.next;
+              }
+            else
+              prev = e;
+            e = e.next;
+          }
       }
   }
 }