Java Timer

1. Timer – the Basics

Timer and TimerTask are java util classes used to schedule tasks in a background thread. In a few words – TimerTask is the task to perform and Timer is the scheduler.

2. Schedule a Task Once

2.1. After a Given Delay

Let’s start by simply running a single task with the help of a Timer:

@Test
public void givenUsingTimer_whenSchedulingTaskOnce_thenCorrect() {
    TimerTask task = new TimerTask() {
        public void run() {
            System.out.println("Task performed on: " + new Date() + "n" +
              "Thread's name: " + Thread.currentThread().getName());
        }
    };
    Timer timer = new Timer("Timer");
    
    long delay = 1000L;
    timer.schedule(task, delay);
}

Now, this performs the task after a certain delay, given as the second parameter of the schedule() method. We’ll see in the next section how to schedule a task at a given date and time.

Note that if we are running this is a JUnit test, we should add a Thread.sleep(delay * 2) call to allow the Timer’s thread to run the task before the Junit test stops executing.

2.2. At a Given Date and Time

Now, let’s see the Timer#schedule(TimerTask, Date) method, which takes a Date instead of a long as its second parameter, allowing us to schedule the task at a certain instant, rather than after a delay.

This time, let’s imagine we have an old legacy database and we want to migrate its data into a new database with a better schema.

We could create a DatabaseMigrationTask class that’ll handle that migration:

public class DatabaseMigrationTask extends TimerTask {
    private List<String> oldDatabase;
    private List<String> newDatabase;

    public DatabaseMigrationTask(List<String> oldDatabase, List<String> newDatabase) {
        this.oldDatabase = oldDatabase;
        this.newDatabase = newDatabase;
    }

    @Override
    public void run() {
        newDatabase.addAll(oldDatabase);
    }
}

For simplicity, we’re representing the two databases by a List of String. Simply put, our migration consists of putting the data from the first list into the second.

To perform this migration at the desired instant, we’ll have to use the overloaded version of the schedule() method:

List<String> oldDatabase = Arrays.asList("Harrison Ford", "Carrie Fisher", "Mark Hamill");
List<String> newDatabase = new ArrayList<>();

LocalDateTime twoSecondsLater = LocalDateTime.now().plusSeconds(2);
Date twoSecondsLaterAsDate = Date.from(twoSecondsLater.atZone(ZoneId.systemDefault()).toInstant());

new Timer().schedule(new DatabaseMigrationTask(oldDatabase, newDatabase), twoSecondsLaterAsDate);

As we can see, we give the migration task as well as the date of execution to the schedule() method.

Then, the migration is executed at the time indicated by twoSecondsLater:

while (LocalDateTime.now().isBefore(twoSecondsLater)) {
    assertThat(newDatabase).isEmpty();
    Thread.sleep(500);
}
assertThat(newDatabase).containsExactlyElementsOf(oldDatabase);

While we’re before this moment, the migration doesn’t occur.

3. Schedule a Repeatable a Task

Now that we’ve covered how to schedule the single execution of a task, let’s see how to deal with repeatable tasks.

Once again, there are multiple possibilities offered by the Timer class: We can set up the repetition to observe either a fixed delay or a fixed rate.

A fixed delay means that execution will start a period of time after the moment last execution started, even if it was delayed (therefore being itself delayed).

Let’s say we want to schedule some task every two seconds, and that the first execution takes one second and the second one takes two but is delayed by one second. Then, the third execution would start at the fifth second:

0s     1s    2s     3s           5s
|--T1--|
|-----2s-----|--1s--|-----T2-----|
|-----2s-----|--1s--|-----2s-----|--T3--|

On the other hand, a fixed rate means that each execution will respect the initial schedule, no matter if a previous execution has been delayed.

Let’s reuse our previous example, with a fixed rate, the second task will start after three seconds (because of the delay). But, the third one after four seconds (respecting the initial schedule of one execution every two seconds):

0s     1s    2s     3s    4s
|--T1--|       
|-----2s-----|--1s--|-----T2-----|
|-----2s-----|-----2s-----|--T3--|

These two principles being covered, let’s can see how to use them.

In order to use fixed-delay scheduling, there are two more overloads of the schedule() method, each taking an extra parameter stating the periodicity in milliseconds.

Why two overloads? Because there is still the possibility to start the task at a certain moment or after a certain delay.

As for the fixed-rate scheduling, we have the two scheduleAtFixedRate() methods also taking a periodicity in milliseconds. Again, we’ve got one method to start the task at a given date and time and another to start it after a given delay.

It’s also worth mentioning that, if a task takes more time than the period to execute, it delays the whole chain of executions whether we’re using fixed-delay or fixed-rate.

3.1. With a Fixed Delay

Now, let’s imagine we want to implement a newsletter system, sending an email to our followers every week. In that case, a repetitive task seems ideal.

So, let’s schedule the newsletter every second, which is basically spamming, but as the sending is fake we’re good to go!

Let’s first design a NewsletterTask:

public class NewsletterTask extends TimerTask {
    @Override
    public void run() {
        System.out.println("Email sent at: " 
          + LocalDateTime.ofInstant(Instant.ofEpochMilli(scheduledExecutionTime()), 
          ZoneId.systemDefault()));
    }
}

Each time it executes, the task will print its scheduled time, which we gather using the TimerTask#scheduledExecutionTime() method.

