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
18package 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 */
27public 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     */
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     */
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     */
71    boolean isScheduled() {
72        synchronized (lock) {
73            return when > 0 || scheduledTime > 0;
74        }
75    }
76
77    /**
78     * Creates a new {@code TimerTask}.
79     */
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     */
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     */
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     */
116    public abstract void run();
117
118}
119