<?xml version='1.0'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://docbook.org/xml/4.2/docbookx.dtd"
               [
               <!ENTITY copyright SYSTEM "copyright.xml">
               ]>

<chapter label="Flashing Clocks" id ="18">
  <title>
    Example: Flashing Clocks
  </title>
  

  <tocchap>
    <tocentry>
      
    </tocentry>
    <toclevel1>
      <tocentry linkend="Introduction">
	<ulink url="#Introduction">Introduction</ulink>
      </tocentry>
    </toclevel1>
    <toclevel1>
      <tocentry>
	<ulink url="#TickerTimer">TickerTimer</ulink>
      </tocentry>
    </toclevel1>
    <toclevel1>
      <tocentry>
	<ulink url="#ComputerTimer">ComputerTimer</ulink>
      </tocentry>
    </toclevel1>
    <toclevel1>
      <tocentry>
	<ulink url="#TickerTimer Driver">TickerTimer Driver</ulink>
      </tocentry>
    </toclevel1>
    <toclevel1>
      <tocentry>
	<ulink url="#ComputerTimer Driver">ComputerTimer Driver</ulink>
      </tocentry>
    </toclevel1>
    <toclevel1>
      <tocentry>
	<ulink url="#Runtime Behaviour">Runtime Behaviour</ulink>
      </tocentry>
    </toclevel1>
  </tocchap>
 


  <abstract>
    <para>
      
    </para>
  </abstract>
  
  <sect1>
    <title id="Introduction">
      Introduction
    </title>
    
    <para>
      One of the early promises of Jini was that it would find its way into all sorts of
      devices which could advertise their presence. However, Jini does not run on the 
      <emphasis>really</emphasis> small Java virtual machines such as the KVM.
      But <emphasis>if</emphasis> it could, how would it be used? 
    </para>

    <para>
      Most people have a number of electronic clocks in their house: alarm clocks, a clock
      on the oven, another on the microwave, and so on. When the electricity resumes after
      a power failure, they all start flashing, and you have to go round one after another
      setting them manually. Wouldn't it be nice if you only had to reset one (or if it
      got a value from a time server somewhere) and all the others reset themselves from it.
    </para>

    <para>
      In this chapter we look at this "flashing clocks" problem from a Jini viewpoint,
      to see what a Jini solution would look like. 
      This example uses <classname>JoinManager</classname> and
      <classname>ServiceDiscoveryManager</classname> to advertise and discover services.
    </para>

    <para>
      On my site
      <ulink url="http://jan.newmarch.name/internetdevices/upnp/upnp-more-programming.html">
	http://jan.newmarch.name/internetdevices/upnp/upnp-more-programming.html
      </ulink>
      is an alternative solution using UPnP - a middleware system that is making more grounds
      in the area of small devices than Jini is, probably due to 
      lighter resource requirements and an active coordinating body.
    </para>

  </sect1>
  
  <sect1>
    <title id="Timer">
      Timer
    </title>
     
    <para>
      Each clock is available as a service which we call a <code>Ticker</code>.
      A ticker has methods to get and set the time, and in addition it knows if it has
      a valid time or if it has an invalid time (and so should be shown flashing).
      A ticker can have its time set: when it does, it becomes valid, so that a display
      can stop flashing.
    </para>

    <para>
      The interface for a ticker is
      <programlisting>
	<?program "src/clock/service/Timer.java"?>
      </programlisting>
    </para>
  </sect1>
  
  <sect1>
    <title id="TickerTimer">
      TickerTimer
    </title>
     
    <para>
      We shall give two implementations of this service: the first is the "dumb" one:
      when it starts it guesses at a start time and enters an invalid state. It uses
      a separate thread to keep imcreasing its time every second (approximately). When
      its time is set, it becomes valid, but will probably drift from the correct time
      due to its use of sleep to keep changing the time.
    </para>

    <para>
      The dumb timer is
      <programlisting>
	<?program "src/clock/service/TickerTimer.java"?>
      </programlisting>
    </para>
    
  </sect1>
  
  <sect1>
    <title id="ComputerTimer">
      ComputerTimer
    </title>
     
    <para>
      This timer uses the computer's internal clock to always return the correct time on
      request. It is always valid.
      <programlisting>
	<?program "src/clock/service/ComputerTimer.java"?>
      </programlisting>
    </para>
    
  </sect1>
  
  <sect1>
    <title id="ClockFrame">
      ClockFrame
    </title>
        
    <para>
      To make this more visual, we can put the timers into a Swing frame and watch them ticking
      away. The following code is based on that of Satoshi Konno for UPnP
    </para>

    <para>
      A clock pane is
      <programlisting>
	<?program "src/clock/clock/ClockPane.java"?>
      </programlisting>
    </para>
 
    <para>
      A clock frame is
      <programlisting>
	<?program "src/clock/clock/ClockFrame.java"?>
      </programlisting>
    </para>
 
  </sect1>
  
  <sect1>
    <title id="TickerTimer Driver">
      TickerTimer Driver
    </title>
     
    <para>
      A driver for the ticker timer in the frame above is
      
      <programlisting>
	<?program "src/clock/clock/TickerClock.java"?>
      </programlisting>
      This can be run by 
      <programlisting>
java clock.clock.TickerClock "Ticking Clock"
      </programlisting>
    </para>
    
  </sect1>
  
  <sect1>
    <title id="ComputerTimer Driver">
      ComputerTimer Driver
    </title>
 
    <para>
      A driver for the computer timer in the frame above is
      <programlisting>
	<?program "src/clock/clock/ComputerClock.java"?>
      </programlisting>
      This can be run by 
      <programlisting>
java clock.clock.ComputerClock "Computer Clock"
      </programlisting>
    </para>
     
    <para>
      Two (or more) clocks can be started. If ticking clocks ae started then they
      will all be flashing. Once a computer clock is started though, the clocks
      will discover each other. Either the computer clock will discover ticking
      clocks and reset them, or the tickong clocks will discover the computer
      clock and reset themselves. I don't know which occurs and it doesn't
      matter.
    </para>

    <para>
      When running, the two clocks look like
      <graphic fileref="images/clocks.png" align="center"></graphic>
    </para>
    
  </sect1>
  
  <sect1>
    <title id="ClockDevice">
      ClockDevice
    </title>
     
    <para>
      The final part is to advertise each timer as a Jini service, to try to locate other timer
      services and to listen to events from each one. This is handled by the clock device
      (really it is what we have been calling a Jini server, we have just adopted the UPnP.
      The device has a timer installed by <code>setTimer()</code>, 
      and advertises this using a <code>JoinManager</code>. In the meantime it uses a
      <code>ServiceDiscoveryManager</code> to find other timers.
      terminology here).
      <programlisting>
	<?program "src/clock/device/ClockDevice.java"?>
      </programlisting>
    </para>
    
  </sect1>
  
  <sect1>
    <title id="Runtime Behaviour">
      Runtime Behaviour
    </title>
     
    <para>
      If several clocks are started, they will advertise themselves and also attempt
      to find other clocks. When one finds another it tries to determine its state:
      if one is valid and the other invalid then either the valid one sets the time
      on the invalid one, or the invalid one gets the correct time from the valid one.
      Which takes place depends on whether the valid one discovers the invalid one
      or vice versa - it doesn't matter, since the result is the same!.
      Two valid clocks do nothing to each other, as do two invalid ones.
    </para>
    
    <para>
      The ant file <filename>clock.clock.xml</filename> runs a ticker clock, pauses
      sixty seconds and then runs a computer clock. When one discovers the other,
      the ticker clock has its time reset.
      </para>
  </sect1>

  &copyright;
</chapter>