Then, what if we want to schedule this task every second in fixed-delay mode? We’ll have to use the overloaded version of schedule() we talked about earlier:

new Timer().schedule(new NewsletterTask(), 0, 1000);

for (int i = 0; i < 3; i++) {
    Thread.sleep(1000);
}

Of course, we only carry the tests for a few occurrences:

Email sent at: 2020-01-01T10:50:30.860
Email sent at: 2020-01-01T10:50:31.860
Email sent at: 2020-01-01T10:50:32.861
Email sent at: 2020-01-01T10:50:33.861

As we can see, there is at least one second between each execution, but they are sometimes delayed by a millisecond. That phenomenon is due to our decision to used fixed-delay repetition.

3.2. With a Fixed Rate

Now, what if we were to use a fixed-rate repetition? Then we would’ve to use the scheduledAtFixedRate() method:

new Timer().scheduleAtFixedRate(new NewsletterTask(), 0, 1000);

for (int i = 0; i < 3; i++) {
    Thread.sleep(1000);
}

This time, executions are not delayed by the previous ones:

Email sent at: 2020-01-01T10:55:03.805
Email sent at: 2020-01-01T10:55:04.805
Email sent at: 2020-01-01T10:55:05.805
Email sent at: 2020-01-01T10:55:06.805

3.3. Schedule a Daily Task

Next, let’s run a task once a day:

@Test
public void givenUsingTimer_whenSchedulingDailyTask_thenCorrect() {
    TimerTask repeatedTask = new TimerTask() {
        public void run() {
            System.out.println("Task performed on " + new Date());
        }
    };
    Timer timer = new Timer("Timer");
    
    long delay = 1000L;
    long period = 1000L * 60L * 60L * 24L;
    timer.scheduleAtFixedRate(repeatedTask, delay, period);
}

4. Cancel Timer and TimerTask

An execution of a task can be canceled in a few ways:

4.1. Cancel the TimerTask Inside Run

By calling the TimerTask.cancel() method inside the run() method’s implementation of the TimerTask itself:

@Test
public void givenUsingTimer_whenCancelingTimerTask_thenCorrect()
  throws InterruptedException {
    TimerTask task = new TimerTask() {
        public void run() {
            System.out.println("Task performed on " + new Date());
            cancel();
        }
    };
    Timer timer = new Timer("Timer");
    
    timer.scheduleAtFixedRate(task, 1000L, 1000L);
    
    Thread.sleep(1000L * 2);
}

4.2. Cancel the Timer

By calling the Timer.cancel() method on a Timer object:

@Test
public void givenUsingTimer_whenCancelingTimer_thenCorrect() 
  throws InterruptedException {
    TimerTask task = new TimerTask() {
        public void run() {
            System.out.println("Task performed on " + new Date());
        }
    };
    Timer timer = new Timer("Timer");
    
    timer.scheduleAtFixedRate(task, 1000L, 1000L);
    
    Thread.sleep(1000L * 2); 
    timer.cancel(); 
}

4.3. Stop the Thread of the TimerTask Inside Run

You can also stop the thread inside the run method of the task, thus canceling the entire task:

@Test
public void givenUsingTimer_whenStoppingThread_thenTimerTaskIsCancelled() 
  throws InterruptedException {
    TimerTask task = new TimerTask() {
        public void run() {
            System.out.println("Task performed on " + new Date());
            // TODO: stop the thread here
        }
    };
    Timer timer = new Timer("Timer");
    
    timer.scheduleAtFixedRate(task, 1000L, 1000L);
    
    Thread.sleep(1000L * 2); 
}

Notice the TODO instruction in the run implementation – in order to run this simple example, we’ll need to actually stop the thread.

In a real-world custom thread implementation, stopping the thread should be supported, but in this case we can ignore the deprecation and use the simple stop API on the Thread class itself.

5. Timer vs ExecutorService

You can also make good use of an ExecutorService to schedule timer tasks, instead of using the timer.

Here’s a quick example of how to run a repeated task at a specified interval:

@Test
public void givenUsingExecutorService_whenSchedulingRepeatedTask_thenCorrect() 
  throws InterruptedException {
    TimerTask repeatedTask = new TimerTask() {
        public void run() {
            System.out.println("Task performed on " + new Date());
        }
    };
    ScheduledExecutorService executor = Executors.newSingleThreadScheduledExecutor();
    long delay  = 1000L;
    long period = 1000L;
    executor.scheduleAtFixedRate(repeatedTask, delay, period, TimeUnit.MILLISECONDS);
    Thread.sleep(delay + period * 3);
    executor.shutdown();
}

So what are the main differences between the Timer and the ExecutorService solution:

• Timer can be sensitive to changes in the system clock; ScheduledThreadPoolExecutor is not
• Timer has only one execution thread; ScheduledThreadPoolExecutor can be configured with any number of threads
• Runtime Exceptions thrown inside the TimerTask kill the thread, so following scheduled tasks won’t run further; with ScheduledThreadExecutor – the current task will be canceled, but the rest will continue to run

6. Conclusion

This tutorial illustrated the many ways you can make use of the simple yet flexible Timer and TimerTask infrastructure built into Java, for quickly scheduling tasks. There are of course much more complex and complete solutions in the Java world if you need them – such as the Quartz library – but this is a very good place to start.

The implementation of these examples can be found in the GitHub project – this is an Eclipse-based project, so it should be easy to import and run as it is.