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}