1. /*
  2. * @(#)TimerTask.java 1.10 04/02/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.util;
  8. /**
  9. * A task that can be scheduled for one-time or repeated execution by a Timer.
  10. *
  11. * @author Josh Bloch
  12. * @version 1.10, 02/19/04
  13. * @see Timer
  14. * @since 1.3
  15. */
  16. public abstract class TimerTask implements Runnable {
  17. /**
  18. * This object is used to control access to the TimerTask internals.
  19. */
  20. final Object lock = new Object();
  21. /**
  22. * The state of this task, chosen from the constants below.
  23. */
  24. int state = VIRGIN;
  25. /**
  26. * This task has not yet been scheduled.
  27. */
  28. static final int VIRGIN = 0;
  29. /**
  30. * This task is scheduled for execution. If it is a non-repeating task,
  31. * it has not yet been executed.
  32. */
  33. static final int SCHEDULED = 1;
  34. /**
  35. * This non-repeating task has already executed (or is currently
  36. * executing) and has not been cancelled.
  37. */
  38. static final int EXECUTED = 2;
  39. /**
  40. * This task has been cancelled (with a call to TimerTask.cancel).
  41. */
  42. static final int CANCELLED = 3;
  43. /**
  44. * Next execution time for this task in the format returned by
  45. * System.currentTimeMillis, assuming this task is scheduled for execution.
  46. * For repeating tasks, this field is updated prior to each task execution.
  47. */
  48. long nextExecutionTime;
  49. /**
  50. * Period in milliseconds for repeating tasks. A positive value indicates
  51. * fixed-rate execution. A negative value indicates fixed-delay execution.
  52. * A value of 0 indicates a non-repeating task.
  53. */
  54. long period = 0;
  55. /**
  56. * Creates a new timer task.
  57. */
  58. protected TimerTask() {
  59. }
  60. /**
  61. * The action to be performed by this timer task.
  62. */
  63. public abstract void run();
  64. /**
  65. * Cancels this timer task. If the task has been scheduled for one-time
  66. * execution and has not yet run, or has not yet been scheduled, it will
  67. * never run. If the task has been scheduled for repeated execution, it
  68. * will never run again. (If the task is running when this call occurs,
  69. * the task will run to completion, but will never run again.)
  70. *
  71. * <p>Note that calling this method from within the <tt>run</tt> method of
  72. * a repeating timer task absolutely guarantees that the timer task will
  73. * not run again.
  74. *
  75. * <p>This method may be called repeatedly; the second and subsequent
  76. * calls have no effect.
  77. *
  78. * @return true if this task is scheduled for one-time execution and has
  79. * not yet run, or this task is scheduled for repeated execution.
  80. * Returns false if the task was scheduled for one-time execution
  81. * and has already run, or if the task was never scheduled, or if
  82. * the task was already cancelled. (Loosely speaking, this method
  83. * returns <tt>true</tt> if it prevents one or more scheduled
  84. * executions from taking place.)
  85. */
  86. public boolean cancel() {
  87. synchronized(lock) {
  88. boolean result = (state == SCHEDULED);
  89. state = CANCELLED;
  90. return result;
  91. }
  92. }
  93. /**
  94. * Returns the <i>scheduled</i> execution time of the most recent
  95. * <i>actual</i> execution of this task. (If this method is invoked
  96. * while task execution is in progress, the return value is the scheduled
  97. * execution time of the ongoing task execution.)
  98. *
  99. * <p>This method is typically invoked from within a task's run method, to
  100. * determine whether the current execution of the task is sufficiently
  101. * timely to warrant performing the scheduled activity:
  102. * <pre>
  103. * public void run() {
  104. * if (System.currentTimeMillis() - scheduledExecutionTime() >=
  105. * MAX_TARDINESS)
  106. * return; // Too late; skip this execution.
  107. * // Perform the task
  108. * }
  109. * </pre>
  110. * This method is typically <i>not</i> used in conjunction with
  111. * <i>fixed-delay execution</i> repeating tasks, as their scheduled
  112. * execution times are allowed to drift over time, and so are not terribly
  113. * significant.
  114. *
  115. * @return the time at which the most recent execution of this task was
  116. * scheduled to occur, in the format returned by Date.getTime().
  117. * The return value is undefined if the task has yet to commence
  118. * its first execution.
  119. * @see Date#getTime()
  120. */
  121. public long scheduledExecutionTime() {
  122. synchronized(lock) {
  123. return (period < 0 ? nextExecutionTime + period
  124. : nextExecutionTime - period);
  125. }
  126. }
  127. }