001    package hirondelle.web4j.util;
002    
003    import java.util.TimeZone;
004    
005    /**
006     Return a possibly-fake value for the system clock.
007     
008     <P>When testing, it is often useful to use a 
009     <a href='http://www.javapractices.com/topic/TopicAction.do?Id=234'>fake system clock</a>, 
010     in order to exercise code that uses date logic. When you implement this interface, 
011     you are instructing WEB4J classes on what time value they should use as the system clock. 
012     This allows your application to <i>share</i> its fake system clock with the framework, 
013     so that they can both use the exact same clock.
014    
015     <P>See {@link hirondelle.web4j.BuildImpl} for instructions on how to configure an implementation 
016     of this interface. 
017       
018       <P>The following WEB4J framework classes use <tt>TimeSource</tt> :
019       <ul>
020       <li>{@link hirondelle.web4j.model.DateTime#now(TimeZone)} - returns the current date-time  
021       <li>{@link hirondelle.web4j.ui.tag.ShowDate} - displays the current date-time  
022       <li>{@link hirondelle.web4j.webmaster.LoggingConfigImpl} - both the name of the logging 
023       file and the date-time attached to each logging record are affected
024       <li>{@link hirondelle.web4j.webmaster.TroubleTicket} - uses the current date-time
025       <li>{@link hirondelle.web4j.Controller} - upon startup, it places the current date-time in application scope
026       </ul>
027    */
028    public interface TimeSource {
029      
030      /** Return the possibly-fake system time, in milliseconds.  */
031      long currentTimeMillis();
032      
033    }