/*
   XBN Java:  Generically useful, non-GUI Java code.
   http://sourceforge.net/projects/xbnjava

   Copyright (C) 1997-2003, Jeff Epstein
   All rights reserved.

   Modifications: No

   Redistribution in binary form, with or without modifications, are permitted provided that the following conditions are met:

      * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
      * If modifications are made to source code then this license should indicate that fact in the "Modifications" section above.
      * Neither the author, nor the contributors may be used to endorse or promote products derived from this software without specific prior written permission.

   THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

   [NOTE:  This license contains NO advertising clause.]
 */
package xbn.util;
   import xbn.XBNObject;

   import java.util.Date;

/**
   <P>For keeping track of things that have a delay, or expire within a given number of units.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/util/TimerUnits.java">TimerUnits.java</A>. &nbsp;<B>Example code</B> &nbsp;See the example code for <A HREF="~JD~tmrs~EJD~">TimerSeconds</A>.</I></CODE></P>

   @version  0.9b
   @author  Jeff Epstein, <A HREF="http://sourceforge.net/projects/xbnjava">http://sourceforge.net/projects/xbnjava</A>.
 **/
public class TimerUnits extends XBNObject  {
   private UtilDate uDate = new UtilDate();

   private Date dStarted = null;
   private int iUnitsToExpire = -1;
   private long lMillsMultiplier = -1;
   private boolean bCrashIfStartStart = false;
   private boolean bCrashIfStopStop = false;

   /**
      <P>Create a TimerUnits that does not expire.</P>

      <P>Equal to <CODE><A HREF="~JD~tmru(l,i)~EJD~">TimerUnits</A>(0, -1)</CODE></P>
    **/
   public TimerUnits()  {
      this(0, -1);
   }

   /**
      <P>Create a TimerUnits.</P>

      <P>Equal to <CODE><A HREF="~JD~tmru(l,i,b)~EJD~">TimerUnits</A>(l_millsMultiplier, i_unitsToExpire, false)</CODE></P>
    **/
   public TimerUnits(long l_millsMultiplier, int i_unitsToExpire)  {
      this(l_millsMultiplier, i_unitsToExpire, false);
   }

   /**
      <P>Create a TimerUnits.</P>

      <P>Equal to <CODE><A HREF="~JD~tmru(l,i,b,b)~EJD~">TimerUnits</A>(l_millsMultiplier, i_unitsToExpire, b_crashIfMidStartOrStop, b_crashIfMidStartOrStop)</CODE></P>
    **/
   public TimerUnits(long l_millsMultiplier, int i_unitsToExpire, boolean b_crashIfMidStartOrStop)  {
      this(l_millsMultiplier, i_unitsToExpire, b_crashIfMidStartOrStop, b_crashIfMidStartOrStop);
   }

   /**
      <P>Create a TimerUnits.</P>

      @param  l_millsMultiplier  This number times i_unitsToExpire is the number of milleseconds until expiration.  See <A HREF="#getMillsMultiplier()">getMillsMultiplier</A>.
      @param  i_unitsToExpire  The number of units for the delay/until expiration.  If -1, then there is no delay (expiration never occurs).  Otherwise, must be greater than or equal to one.  See <A HREF="#getUnitsToExpire()">getSeconds</A>.
      @param  b_crashIfStartStart  Is it legal to start the timer when already started?  See <A HREF="#doCrashIfStartStart()">doCrashIfStartStart</A>.
      @param  b_crashIfStopStop  Is it legal to stop the timer when already stopped?  See <A HREF="#doCrashIfStopStop()">doCrashIfStopStop</A>.
    **/
   public TimerUnits(long l_millsMultiplier, int i_unitsToExpire, boolean b_crashIfStartStart, boolean b_crashIfStopStop)  {
      if(i_unitsToExpire != -1  &&  i_unitsToExpire < 1)  {
         throwAX("constructor:  i_unitsToExpire (" + i_unitsToExpire + ") may equal -1--meaning no delay, or must be greater than zero.");
      }

      lMillsMultiplier = l_millsMultiplier;
      iUnitsToExpire = i_unitsToExpire;
      bCrashIfStartStart = b_crashIfStartStart;
      bCrashIfStopStop = b_crashIfStopStop;
      dStarted = null;
   }

   /**
      <P>Start the timer.  <A HREF="#getUnitsToExpire()">getSeconds</A>, from the moment when this function is called, is when <A HREF="#hasExpired()">isReady</A> will return true.</P>

      <P>See <A HREF="#stop()">stop</A>.</P>

      @exception  AssertException  If <A HREF="#isStarted()">already started</A> and <A HREF="#doCrashIfStartStart()">doCrashIfStartStart</A> equals true.
    **/
   public void start()  {
      if(doCrashIfStartStart()  &&  isStarted())  {
         throwAX("start:  Both doCrashIfStartStart() and isStarted() equal true.  Already started.");
      }

      if(!doesExpire())  {
         return;
      }

      dStarted = new Date();
   }

