Package net.sf.eBusx.util

This package provides an eBus interface for accessing Timer API. This eBus interface is useful if Java timer tasks are treated as events to be delivered to an object rather than autonomous tasks. If treated as tasks, then Timer should be used. Otherwise, the advantage in using eBus timer request/reply messages is that it allows for uniform event processing. All events are delivered as eBus messages.

The eBus timer request allows for all six Timer scheduling methods to be accessed:

  1. Timer.schedule(java.util.TimerTask, java.util.Date): send the request 
    TimerRequest.builder()
            .timerName("name")
            .time(java.time.Instant)
            .build()
    to schedule a one-shot timer that expires on a given date and time.
  2. Timer.schedule(java.util.TimerTask, long): send the request 
    TimerRequest.builder()
            .timerName("name")
            .delay(long)
            .build()
    to schedule a one-shot timer that expires after a millisecond delay.
  3. Timer.schedule(java.util.TimerTask, java.util.Date, long): send the request 
    TimerRequest.builder()
            .timerName("name")
            .time(Instant)
            .period(long)
            .build()
    to schedule a repeated fixed-delay execution timer beginning at the specified date and time and repeating at the millisecond period. The timer continues running until the request is canceled.
  4. Timer.scheduleAtFixedRate(java.util.TimerTask, java.util.Date, long): send the request 
    TimerRequest.builder()
            .timerName("name")
            .time(Instant)
            .period(long)
            .fixedRate(true)
            .build()
    to schedule a repeated fixed-rate execution, beginning at the specified date and time and repeating at the millisecond period. The timer continues running until the request is canceled.
  5. Timer.schedule(java.util.TimerTask, long, long): send the request 
    TimerRequest.builder()
            .timerName("name")
            .delay(long)
            .period(long)
            .build()
    to schedule a repeated fixed-delay execution, beginning at the specified millisecond delay and repeating at the millisecond period. The timer continues running until the request is canceled.
  6. Timer.scheduleAtFixedRate(java.util.TimerTask, long, long): send the request 
    TimerRequest.builder()
            .timerName("name")
            .delay(long)
            .period(long)
            .fixedRate(true)
            .build()
    to schedule a repeated fixed-rate execution, beginning at the specified millisecond delay and repeating at the millisecond period. The timer continues running until the request is canceled.
Each timer request must be given a name that is unique among the currently executing timers. It is possible to re-use a timer name as long as there is not a timer with the same name at the same time.

The TimerReply message is sent when the requested timer expires. If it is for a one-shot timer, the reply final reply flag is set to true. Otherwise, a repeating timer will continue until the timer request is canceled.

The eBus timer service is only available to ERequestor objects in the same JVM. An object cannot remotely access an eBus timer service.

Starting and Stopping ETimer

ETimer must be running before any timer requests may be placed. ETimer is started by calling ETimer.startETimer();. ETimer is stopped by calling ETimer.stopETimer();

Subscribing to ETimer

Before timer requests may be placed, the ERequestor must first subscribe to ETimer. The example assumes that this object implements the ERequestor interface and mTimerFeed and mTimerReq are class data members. 

 ERequestFeed mTimerFeed;
 ERequestFeed.ERequest mTimerReq;

 mTimerFeed = ERequestFeed.open(this, ETimer.TIMER_KEY, EFeed.FeedScope.LOCAL_ONLY);
 mTimerFeed.subscribe();

Placing ETimer requests

The following code examples show how to make timer requests.

One time date timer: 
 // Set a timer for the top of the next hour.
 final Calendar calendar = Calendar.getInstance();

 calendar.add(Calendar.HOUR_OF_DAY, 1);
 calendar.set(Calendar.MINUTE, 0);
 calendar.set(Calendar.SECOND, 0);
 calendar.set(Calendar.MILLISECOND, 0);

 mTimerReq = mTimerFeed.request(new TimerRequest("hourly_timer", calendar.getTime()), this);
One time millisecond delay: 
 // Set a timer for 5 seconds into the future.
 mTimerReq = mTimerFeed.request(new TimerRequest("five_seconds", 5000L), this);
Repeating timer for date, period, and fixed delay: 
 // Set a timer for the top of the next hour and every hour after that.
 final Calendar calendar = Calendar.getInstance();

 calendar.add(Calendar.HOUR_OF_DAY, 1);
 calendar.set(Calendar.MINUTE, 0);
 calendar.set(Calendar.SECOND, 0);
 calendar.set(Calendar.MILLISECOND, 0);

 mTimerReq = mTimerFeed.request(new TimerRequest("hourly_timer", calendar.getTime(), 3600L, false), this);
Repeating timer for date, period, and fixed rate: 
 // Set a timer for the top of the next hour and every hour after that.
 final Calendar calendar = Calendar.getInstance();

 calendar.add(Calendar.HOUR_OF_DAY, 1);
 calendar.set(Calendar.MINUTE, 0);
 calendar.set(Calendar.SECOND, 0);
 calendar.set(Calendar.MILLISECOND, 0);

 mTimerReq = mTimerFeed.request(new TimerRequest("hourly_timer", calendar.getTime(), 3600L, true), this);
Repeating timer for initial delay, period, and fixed delay: 
 // Set a timer to run five seconds into the future and every second after that.
 mTimerReq = mTimerFeed.request(new TimerRequest("five_seconds", 5000L, 1000L, false), this);
Repeating timer for initial delay, period, and fixed rate: 
 // Set a timer to run five seconds into the future and every second after that.
 mTimerReq = mTimerFeed.request(new TimerRequest("five_seconds", 5000L, 1000L, true), this);

Canceling ETimer requests

A ETimer request is canceled by calling mTimerReq.close(). A repeating timer request will continue until either the requestor closes the request or ETimer is stopped. A one-time request discontinues after the one reply is sent but may be canceled by the requestor before then.