001package jmri;
002
003import java.util.Date;
004
005/**
006 * ClockControl defines an interface for control of hardware Fast Clocks
007 * <p>
008 * Each hardware system that has a hardware Fast Clock implementation must
009 * supply a module that implements this interface. Each ClockControl module must
010 * register itself with the Instance Manager at start up.
011 * <p>
012 * Parameters for fast clocks are set up generically in the Fast Clock Setup,
013 * accessed via the JMRI Tools menu. These parameters are saved in the
014 * configuration file generically, so no special configxml module is needed for
015 * storing parameters.
016 * <p>
017 * Hardware ClockControl modules should extend DefaultClockControl, which
018 * supplies default implementations of methods required by this interface that
019 * specific hardware implementations may not need.
020 * <p>
021 * All Clock Control modules communicate with the internal clock and the master
022 * JMRI timebase, using methods of the Timebase interface.
023 * <hr>
024 * This file is part of JMRI.
025 * <p>
026 * JMRI is free software; you can redistribute it and/or modify it under the
027 * terms of version 2 of the GNU General Public License as published by the Free
028 * Software Foundation. See the "COPYING" file for a copy of this license.
029 * <p>
030 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
031 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
032 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
033 *
034 * @author Dave Duchamp Copyright (C) 2007
035 */
036public interface ClockControl {
037
038    /**
039     * Get status of the fast clock.
040     * Potentially unused?
041     *
042     * @return the status
043     */
044    int getStatus();
045
046    /**
047     * Get name of hardware clock Note: If there is no hardware clock,
048     * DefaultClockControl returns null, so all hardware clocks must override
049     * this method.
050     *
051     * @return the name
052     */
053    String getHardwareClockName();
054
055    /**
056     * Returns true if hardware clock accuracy can be corrected using the
057     * computer clock.
058     *
059     * @return true if correctable; false otherwise
060     */
061    boolean canCorrectHardwareClock();
062    
063    /**
064     * Returns 'true' if hardware clock can be set to 12 or 24 hour display from
065     * JMRI software.
066     *
067     * @return true if settable; false otherwise
068     */
069    boolean canSet12Or24HourClock();
070
071    /**
072     * Returns true if hardware clock requires an integer rate.
073     *
074     * @return true if integer rates only; false otherwise
075     */
076    boolean requiresIntegerRate();
077
078    /**
079     * Set the rate of the Fast Clock.
080     * <p>
081     * The rate is a number that
082     * multiplies the wall clock time For example, a rate of 4 specifies that
083     * the fast clock runs 4 times faster than the wall clock.
084     *
085     * @param newRate the new rate
086     */
087    void setRate(double newRate);
088
089    /**
090     * Get the rate of the Fast Clock.
091     * <p>
092     * The rate is a number that multiplies the wall clock. 
093     * For example, a rate of 4 specifies that the
094     * fast clock runs 4 times faster than the wall clock.
095     * 
096     * @return Fast Clock rate.
097     */
098    double getRate();
099
100    /**
101     * Set the fast clock time.
102     *
103     * @param now the new time
104     */
105    void setTime(Date now);
106
107    /**
108     * Get the fast clock time.
109     *
110     * @return current time.
111     */
112    Date getTime();
113
114    /**
115     * Start hardware fast clock Some hardware fast clocks continue to
116     * run indefinitely. This is provided for the case where the hardware clock
117     * can be stopped and started.
118     *
119     * @param now the starting time
120     */
121    void startHardwareClock(Date now);
122
123    /**
124     * Stop hardware fast clock.
125     * This is provided for the case where the hardware clock
126     * can be stopped and started.
127     *
128     */
129    void stopHardwareClock();
130
131    /**
132     * Initialize the hardware fast clock Note: When the hardware clock control
133     * receives this, it should initialize those clock settings that are
134     * available on the hardware clock. This method is used when the fast clock
135     * is started, and when time source, synchronize, or correct options are
136     * changed. If rate is 0.0, the hardware clock should be initialized
137     * "stopped", and the current rate saved for when the clock is restarted. If
138     * getTime is "true" the time from the hardware clock should be used in
139     * place of the supplied time if possible.
140     *
141     * @param rate    the rate
142     * @param now     the time
143     * @param getTime true if hardware clock should be used; false otherwise
144     */
145    void initializeHardwareClock(double rate, Date now, boolean getTime);
146
147}