net.sf.eBusx.util.TimerRequest Maven / Gradle / Ivy
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later
// version.
//
// This library is distributed in the hope that it will be
// useful, but WITHOUT ANY WARRANTY; without even the implied
// warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
// PURPOSE. See the GNU Lesser General Public License for more
// details.
//
// You should have received a copy of the GNU Lesser General
// Public License along with this library; if not, write to the
//
// Free Software Foundation, Inc.,
// 59 Temple Place, Suite 330,
// Boston, MA
// 02111-1307 USA
//
// The Initial Developer of the Original Code is Charles W. Rapp.
// Portions created by Charles W. Rapp are
// Copyright 2012, 2013, 2015, 2016. Charles W. Rapp
// All Rights Reserved.
//
package net.sf.eBusx.util;
import java.io.Serializable;
import java.util.Calendar;
import java.util.Date;
import java.util.Formatter;
import net.sf.eBus.messages.EFieldInfo;
import net.sf.eBus.messages.EReplyInfo;
import net.sf.eBus.messages.ERequestMessage;
/**
* Send this request to schedule a timer task. Each timer request
* must have a unique name, that is, no two timer requests
* currently running must have the same name. Timer
* requests come in four kinds:
*
* -
* {@link #TimerRequest(String, Date)}:
* a one-shot timer scheduled to expire on a given date and
* time.
*
* -
* {@link #TimerRequest(String, long)}: a one-shot
* timer scheduled to expire after the specified millisecond
* delay.
*
* -
* {@link #TimerRequest(String, Date, long, boolean)}:
* a repeating timer which first expires on a given date and
* time and after that on a periodic millisecond rate. If the
* {@code fixedRate} parameter is {@code true}, then the
* timer is scheduled using
* {@link java.util.Timer#scheduleAtFixedRate(java.util.TimerTask, Date, long)}.
* Otherwise, the timer is scheduled using
* {@link java.util.Timer#schedule(java.util.TimerTask, Date, long)}.
*
* -
* {@link #TimerRequest(String, long, long, boolean)}:
* a repeating timer which first expires after a specified
* millisecond delay and then on a periodic millisecond rate.
* if {@code fixedRate} parameter is {@code true}, then the
* timer is scheduled using
* {@link java.util.Timer#scheduleAtFixedRate(java.util.TimerTask, Date, long)}.
* Otherwise, the timer is scheduled using
* {@link java.util.Timer#schedule(java.util.TimerTask, Date, long)}.
*
*
*
* @author Charles Rapp
*/
@EFieldInfo (fields={"timerName",
"time",
"delay",
"period",
"fixedRate"})
@EReplyInfo (replyMessageClasses = {TimerReply.class})
public final class TimerRequest
extends ERequestMessage
implements Serializable
{
//---------------------------------------------------------------
// Member methods.
//
//-----------------------------------------------------------
// Constructors.
//
/**
* Creates a new timer request instance with the given timer
* name and expiration time.
* @param timerName the timer name which serves as the
* request message subject.
* @param time expiration time.
* @exception IllegalArgumentException
* if {@code timerName} is either {@code null} or empty or if
* {@code time} is {@code null}.
* @see java.util.Timer#schedule(java.util.TimerTask, Date)
*/
public TimerRequest(final String timerName,
final Date time)
throws IllegalArgumentException
{
super (ETimer.TIMER_SUBJECT, System.currentTimeMillis());
if (timerName == null || timerName.isEmpty() == true)
{
throw (
new IllegalArgumentException(
"timerName is null or empty"));
}
else if (time == null)
{
throw (new IllegalArgumentException("null time"));
}
this.timerName = timerName;
this.time = new Date(time.getTime());
this.delay = 0L;
this.period = 0L;
this.fixedRate = false;
} // end of TimerRequest(String, Date)
/**
* Creates a new timer request instance with the given timer
* name, expiration time and repeating millisecond period.
* If {@code fixedRate} is {@code true}, then the timer is
* scheduled using a fixed-rate interval.
* @param timerName the timer name which serves as the
* request message subject.
* @param time expiration time.
* @param period repeating millisecond period.
* @param fixedRate if {@code true}, timer is run using
* fixed-rate execution.
* @throws IllegalArgumentException
* if {@code timerName} is either {@code null} or empty or if
* either {@code time} is {@code null} or {@code period} is
* ≤ zero.
* @see java.util.Timer#schedule(java.util.TimerTask, Date, long)
* @see java.util.Timer#scheduleAtFixedRate(java.util.TimerTask, Date, long)
*/
public TimerRequest(final String timerName,
final Date time,
final long period,
final boolean fixedRate)
throws IllegalArgumentException
{
super (ETimer.TIMER_SUBJECT, System.currentTimeMillis());
if (timerName == null || timerName.isEmpty() == true)
{
throw (
new IllegalArgumentException(
"timerName is null or empty"));
}
else if (time == null)
{
throw (new IllegalArgumentException("null time"));
}
else if (period < 1L)
{
throw (new IllegalArgumentException("period < 1"));
}
this.timerName = timerName;
this.time = new Date(time.getTime());
this.delay = 0L;
this.period = period;
this.fixedRate = fixedRate;
} // end of TimerRequest(String, Date, long, boolean)
/**
* Creates a new timer request instance with the given timer
* name and millisecond expiration delay.
* @param timerName the timer name which serves as the
* request message subject.
* @param delay the millisecond expiration delay.
* @throws IllegalArgumentException
* if {@code timerName} is either {@code null} or empty or if
* {@code delay} is ≤ zero.
* @see java.util.Timer#schedule(java.util.TimerTask, long)
*/
public TimerRequest(final String timerName,
final long delay)
throws IllegalArgumentException
{
super (ETimer.TIMER_SUBJECT, System.currentTimeMillis());
if (timerName == null || timerName.isEmpty() == true)
{
throw (
new IllegalArgumentException(
"timerName is null or empty"));
}
else if (delay < 1L)
{
throw (new IllegalArgumentException("delay < 1"));
}
this.timerName = timerName;
this.time = null;
this.delay = delay;
this.period = 0L;
this.fixedRate = false;
} // end fo TimerRequest(String, long)
/**
* Creates a new timer request instance with the given timer
* name, millisecond expiration delay and repeating
* millisecond period. If {@code fixedRate} is
* {@code true}, then the timer is scheduled using a
* fixed-rate interval.
* @param timerName the timer name which serves as the
* request message subject.
* @param delay the millisecond expiration delay.
* @param period repeating millisecond period.
* @param fixedRate if {@code true}, timer is run using
* fixed-rate execution.
* @throws IllegalArgumentException
* if {@code timerName} is either {@code null} or empty or if
* either {@code delay} or {@code period} is ≤ zero.
* @see java.util.Timer#schedule(java.util.TimerTask, long, long)
* @see java.util.Timer#scheduleAtFixedRate(java.util.TimerTask, long, long)
*/
public TimerRequest(final String timerName,
final long delay,
final long period,
final boolean fixedRate)
throws IllegalArgumentException
{
super (ETimer.TIMER_SUBJECT, System.currentTimeMillis());
if (timerName == null || timerName.isEmpty() == true)
{
throw (
new IllegalArgumentException(
"timerName is null or empty"));
}
else if (delay < 1L)
{
throw (new IllegalArgumentException("delay < 1"));
}
else if (period < 1L)
{
throw (new IllegalArgumentException("period < 1"));
}
this.timerName = timerName;
this.time = null;
this.delay = delay;
this.period = period;
this.fixedRate = fixedRate;
} // end of TimerRequest(String, long, long, boolean)
/**
* De-serialization constructor.
* @param subject the message subject.
* @param timestamp the message timestamp.
* @param timerName the user-assigned timer name.
* @param time the expiration time.
* @param delay the millisecond expiration delay.
* @param period the repeating millisecond period.
* @param fixedRate if {@code true}, timer is run using
* fixed-rate execution.
*/
public TimerRequest(final String subject,
final long timestamp,
final String timerName,
final Date time,
final long delay,
final long period,
final boolean fixedRate)
{
super (subject, timestamp);
this.timerName = timerName;
this.time = new Date(time.getTime());
this.delay = delay;
this.period = period;
this.fixedRate = fixedRate;
} // end of TimerRequest(...)
//
// end of Constructors.
//-----------------------------------------------------------
//-----------------------------------------------------------
// Object Method Overrides.
//
/**
* Returns a textual representation of this timer request
* message.
* @return the request message as text.
*/
@Override
public String toString()
{
final Formatter retval = new Formatter();
retval.format("%s%n timer expires ", super.toString());
// Is this a time-based expiration?
if (time != null)
{
// Yes.
final Calendar calendar = Calendar.getInstance();
final int year = calendar.get(Calendar.YEAR);
final int day = calendar.get(Calendar.DAY_OF_YEAR);
calendar.setTime(time);
// If the timer expires today, then output only the
// time.
if (calendar.get(Calendar.YEAR) == year &&
calendar.get(Calendar.DAY_OF_YEAR) == day)
{
retval.format("@ %1$tH:%1$tM:%1$tS.%1$tL", time);
}
// Output the date and time.
else
{
retval.format(
"on %1$tY-%1$tm-%1$td @ %1$tH:%1$tM:%1$tS.%1$tL",
time);
}
}
// No, this is a millisecond delay expiration.
else
{
retval.format("in %,d milliseconds", delay);
}
// Does this timer have a repeating period?
if (period > 0L)
{
// Yes.
retval.format(
", repeating every %,d milliseconds.",
period);
}
// No.
else
{
retval.format(".");
}
return (retval.toString());
} // end of toString()
//
// end of Object Method Overrides.
//-----------------------------------------------------------
//---------------------------------------------------------------
// Member data.
//
/**
* The requestor-assigned name for this timer request.
*/
public final String timerName;
/**
* If this timer is to expire at a given time, then set this
* value. Otherwise, set to {@code null} and specify a
* {@link #delay}.
*/
public final Date time;
/**
* If this timer is to expire after a millisecond delay, then
* set this value. Otherwise, set to zero and specify a
* {@link #time}.
*/
public final long delay;
/**
* If this timer is repeating, then set this millisecond
* period. Otherwise, set to zero for a one shot timer.
*/
public final long period;
/**
* If {@code true}, then repeating timers are run using fixed
* rate scheduling.
* @see java.util.Timer#scheduleAtFixedRate(java.util.TimerTask, Date, long)
* @see java.util.Timer#scheduleAtFixedRate(java.util.TimerTask, long, long)
*/
public final boolean fixedRate;
//-----------------------------------------------------------
// Constants.
//
/**
* Serialization version identifier.
*/
private static final long serialVersionUID = 0x060100L;
} // end of class TimerRequest
© 2015 - 2025 Weber Informatics LLC | Privacy Policy