org.joe_e.var
Class Milestone<T>

java.lang.Object
  org.joe_e.var.Milestone<T>

All Implemented Interfaces:

java.io.Serializable, Equatable

public class Milestone<T>
extends java.lang.Object
implements Equatable, java.io.Serializable

A variable that can be set only once.

An instance of this class is like a final variable that can either be initialized, or left uninitialized. This is useful for keeping track of whether or not a particular branch of code has been executed. For example, say you've got some code that operates on a set of objects. Sometimes, the set is mutated, sometimes not. To remember whether or not a mutation was made, the set's update method could be coded as:

 private final Milestone<Boolean> dirty = Milestone.make();
 …
 public void
 add(final Object x) {
     objectSet.add(x);
     dirty.set(true);
 }
 

When the code is done using the set, a commit() method can check to see if any updates need to be written:

 public void
 commit() {
     if (dirty.is()) {
         // write out the new set
         …
     }
 }
 

By using this class, instead of a normal variable, you can better communicate to a code reviewer that a variable is only assigned once. The variable declaration alone ensures this property is enforced, without the need to inspect all the code that can access the variable.

This class is named Milestone, since it keeps track of whether or not a program's execution reached a certain point or not. This program meaningful execution point is a milestone.

See Also:

Serialized Form

Method Summary

T	get() Gets the milestone marker.
boolean	is() Has the milestone been passed?
static <T> Milestone<T>	make() Constructs an instance.
boolean	set(T marker) Sets the milestone marker, if not already set.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

make

public static <T> Milestone<T> make()

Constructs an instance.

is

public boolean is()

Has the milestone been passed?

Returns:

true if set, else false

get

public T get()

Gets the milestone marker.

Returns:

marker, or null if not set

set

public boolean set(T marker)

Sets the milestone marker, if not already set.

Parameters:

marker - initialized value of the variable

Returns:

false if previously set, else true