   /**
      <P>Stop the timer.</P>

      <P>See <A HREF="#start()">start</A>.</P>

      @exception  AssertException  If <A HREF="#isStarted()">already stopped</A> and <A HREF="#doCrashIfStopStop()">doCrashIfStopStop</A> equals true.
    **/
   public void stop()  {
      if(doCrashIfStopStop()  &&  isStopped())  {
         throwAX("end:  Both doCrashIfStopStop() and isStopped() equal true.  Already stopped.");
      }

      if(!doesExpire())  {
         return;
      }

      dStarted = null;
   }

   /**
      <P>When the timer is already started, is it legal to start it again?</P>

      @return  <B>true</B>  If it is only legal to <A HREF="#start()">start</A> the timer when it <A HREF="#isStopped()">is stopped</A>.
      <BR><B>false</B>  If it is legal to start the timer at any time...even when it is already started.
    **/
   public boolean doCrashIfStartStart()  {
      return bCrashIfStartStart;
   }

   /**
      <P>When the timer is already stopped, is it legal to stop it again?</P>

      @return  <B>true</B>  If it is only legal to <A HREF="#stop()">stop</A> the timer when it <A HREF="#isStarted()">is started</A>.
      <BR><B>false</B>  If it is legal to stop the timer at any time...even when it is already stopped.
    **/
   public boolean doCrashIfStopStop()  {
      return bCrashIfStopStop;
   }

   /**
      <P>Get the total number of units until expiration.  This number, multiplied by <A HREF="#getMillsMultiplier()">getMillsMultiplier</A>, is the number of milliseconds until <A HREF="#hasExpired()">expiration</A>.</P>

      <P>This number represents the units from the moment this TimerUnits is <a href="#start()">started</A>, to the moment it expires.  It does not change during the life of this object.</P>
    **/
   public int getUnitsToExpire()  {
      return iUnitsToExpire;
   }

   /**
      <P>Get the millesecond multiplier for this TimerUnits.  This number, multiplied by <A HREF="#getUnitsToExpire()">getUnitsToExpire</A>, is the number of milliseconds until <A HREF="#hasExpired()">expiration</A>.</P>
    **/
   public long getMillsMultiplier()  {
      return lMillsMultiplier;
   }

   /**
      <P>Get the number of milleseconds until expiration.</P>

      @return  <CODE>(<A HREF="#getUnitsToExpire()">getUnitsToExpire</A>() * <A HREF="#getMillsMultiplier()">getMillsMultiplier</A>())</CODE>
    **/
   public long getMillsToExpire()  {
      return (getUnitsToExpire() * getMillsMultiplier());
   }


   /**
      <P>Does this timer ever expire?</P>

      @return  <CODE>(<A HREF="#getUnitsToExpire()">getUnitsToExpire</A>() != -1)</CODE>
    **/
   public boolean doesExpire()  {
      return (getUnitsToExpire() != -1);
   }

   /**
      <P>Has the timer been started?</P>

      @return  <CODE>(<A HREF="#getDateStarted()">getDateStarted</A>() != null)</CODE>
    **/
   public boolean isStarted()  {
      return (getDateStarted() != null);
   }

   /**
      <P>Has the timer been stopped?</P>

      @return  <CODE>!<A HREF="#isStarted()">isStarted</A>()</CODE>
    **/
   public boolean isStopped()  {
      return !isStarted();
   }

   /**
      <P>Get the date representing the moment the timer was started.</P>

      @return  A <B>Date</B>  If the timer was started.
      <BR><B>null</B>  If the timer was not started.
    **/
   public Date getDateStarted()  {
      return dStarted;
   }

   /**
      <P>Have the number of units to expiration gone a went?</P>

      <P>When this function returns true, the timer is <A HREF="#stop()">stopped</A>.</P>

      @return  <B>true</B>  If the timer <A HREF="#isStopped()">has not yet been started</A>.
      <BR>Otherwise return <CODE>[<A HREF="UtilDate.html">UtilDate</A>].<A HREF="~JD~utild#getNowMinusYUnits(jud,l)~EJD~">getNowMinusYUnits</A>(<A HREF="#getDateStarted()">getDateStarted</A>(), <A HREF="#getMillsMultiplier()">getMillsMultiplier</A>()) &gt;= <A HREF="#getUnitsToExpire()">getUnitsToExpire</A>())</CODE>
    **/
   public synchronized boolean hasExpired()  {
      if(isStopped())  {
         return true;
      }

      boolean bReady = (uDate.getNowMinusYUnits(getDateStarted(), getMillsMultiplier()) >= getUnitsToExpire());

      if(bReady)  {
         stop();
      }

      return bReady;
   }

   /**
      <P>Get some information about this TimerUnits.</P>
    **/
   public String toString()  {
      return this.getClass().getName() + ":  doCrashIfStartStart()=" + doCrashIfStartStart() + ", getMillsMultiplier()=" + getMillsMultiplier() + ", getUnitsToExpire()=" + getUnitsToExpire() + ", isStarted()=" + isStarted()  + ", getDateStarted()=" + getDateStarted() + sES;
   }
}