1 /* MediaTracker.java -- Class used for keeping track of images 2 Copyright (C) 1999, 2002, 2004, 2005 Free Software Foundation, Inc. 3 4 This file is part of GNU Classpath. 5 6 GNU Classpath is free software; you can redistribute it and/or modify 7 it under the terms of the GNU General Public License as published by 8 the Free Software Foundation; either version 2, or (at your option) 9 any later version. 10 11 GNU Classpath is distributed in the hope that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along with GNU Classpath; see the file COPYING. If not, write to the 18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19 02110-1301 USA. 20 21 Linking this library statically or dynamically with other modules is 22 making a combined work based on this library. Thus, the terms and 23 conditions of the GNU General Public License cover the whole 24 combination. 25 26 As a special exception, the copyright holders of this library give you 27 permission to link this library with independent modules to produce an 28 executable, regardless of the license terms of these independent 29 modules, and to copy and distribute the resulting executable under 30 terms of your choice, provided that you also meet, for each linked 31 independent module, the terms and conditions of the license of that 32 module. An independent module is a module which is not derived from 33 or based on this library. If you modify this library, you may extend 34 this exception to your version of the library, but you are not 35 obligated to do so. If you do not wish to do so, delete this 36 exception statement from your version. */ 37 38 39 package java.awt; 40 41 import java.awt.image.ImageObserver; 42 import java.util.ArrayList; 43 44 /** 45 * This class is used for keeping track of the status of various media 46 * objects. 47 * 48 * Media objects are tracked by assigning them an ID. It is possible 49 * to assign the same ID to mutliple objects, effectivly grouping them 50 * together. In this case the status flags ({@link #statusID}) and error flag 51 * (@link #isErrorID} and {@link #getErrorsID}) are ORed together. This 52 * means that you cannot say exactly which media object has which status, 53 * at most you can say that there <em>are</em> certain media objects with 54 * some certain status. 55 * 56 * At the moment only images are supported by this class. 57 * 58 * @author Aaron M. Renn (arenn@urbanophile.com) 59 * @author Bryce McKinlay 60 */ 61 public class MediaTracker implements java.io.Serializable 62 { 63 /** Indicates that the media is still loading. */ 64 public static final int LOADING = 1 << 0; 65 66 /** Indicates that the loading operation has been aborted. */ 67 public static final int ABORTED = 1 << 1; 68 69 /** Indicates that an error has occured during loading of the media. */ 70 public static final int ERRORED = 1 << 2; 71 72 /** Indicates that the media has been successfully and completely loaded. */ 73 public static final int COMPLETE = 1 << 3; 74 75 /** The component on which the media is eventually been drawn. */ 76 Component target; 77 78 /** The head of the linked list of tracked media objects. */ 79 MediaEntry head; 80 81 /** Our serialVersionUID for serialization. */ 82 static final long serialVersionUID = -483174189758638095L; 83 84 /** 85 * This represents a media object that is tracked by a MediaTracker. 86 * It also implements a simple linked list. 87 */ 88 // FIXME: The serialized form documentation says MediaEntry is a 89 // serializable field, but the serialized form of MediaEntry itself 90 // doesn't appear to be documented. 91 class MediaEntry implements ImageObserver 92 { 93 /** The ID of the media object. */ 94 int id; 95 96 /** The media object. (only images are supported ATM). */ 97 Image image; 98 99 /** The link to the next entry in the list. */ 100 MediaEntry next; 101 102 /** The tracking status. */ 103 int status; 104 105 /** The width of the image. */ 106 int width; 107 108 /** The height of the image. */ 109 int height; 110 111 /** 112 * Receives notification from an {@link java.awt.image.ImageProducer} 113 * that more data of the image is available. 114 * 115 * @param img the image that is updated 116 * @param flags flags from the ImageProducer that indicate the status 117 * of the loading process 118 * @param x the X coordinate of the upper left corner of the image 119 * @param y the Y coordinate of the upper left corner of the image 120 * @param width the width of the image 121 * @param height the height of the image 122 * 123 * @return <code>true</code> if more data is needed, <code>false</code> 124 * otherwise 125 * 126 * @see java.awt.image.ImageObserver 127 */ imageUpdate(Image img, int flags, int x, int y, int width, int height)128 public boolean imageUpdate(Image img, int flags, int x, int y, 129 int width, int height) 130 { 131 if ((flags & ABORT) != 0) 132 status = ABORTED; 133 else if ((flags & ERROR) != 0) 134 status = ERRORED; 135 else if ((flags & ALLBITS) != 0) 136 status = COMPLETE; 137 else 138 status = 0; 139 140 synchronized (MediaTracker.this) 141 { 142 MediaTracker.this.notifyAll(); 143 } 144 145 // If status is not COMPLETE then we need more updates. 146 return ((status & (COMPLETE | ERRORED | ABORTED)) == 0); 147 } 148 } 149 150 /** 151 * Constructs a new MediaTracker for the component <code>c</code>. The 152 * component should be the component that uses the media (i.e. draws it). 153 * 154 * @param c the Component that wants to use the media 155 */ MediaTracker(Component c)156 public MediaTracker(Component c) 157 { 158 target = c; 159 } 160 161 /** 162 * Adds an image to the tracker with the specified <code>ID</code>. 163 * 164 * @param image the image to be added 165 * @param id the ID of the tracker list to which the image is added 166 */ addImage(Image image, int id)167 public void addImage(Image image, int id) 168 { 169 MediaEntry e = new MediaEntry(); 170 e.id = id; 171 e.image = image; 172 synchronized(this) 173 { 174 e.next = head; 175 head = e; 176 } 177 } 178 179 /** 180 * Adds an image to the tracker with the specified <code>ID</code>. 181 * The image is expected to be rendered with the specified width and 182 * height. 183 * 184 * @param image the image to be added 185 * @param id the ID of the tracker list to which the image is added 186 * @param width the width of the image 187 * @param height the height of the image 188 */ addImage(Image image, int id, int width, int height)189 public void addImage(Image image, int id, int width, int height) 190 { 191 MediaEntry e = new MediaEntry(); 192 e.id = id; 193 e.image = image; 194 e.width = width; 195 e.height = height; 196 synchronized(this) 197 { 198 e.next = head; 199 head = e; 200 } 201 } 202 203 /** 204 * Checks if all media objects have finished loading, i.e. are 205 * {@link #COMPLETE}, {@link #ABORTED} or {@link #ERRORED}. 206 * 207 * If the media objects are not already loading, a call to this 208 * method does <em>not</em> start loading. This is equivalent to 209 * a call to <code>checkAll(false)</code>. 210 * 211 * @return if all media objects have finished loading either by beeing 212 * complete, have been aborted or errored. 213 */ checkAll()214 public boolean checkAll() 215 { 216 return checkAll(false); 217 } 218 219 /** 220 * Checks if all media objects have finished loading, i.e. are 221 * {@link #COMPLETE}, {@link #ABORTED} or {@link #ERRORED}. 222 * 223 * If the media objects are not already loading, and <code>load</code> 224 * is <code>true</code> then a call to this 225 * method starts loading the media objects. 226 * 227 * @param load if <code>true</code> this method starts loading objects 228 * that are not already loading 229 * 230 * @return if all media objects have finished loading either by beeing 231 * complete, have been aborted or errored. 232 */ checkAll(boolean load)233 public boolean checkAll(boolean load) 234 { 235 MediaEntry e = head; 236 boolean result = true; 237 238 while (e != null) 239 { 240 if ((e.status & (COMPLETE | ERRORED | ABORTED)) == 0) 241 { 242 if (load && ((e.status & LOADING) == 0)) 243 { 244 if (target.prepareImage(e.image, e)) 245 e.status = COMPLETE; 246 else 247 { 248 e.status = LOADING; 249 int flags = target.checkImage(e.image, e); 250 if ((flags & ImageObserver.ABORT) != 0) 251 e.status = ABORTED; 252 else if ((flags & ImageObserver.ERROR) != 0) 253 e.status = ERRORED; 254 else if ((flags & ImageObserver.ALLBITS) != 0) 255 e.status = COMPLETE; 256 } 257 boolean complete = (e.status 258 & (COMPLETE | ABORTED | ERRORED)) != 0; 259 if (!complete) 260 result = false; 261 } 262 else 263 result = false; 264 } 265 e = e.next; 266 } 267 return result; 268 } 269 270 /** 271 * Checks if any of the registered media objects has encountered an error 272 * during loading. 273 * 274 * @return <code>true</code> if at least one media object has encountered 275 * an error during loading, <code>false</code> otherwise 276 * 277 */ isErrorAny()278 public boolean isErrorAny() 279 { 280 MediaEntry e = head; 281 while (e != null) 282 { 283 if ((e.status & ERRORED) != 0) 284 return true; 285 e = e.next; 286 } 287 return false; 288 } 289 290 /** 291 * Returns all media objects that have encountered errors during loading. 292 * 293 * @return an array of all media objects that have encountered errors 294 * or <code>null</code> if there were no errors at all 295 */ getErrorsAny()296 public Object[] getErrorsAny() 297 { 298 MediaEntry e = head; 299 ArrayList result = null; 300 while (e != null) 301 { 302 if ((e.status & ERRORED) != 0) 303 { 304 if (result == null) 305 result = new ArrayList(); 306 result.add(e.image); 307 } 308 e = e.next; 309 } 310 if (result == null) 311 return null; 312 else 313 return result.toArray(); 314 } 315 316 /** 317 * Waits for all media objects to finish loading, either by completing 318 * successfully or by aborting or encountering an error. 319 * 320 * @throws InterruptedException if another thread interrupted the 321 * current thread while waiting 322 */ waitForAll()323 public void waitForAll() throws InterruptedException 324 { 325 synchronized (this) 326 { 327 while (checkAll(true) == false) 328 wait(); 329 } 330 } 331 332 /** 333 * Waits for all media objects to finish loading, either by completing 334 * successfully or by aborting or encountering an error. 335 * 336 * This method waits at most <code>ms</code> milliseconds. If the 337 * media objects have not completed loading within this timeframe, this 338 * method returns <code>false</code>, otherwise <code>true</code>. 339 * 340 * @param ms timeframe in milliseconds to wait for the media objects to 341 * finish 342 * 343 * @return <code>true</code> if all media objects have successfully loaded 344 * within the timeframe, <code>false</code> otherwise 345 * 346 * @throws InterruptedException if another thread interrupted the 347 * current thread while waiting 348 */ waitForAll(long ms)349 public boolean waitForAll(long ms) throws InterruptedException 350 { 351 long start = System.currentTimeMillis(); 352 boolean result = checkAll(true); 353 synchronized (this) 354 { 355 while (result == false) 356 { 357 wait(ms); 358 result = checkAll(true); 359 if ((System.currentTimeMillis() - start) > ms) 360 break; 361 } 362 } 363 364 return result; 365 } 366 367 /** 368 * Returns the status flags of all registered media objects ORed together. 369 * If <code>load</code> is <code>true</code> then media objects that 370 * are not already loading will be started to load. 371 * 372 * @param load if set to <code>true</code> then media objects that are 373 * not already loading are started 374 * 375 * @return the status flags of all tracked media objects ORed together 376 */ statusAll(boolean load)377 public int statusAll(boolean load) 378 { 379 int result = 0; 380 MediaEntry e = head; 381 while (e != null) 382 { 383 if (load && e.status == 0) 384 { 385 if (target.prepareImage(e.image, e)) 386 e.status = COMPLETE; 387 else 388 { 389 e.status = LOADING; 390 int flags = target.checkImage(e.image, e); 391 if ((flags & ImageObserver.ABORT) != 0) 392 e.status = ABORTED; 393 else if ((flags & ImageObserver.ERROR) != 0) 394 e.status = ERRORED; 395 else if ((flags & ImageObserver.ALLBITS) != 0) 396 e.status = COMPLETE; 397 } 398 } 399 result |= e.status; 400 e = e.next; 401 } 402 return result; 403 } 404 405 /** 406 * Checks if the media objects with <code>ID</code> have completed loading. 407 * 408 * @param id the ID of the media objects to check 409 * 410 * @return <code>true</code> if all media objects with <code>ID</code> 411 * have successfully finished 412 */ checkID(int id)413 public boolean checkID(int id) 414 { 415 return checkID(id, false); 416 } 417 418 /** 419 * Checks if the media objects with <code>ID</code> have completed loading. 420 * If <code>load</code> is <code>true</code> then media objects that 421 * are not already loading will be started to load. 422 * 423 * @param id the ID of the media objects to check 424 * @param load if set to <code>true</code> then media objects that are 425 * not already loading are started 426 * 427 * @return <code>true</code> if all media objects with <code>ID</code> 428 * have successfully finished 429 */ checkID(int id, boolean load)430 public boolean checkID(int id, boolean load) 431 { 432 MediaEntry e = head; 433 boolean result = true; 434 435 while (e != null) 436 { 437 if (e.id == id && ((e.status & (COMPLETE | ABORTED | ERRORED)) == 0)) 438 { 439 if (load && ((e.status & LOADING) == 0)) 440 { 441 e.status = LOADING; 442 if (target.prepareImage(e.image, e)) 443 e.status = COMPLETE; 444 else 445 { 446 int flags = target.checkImage(e.image, e); 447 if ((flags & ImageObserver.ABORT) != 0) 448 e.status = ABORTED; 449 else if ((flags & ImageObserver.ERROR) != 0) 450 e.status = ERRORED; 451 else if ((flags & ImageObserver.ALLBITS) != 0) 452 e.status = COMPLETE; 453 } 454 boolean complete = (e.status 455 & (COMPLETE | ABORTED | ERRORED)) != 0; 456 if (!complete) 457 result = false; 458 } 459 else 460 result = false; 461 } 462 e = e.next; 463 } 464 return result; 465 } 466 467 /** 468 * Returns <code>true</code> if any of the media objects with <code>ID</code> 469 * have encountered errors during loading, false otherwise. 470 * 471 * @param id the ID of the media objects to check 472 * 473 * @return <code>true</code> if any of the media objects with <code>ID</code> 474 * have encountered errors during loading, false otherwise 475 */ isErrorID(int id)476 public boolean isErrorID(int id) 477 { 478 MediaEntry e = head; 479 while (e != null) 480 { 481 if (e.id == id && ((e.status & ERRORED) != 0)) 482 return true; 483 e = e.next; 484 } 485 return false; 486 } 487 488 /** 489 * Returns all media objects with the specified ID that have encountered 490 * an error. 491 * 492 * @param id the ID of the media objects to check 493 * 494 * @return an array of all media objects with the specified ID that 495 * have encountered an error 496 */ getErrorsID(int id)497 public Object[] getErrorsID(int id) 498 { 499 MediaEntry e = head; 500 ArrayList result = null; 501 while (e != null) 502 { 503 if (e.id == id && ((e.status & ERRORED) != 0)) 504 { 505 if (result == null) 506 result = new ArrayList(); 507 result.add(e.image); 508 } 509 e = e.next; 510 } 511 if (result == null) 512 return null; 513 else 514 return result.toArray(); 515 } 516 517 /** 518 * Waits for all media objects with the specified ID to finish loading, 519 * either by completing successfully or by aborting or encountering an error. 520 * 521 * @param id the ID of the media objects to wait for 522 * 523 * @throws InterruptedException if another thread interrupted the 524 * current thread while waiting 525 */ waitForID(int id)526 public void waitForID(int id) throws InterruptedException 527 { 528 MediaEntry e = head; 529 synchronized (this) 530 { 531 while (checkID (id, true) == false) 532 wait(); 533 } 534 } 535 536 /** 537 * Waits for all media objects with the specified ID to finish loading, 538 * either by completing successfully or by aborting or encountering an error. 539 * 540 * This method waits at most <code>ms</code> milliseconds. If the 541 * media objects have not completed loading within this timeframe, this 542 * method returns <code>false</code>, otherwise <code>true</code>. 543 * 544 * @param id the ID of the media objects to wait for 545 * @param ms timeframe in milliseconds to wait for the media objects to 546 * finish 547 * 548 * @return <code>true</code> if all media objects have successfully loaded 549 * within the timeframe, <code>false</code> otherwise 550 * 551 * @throws InterruptedException if another thread interrupted the 552 * current thread while waiting 553 */ waitForID(int id, long ms)554 public boolean waitForID(int id, long ms) throws InterruptedException 555 { 556 MediaEntry e = head; 557 long start = System.currentTimeMillis(); 558 boolean result = checkID(id, true); 559 560 synchronized (this) 561 { 562 while (result == false) 563 { 564 wait(ms); 565 result = checkID(id, true); 566 if ((System.currentTimeMillis() - start) > ms) 567 break; 568 } 569 } 570 571 return result; 572 } 573 574 /** 575 * Returns the status flags of the media objects with the specified ID 576 * ORed together. 577 * 578 * If <code>load</code> is <code>true</code> then media objects that 579 * are not already loading will be started to load. 580 * 581 * @param load if set to <code>true</code> then media objects that are 582 * not already loading are started 583 * 584 * @return the status flags of all tracked media objects ORed together 585 */ statusID(int id, boolean load)586 public int statusID(int id, boolean load) 587 { 588 int result = 0; 589 MediaEntry e = head; 590 while (e != null) 591 { 592 if (e.id == id) 593 { 594 if (load && e.status == 0) 595 { 596 if (target.prepareImage(e.image, e)) 597 e.status = COMPLETE; 598 else 599 { 600 e.status = LOADING; 601 int flags = target.checkImage(e.image, e); 602 if ((flags & ImageObserver.ABORT) != 0) 603 e.status = ABORTED; 604 else if ((flags & ImageObserver.ERROR) != 0) 605 e.status = ERRORED; 606 else if ((flags & ImageObserver.ALLBITS) != 0) 607 e.status = COMPLETE; 608 } 609 } 610 result |= e.status; 611 } 612 e = e.next; 613 } 614 return result; 615 } 616 617 /** 618 * Removes an image from this MediaTracker. 619 * 620 * @param image the image to be removed 621 */ removeImage(Image image)622 public void removeImage(Image image) 623 { 624 synchronized (this) 625 { 626 MediaEntry e = head; 627 MediaEntry prev = null; 628 while (e != null) 629 { 630 if (e.image == image) 631 { 632 if (prev == null) 633 head = e.next; 634 else 635 prev.next = e.next; 636 } 637 else 638 prev = e; 639 e = e.next; 640 } 641 } 642 } 643 644 /** 645 * Removes an image with the specified ID from this MediaTracker. 646 * 647 * @param image the image to be removed 648 */ removeImage(Image image, int id)649 public void removeImage(Image image, int id) 650 { 651 synchronized (this) 652 { 653 MediaEntry e = head; 654 MediaEntry prev = null; 655 while (e != null) 656 { 657 if (e.id == id && e.image == image) 658 { 659 if (prev == null) 660 head = e.next; 661 else 662 prev.next = e.next; 663 } 664 else 665 prev = e; 666 e = e.next; 667 } 668 } 669 } 670 671 /** 672 * Removes an image with the specified ID and scale from this MediaTracker. 673 * 674 * @param image the image to be removed 675 */ removeImage(Image image, int id, int width, int height)676 public void removeImage(Image image, int id, int width, int height) 677 { 678 synchronized (this) 679 { 680 MediaEntry e = head; 681 MediaEntry prev = null; 682 while (e != null) 683 { 684 if (e.id == id && e.image == image 685 && e.width == width && e.height == height) 686 { 687 if (prev == null) 688 head = e.next; 689 else 690 prev.next = e.next; 691 } 692 else 693 prev = e; 694 e = e.next; 695 } 696 } 697 } 698 } 699