001    // Copyright 2008 Regents of the University of California.  May be used
002    // under the terms of the revised BSD license.  See LICENSING for details.
003    package org.joe_e.var;
004    
005    import java.io.Serializable;
006    
007    import org.joe_e.Equatable;
008    
009    /**
010     * A variable that can be set only once.
011     * <p>
012     * An instance of this class is like a <code>final</code> variable that can
013     * either be initialized, or left uninitialized. This is useful for keeping
014     * track of whether or not a particular branch of code has been executed. For
015     * example, say you've got some code that operates on a set of objects.
016     * Sometimes, the set is mutated, sometimes not. To remember whether or not a
017     * mutation was made, the set's update method could be coded as:
018     * </p>
019     * <pre>
020     * private final Milestone&lt;Boolean&gt; dirty = Milestone.make();
021     * &hellip;
022     * public void
023     * add(final Object x) {
024     *     objectSet.add(x);
025     *     dirty.set(true);
026     * }
027     * </pre>
028     * <p>
029     * When the code is done using the set, a commit() method can check to see if
030     * any updates need to be written:
031     * </p>
032     * <pre>
033     * public void
034     * commit() {
035     *     if (dirty.is()) {
036     *         // write out the new set
037     *         &hellip;
038     *     }
039     * }
040     * </pre>
041     * <p>
042     * By using this class, instead of a normal variable, you can better communicate
043     * to a code reviewer that a variable is only assigned once. The variable
044     * declaration alone ensures this property is enforced, without the need to
045     * inspect all the code that can access the variable.
046     * </p>
047     * <p>
048     * This class is named Milestone, since it keeps track of whether or not a
049     * program's execution reached a certain point or not. This program meaningful
050     * execution point is a milestone.
051     * </p>
052     */
053    public class
054    Milestone<T> implements Equatable, Serializable {
055        static private final long serialVersionUID = 1L;
056        
057        /**
058         * current state
059         */
060        private T marker;
061    
062        protected
063        Milestone() {}
064        
065        /**
066         * Constructs an instance.
067         */
068        static public <T> Milestone<T>
069        make() { return new Milestone<T>(); }
070        
071        // org.joe_e.var.Milestone interface
072    
073        /**
074         * Has the milestone been {@linkplain #set passed}?
075         * @return <code>true</code> if {@linkplain #set set},
076         *         else <code>false</code>
077         */
078        public boolean
079        is() { return null != marker; }
080        
081        /**
082         * Gets the milestone marker.
083         * @return marker, or <code>null</code> if not {@linkplain #set set}
084         */
085        public T
086        get() { return marker; }
087    
088        /**
089         * Sets the milestone marker, if not already set.
090         * @param marker    initialized value of the variable
091         * @return <code>false</code> if previously set, else <code>true</code>
092         */
093        public boolean
094        set(final T marker) {
095            if (null == marker) { throw new NullPointerException(); }
096            if (null != this.marker) { return false; }
097            this.marker = marker;
098            return true;
099        }
100    }