1 /*
2  *  Licensed to the Apache Software Foundation (ASF) under one or more
3  *  contributor license agreements.  See the NOTICE file distributed with
4  *  this work for additional information regarding copyright ownership.
5  *  The ASF licenses this file to You under the Apache License, Version 2.0
6  *  (the "License"); you may not use this file except in compliance with
7  *  the License.  You may obtain a copy of the License at
8  *
9  *     http://www.apache.org/licenses/LICENSE-2.0
10  *
11  *  Unless required by applicable law or agreed to in writing, software
12  *  distributed under the License is distributed on an "AS IS" BASIS,
13  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  *  See the License for the specific language governing permissions and
15  *  limitations under the License.
16  */
17 
18 package java.util;
19 
20 /**
21  * The {@code TimerTask} class represents a task to run at a specified time. The task
22  * may be run once or repeatedly.
23  *
24  * @see Timer
25  * @see java.lang.Object#wait(long)
26  */
27 public abstract class TimerTask implements Runnable {
28     /* Lock object for synchronization. It's also used by Timer class. */
29     final Object lock = new Object();
30 
31     /* If timer was cancelled */
32     boolean cancelled;
33 
34     /* Slots used by Timer */
35     long when;
36 
37     long period;
38 
39     boolean fixedRate;
40 
41     /*
42      * The time when task will be executed, or the time when task was launched
43      * if this is task in progress.
44      */
45     private long scheduledTime;
46 
47     /*
48      * Method called from the Timer for synchronized getting of when field.
49      */
getWhen()50     long getWhen() {
51         synchronized (lock) {
52             return when;
53         }
54     }
55 
56     /*
57      * Method called from the Timer object when scheduling an event @param time
58      */
setScheduledTime(long time)59     void setScheduledTime(long time) {
60         synchronized (lock) {
61             scheduledTime = time;
62         }
63     }
64 
65     /*
66      * Is TimerTask scheduled into any timer?
67      *
68      * @return {@code true} if the timer task is scheduled, {@code false}
69      * otherwise.
70      */
isScheduled()71     boolean isScheduled() {
72         synchronized (lock) {
73             return when > 0 || scheduledTime > 0;
74         }
75     }
76 
77     /**
78      * Creates a new {@code TimerTask}.
79      */
TimerTask()80     protected TimerTask() {
81     }
82 
83     /**
84      * Cancels the {@code TimerTask} and removes it from the {@code Timer}'s queue. Generally, it
85      * returns {@code false} if the call did not prevent a {@code TimerTask} from running at
86      * least once. Subsequent calls have no effect.
87      *
88      * @return {@code true} if the call prevented a scheduled execution
89      *         from taking place, {@code false} otherwise.
90      */
cancel()91     public boolean cancel() {
92         synchronized (lock) {
93             boolean willRun = !cancelled && when > 0;
94             cancelled = true;
95             return willRun;
96         }
97     }
98 
99     /**
100      * Returns the scheduled execution time. If the task execution is in
101      * progress it returns the execution time of the ongoing task. Tasks which
102      * have not yet run return an undefined value.
103      *
104      * @return the most recent execution time.
105      */
scheduledExecutionTime()106     public long scheduledExecutionTime() {
107         synchronized (lock) {
108             return scheduledTime;
109         }
110     }
111 
112     /**
113      * The task to run should be specified in the implementation of the {@code run()}
114      * method.
115      */
run()116     public abstract void run();
117 
118 }
119