# TickTock - A JavaTM Application for Time Synchronization

by William Giel

Version 1.04b, 4 March 1996

The compiled classes comprising the TickTock program, source code, a program icon and this HTML file can be downloaded as ticktock.zip The Java Interpreter is contained in Sun Microsystem's Java Developers Kit (JDK), available in versions for a variety of operating systems. You'll also need a version of zip that supports long filenames.

## Abstract

TickTock is a Java application that permits synchronizing the user's computer clock with one of the master clock time servers at the U.S. Naval Observatory (USNO.) By using USNO's special Port 13 Daytime time service, TickTock can acchieve accuracy to one second. TickTock takes its name from these two USNO computers, named appropriately, "tick" and "tock"

It is certainly possible to acchieve higher accuracy over the net, using the more sophisticated SNTP (RFC 1769) and NTP (RFC 1305) protocols. However, for most purposes, TickTock provides sufficient accuracy. In fact, most PC clocks are surprisingly inaccurate, and lose or gain several seconds each day.

Notwithstanding the above, the next version of TickTock should probably offer the option of using SNTP. Until that time, users requiring time accuracy to fractions of a second will have to resort to other software packages that meet their specific requirements. A selection of precise time synchronization software for a variety of platforms can be accessed from the USNO website.

## What's New in Version 1.04?

Some very narrow minded programmers assume that all OS commands are like those in DOS. The way version 1.03 was set up, it would not be possible to execute time/date commands on a Unix box. Thanks to Gerry Gleason <gerry@inter-direct.com> for providing information and code to correct this situation.

## Installation

TickTock consists of the following components:

ttConst.class | inputBox.class
Julian.class | Scroller.class
timeThread.class | sysCommandDialog.class
SocketThread.class | Configuration.class
ticktock.class | Format.class

These files can be placed in any directory that you want to create. However, be sure that it is named in the CLASSPATH environment variable. If you do not want to specify a CLASSPATH variable at all, then you must run TickTock from the directory that contains all the classes. Apparently, CLASSPATH is all or nothing as far as the Java interpreter is concerned. If Java finds it, it only looks where it is told for the classes. If it does not find it, then it looks in the current directory.

## Usage

Since TickTock is an application, as opposed to an applet, it is used in conjunction with the Java Interpreter. Invoke TickTock with the command

`java ticktock`

either at the system's command prompt, with a batch file, or by any other appropriate mechanism, such as Win95's Run… menu item. When invoked, TickTock's main program window will appear.

TickTock's startup screen.

TickTock starts off in an idle state, displaying the copyright notice, the current system time and date, and the local time zone offset. It also displays the names of the two USNO computers that offer the special type of time service that is used for synchronizing.

Select one of the two servers, either "tick" or "tock", and press the "Connect" button.

TickTock will attempt to communicate with the selected time server. Once a connection is established, TickTock will remain connected and attempt to make eight time comparisons.

After receiving these comparisons, TickTock will kill the socket, and then calculate the mean correction from the difference between the local system's time and that from USNO for each sample received (taking time zone offset into consideration.) Provided a full set of eight time comparisons are available, TickTock will also calculate the data's standard deviation, and if necessary, reprocess the mean, this time snooping outlying data based on a rejection limit of three standard deviations.

The value of the correction,in seconds, and the current running time based on USNO will be displayed. You may press "Connect" another time , and possibly see a one second variation in the correction. This is due to the inherent inaccuracies of this method.

TickTock after a connection is established.

When you are ready to correct your system's time, press the "Set Time" button. In order to remain platform independent, TickTock presents a dialog showing the two system commands that it will use to update the time.

TickTock prompting for system command templates.

The first time that you run TickTock, the default command syntax is suitable for DOS or Win95. You should enter your system's specific commands if different. Note that you must specify the complete path and command file name. For DOS/Win95, the /C switch tells the system to return from the shell immediately after running the TIME or DATE commands. When specifying the time and date formats, you must use "hh", "mm" and "ss" where you want the hours, minutes and seconds to be inserted. Likewise, in the date command, you must use "MM", "DD" and "YY" where the date components will be placed.

