Java Class Road Map

4-may-2000 / gmt

There are many classes in the token server, generally named with
Initial Capitals.  Here's how they relate.


There are some general-purpose utility classes, declared "public".
These classes could potentially used outside the tsvc package.
    Configuration reads a configuration file.
    Logger writes log messages, with dynamic selection.
    CircularBuffer maintains a list, discarding old items to make room for new.
    Timer provides a simple asynchronous alarm facility.
    Queue provides a simple buffer for message-passing synchronization.
    Util holds small utility methods.
    Pickle encodes and decodes data values for serial transmission.

Two public classes relate directly to the token server.
    Client provides token services to a Java program.
    A Token object represents a token handle in a client program.
    Broker is a command-line program that uses the Client.

The remaining files compose the token server system, with token services
built atop classes that provide communication and leader election.

A Council is (one member of) a group of communicating network processes.
    A Receiver provides a callback for each incoming message.
    An Observer passively watches and logs incoming messages.

A Leader communicates with other Leaders in the council to elect a leader.
    The Leader runs the "Candidate" state machine.
    A separate Elector instance runs the "Elector" state machine.

A Server performs the basic functions of a token server, including client
communication and token assignment.  A Director performs those token
functions delegated to the single elected leader.  A Certifier keeps
track of the Server's authority and responsibility, and the Vault is
the database of known tokens.

The Pickle class encodes and decodes values for serial transmission.
We do our own pickling (for easier interoperability with C) instead of
using Java serialization.

A Message is what gets sent, via UDP datagram, among Council members or
to/from clients.  The several subclasses hold data for specific purposes.
    A DataMessage (mainly for testing) holds an arbitrary array of bytes.
    A CouncilMessage handles Council administrative matters:
	An ElectMessage initiates or prolongs a leader election.
	A VoteMessage chooses a member for leadership.
	A LeadMessage proclaims sender's leadership and serves as a heartbeat.
	    A RosterMessage is a LeadMessage from the token Director.
    A ServerMessage reports the state of a Server to its Director.
    A TransferMessage sends tokens from a backup to a newly up primary server.
    See the PROTOCOL file for messages exchanged between server and client.

A Tok is the internal base class representing a token.  The public subclass
Token is used by the Client library.  A ServerToken is used in a Server.

Some classes are for testing.  For simplicity, some assume reliable, quick
responses, and may not run correctly the first time if class files must be
loaded over a slow network.
    t* classes run automated tests, with results compared to t*.std files.
    expt* classes are for manual experiments.
    Stress provides several options for stress-testing the system.

Most test files live in the "test" and "expt" directories, but there are
exceptions.  Broker and Stress, with formal, documented behavior, are
included with the tsvc package;  so are tMsgs and tToken, which reference
internal interfaces and so must be part of the package.