001    package javax.realtime;
002    
003    /** An <code>AsyncEvent</code> whose fire method is executed periodically
004     *  according to the given parameters. If a clock is given, calculation
005     *  of the period uses the increments of the clock. If an interval is
006     *  given or set the system guarantees that the fire method will execute
007     *  <code>interval</code> time units after the last execution or its
008     *  given start time as appropriate. If one of the
009     *  <code>HighResolutionTime</code> argument types is
010     *  <code>RationalTime</code> then the system guarantees that the fire
011     *  method will be executed exactly <code>frequence</code> times every
012     *  unit time by adjusting the interval between executions of
013     *  <code>fire()</code>. This is similar to a thread with
014     *  <code>PeriodicParameters</code> except that it is lighter weight.
015     *  If a <code>PeriodicTimer</code> is disabled, it still counts, and
016     *  if enabled at some later time, it will fire at its next scheduled
017     *  fire time.
018     */
019    public class PeriodicTimer extends Timer {
020    
021        private RelativeTime interval;
022    
023        /** Create an instance of <code>AsyncEvent</code> that executes its
024         *  fire method periodically.
025         *
026         *  @param start The time when the first interval begins.
027         *  @param interval The time between successive executions of the fire method.
028         *  @param handler The instance of <code>AsyncEventHandler</code> that will be
029         *                 scheduled each time the fire method is executed.
030         */
031        public PeriodicTimer(HighResolutionTime start,
032                             RelativeTime interval,
033                             AsyncEventHandler handler) {
034            super(start, Clock.getRealtimeClock(), handler);
035            this.interval = interval;
036        }
037    
038        /** Create an instance of <code>AsyncEvent</code> that executes its
039         *  fire method periodically.
040         *
041         *  @param start The time when the first interval begins.
042         *  @param interval The time between successive executions of the fire method.
043         *  @param clock The clock whose increments are used to calculate the interval.
044         *  @param handler The instance of <code>AsyncEventhandler</code> that will be
045         *                 scheduled each time the fire method is executed.
046         */
047        public PeriodicTimer(HighResolutionTime start,
048                             RelativeTime interval, Clock clock,
049                             AsyncEventHandler handler) {
050            super(start, clock, handler);
051            this.interval = interval;
052        }
053    
054        /** Create a <code>ReleaseParameters</code> object with the next
055         *  fire time as the start time and the interval of <code>this</code>
056         *  as the period.
057         *
058         *  @return An instance of <code>ReleaseParameters</code> object.
059         */
060        public ReleaseParameters createReleaseParameters() {
061            return new PeriodicParameters(getFireTime(), interval, null, null,
062                                          handler, null);
063        }
064    
065        /** Causes the instance of the superclass <code>AsyncEvent</code>
066         *  to occur now.
067         */
068        public void fire() {
069            handler.run();
070        }
071    
072        /** Gets the absolute time <code>this</code> will next fire
073         *
074         *  @return The next fire time as an absolute time.
075         */
076        public AbsoluteTime getFireTime() {
077            return super.getFireTime();
078        }
079    
080        /** Gets the interval of <code>this</code>.
081         *
082         *  @return The value in <code>interval</code>.
083         */
084        public RelativeTime getInterval() {
085            return interval;
086        }
087    
088        /** Sets the <code>interval</code> value of <code>this</code>.
089         *
090         *  @param interval The value to which <code>interval</code> will be set.
091         */
092        public void setInterval(RelativeTime interval) {
093            this.interval = interval;
094        }
095    }