Where two separate commands are issued for TIME and DATE, the time command must be first.

For Unix systems, a single command is given to set both time and date. In this case, delete the lower text field, and enter the complete Unix command in the upper. For example

        /bin/date MMDDhhmmYY.ss

Note that the same characters (case sensitive) are used for days, months, hours, etc.

Once you are satisfied that the command template(s) are correct, press OK, and TickTock will adjust the time of your system. TickTock will also save your command template(s) to a small configuration file, so that the next time you use it, you will not have to edit the command field(s).

## Planned Improvements

- Modal system command dialog (Java bug.)
- Remember window location when next used (Java bug.)
- Attempt to implement SNTP protocol, permitting greater flexibility in selecting a time server, with increased accuracy.

## How TickTock works.

TickTock is essentially a simple telnet client that opens a socket on Port 13 to one of the abovementioned USNO time servers. Since the output of the server is well documented, it is a straightforward task to parse the incoming data to obtain the necessary values needed to correct the local clock. The data format that is received consists of an identification line, the estimated network delay, and a header for the actual time data that follows. The time data consists of a modified julian day number(see RFC 1305,) a day of year number, and Coordinated Universal Time (GMT) in HHMMSS format. Immediately following this is an asterisk character, which is the "hack" for the time value just received. Normally, the time string and hack repeat until the connection is terminated. You can manually telnet to one of the servers to see the actual ascii output.

TickTock is designed to receive eight consecutive time signals, and calculate the correction based on the mean of eight comparisons to the local clock.

There are occasions when eight comparisons are not possible. When the USNO server is contacted, it pings the client to estimate the network delay and adjusts the time that it transmits accordingly. If the delay is excessive, the server will only transmit one time message. TickTock will recognize this situation and will not attempt to calculate a mean, since only one value is obtained.

If TickTock successfully receives eight time messages, it computes the standard deviation of the computed mean correction. If this exceeds 0.5 seconds, TickTock will re-examine the data and reject any outliers based on a standard rejection limit of three standard deviations.

Since Java does not provide a method to set the time on the system clock, there are two possible ways to accomplish this. The first could be by invoking a native function coded in C or C++. However, this would totally defeat the platform-independent aspect of TickTock. The other choice is to use the Runtime.exec() method to issue system commands to set the time and date. By permiting a user to customize the commands, portability is maintained, at the expense of elegance. TickTock will remember the customized commands the next time it is used.

## Why not a TickTock Applet?

TickTock does two things that applets are currently prohibited from doing (under Netscape.) First, it contacts a server other than the codebase server, which throws a security exception as an applet. Attempting to execute another program (the command shell) is another security violation. TickTock cannot exist as an applet, although it would be a great one.

But TickTock as an application is interesting. With the majority of attention going to applets, its not to difficult to lose sight of the fact that there is Java without Netscape. Hopefully, TickTock will give some indication of the potential of Java applications. Keep in mind that TickTock was written in a few evenings of casual programming, and is not a large application!

## Program Structure

TickTock's source is contained in several code units or source files. These consist of the following:

ticktock.java - This is the main code unit, and contains the class ticktock. Within this class are the init() method, which sets up the user interface using GridBagLayout and starts the system time thread (described below) , a main() method, which instantiates the class and gets things going in an application, as well as an action() method to handle buttons, and a handleEvent() method for the WINDOW_DESTROY event.

It is also the location of the code for a sysCommandDialog class, which is a subclass of the abstract class inputBox (described below.) sysCommandDialog creates a pop-up dialog that lets the user modify the system command text used to change the time and date.

