net.sf.eBusx.util.package-info Maven / Gradle / Ivy
//
// Copyright 2012, 2016 Charles W. Rapp
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
/**
* This package provides an eBus interface for accessing
* {@link java.util.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 {@link java.util.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 {@link net.sf.eBusx.util.TimerRequest timer request}
* allows for all six {@link java.util.Timer} scheduling methods
* to be accessed:
*
* -
* {@link java.util.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.
*
* -
* {@link java.util.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.
*
* -
* {@link java.util.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
* {@link net.sf.eBus.client.ERequestFeed.ERequest#close() canceled}.
*
* -
* {@link java.util.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
* {@link net.sf.eBus.client.ERequestFeed.ERequest#close() canceled}.
*
* -
* {@link java.util.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
* {@link net.sf.eBus.client.ERequestFeed.ERequest#close() canceled}.
*
* -
* {@link java.util.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
* {@link net.sf.eBus.client.ERequestFeed.ERequest#close() 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 {@link net.sf.eBusx.util.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 {@code true}. Otherwise,
* a repeating timer will continue until the timer request is
* {@link net.sf.eBus.client.ERequestFeed.ERequest#close() canceled}.
*
* The eBus timer service is only available to
* {@link net.sf.eBus.client.ERequestor} objects in the same JVM.
* An object cannot remotely access an eBus timer service.
*
Starting and Stopping {@code ETimer}
*
* {@code ETimer} must be running before any timer requests may
* be placed. {@code ETimer} is started by calling
* {@code ETimer.startETimer();}. {@code ETimer} is stopped by
* calling {@code ETimer.stopETimer();}
*
* Subscribing to {@code ETimer}
*
* Before timer requests may be placed, the {@code ERequestor}
* must first subscribe to {@code ETimer}. The example assumes
* that {@code this} object implements the
* {@link net.sf.eBus.client.ERequestor} interface and
* {@code mTimerFeed} and {@code mTimerReq} are class data
* members.
*
* ERequestFeed mTimerFeed;
* ERequestFeed.ERequest mTimerReq;
*
* mTimerFeed = ERequestFeed.open(this, ETimer.TIMER_KEY, EFeed.FeedScope.LOCAL_ONLY);
* mTimerFeed.subscribe();
*
* Placing {@code 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 {@code ETimer} requests
*
* A {@code ETimer} request is canceled by calling
* {@code mTimerReq.close()}. A repeating timer request will
* continue until either the requestor closes the request or
* {@code ETimer} is stopped. A one-time request discontinues
* after the one reply is sent but may be canceled by the
* requestor before then.
*
*/
package net.sf.eBusx.util;