ttConst.java - This unit contains the public interface ttConst, to define literal strings and other constants used throughout the program. This type of structure is a handy technique for creating the functional equivalent of a stringtable resource in windows programming. The primary advantages of this technique are that it helps keep things under control from the standpoint of organization, and uses memory efficiently. A secondary advantage of such a package is that it facilitates internationalization, or translation to a language besides English. After all, it is a World Wide Web.

timeThread.java - The timeThread class provides methods for displaying running time/date within a defined textArea, Two initiallizers are provided. One is for the simple case of displaying uncorrected system time, optionally converted to Greenwich Mean Time (GMT), and the second accepts an additional argument, the correction (in seconds) which it applies to the system time to display a corrected time.

SocketThread.java - A socketThread object is used to establish a connection with the USNO.

In the early stage of developing the socket code, it was initially placed inline, within TickTock's action handler (an apparent regression to procedural programming.) While this seemed to work under good conditions, it created a serious problem if the connection stalled, because TickTock's action handler would stall with it. The result would be a dead application that would not respond to any button presses.

The correct implementation for the socket connection is to run it as a separate thread, which will not hang the entire program if it stalls. This way, the Reset button can be used to manually stop the thread, or the Quit button used to terminate the program.

The socketThread also contains code to compute the correction required to synchronize the local clock with the server, and provides methods to permit the main program to query its status, and determine if a correction has been calculated.

One other addition was made to stopSocket, and that was the stopSocket() method. Simply stopping the socketThread (such as by pressing Reset) might not properly kill the socket if it is open. Since the objects inherited stop() method is final, and cannot be overrriden, the stopSocket method was added. This method first checks for an open socket and closes it before invoking the super.stop() method.

Julian.java - The Julian class provides methods to convert back and forth between the conventional Gregorian calendar and the Julian Calendar. The formulas provided are adequate for the purposes of this program, and probably most others that are involved with calendar conversions. However, since they will not handle negative julian day numbers, they are inappropriate for certain calendar calculations, such as those that might be involved in historical astronomy.

Julian.java is also a good place to provide formatting methods to convert java.util.Date objects, and julian or modified julian day numbers to standard date formats.

In retrospect, as I review the program, it may have better to create a JulianDate class as an extension of java.util.Date. The Julian class will suffice for the time being, but I will explore this possibility for the next version of TickTock.

Scroller.java - The Scroller class is a simple subclass of java.awt.TextArea. The only additional functionality it provides is a Scroller.newLine() method, which appends a CRLF to the text currently contained in the TextArea component.

Format.java - The Format class provides a method to display a string representation of a double precision number to a specified level of decimal places, providing funtionality akin to the sprintf(char *string,%.3f,...) statement in C. At present, there is considerable room for expansion and refinement of this class. However, in its present form it is sufficient for our purposes in TickTock.

inputBox.java - The abstract class inputBox.class is a start at creating a OK-Cancelgeneric dialog box in which the user can provide one or two lines of input. The class itself cannot be instantiated, but must be extended to include an application specific action handler.

TickTock's sysCommandDialog class extends inputBox to request the system commands to be used to correct the time, and actually executes the system commands performs the correction from within the action handler. As with the Format class, inputBox is at an early stage of development, and should at least be refined to size itself based on the dimensions of the TextArea component(s) and prompt message,

Configuration.java - Configuration.java creates Configuration.class, which contains TickTock's default parameters. Presently, the only defaults saved are the system command templates for setting time and date. Hopefully, this class can be extended in the future to remember the origin of the TickTock window . Presently, a known Java bug (java.awt.Component.location() method always returns 0,0 for the main windows origin) prevents this from being done.

TickTock Software Copyright © 1996 by William Giel. All rights reserved.

Compiled software and source code is provided for non-commercial or educational use only. TickTock may be freely distributed for these purposes provided that it is unaltered and the original documentation accompany the software.

HTML coding validated with Weblint 1.013

This document was last updated on 4 March 1996.
http://www.nai.net/~rvdi/home.htm