Add interface for freezing/thawing objects

This adds a new interface IFreezable, which denotes that your object
supports being 'frozen' (immutable) or 'thawed' (mutable). There is also
optional support for 'deep-freezing' objects, which disables the ability
to thaw them.

It also introduces a new exception called ObjectFrozen, which
implementations of IFreezable may or may not throw when you attempt to
modify a frozen object

2 files changed, 120 insertions, 0 deletions

diff --git a/src/main/java/bjc/funcdata/IFreezable.java b/src/main/java/bjc/funcdata/IFreezable.java
new file mode 100644
index 0000000..abc7d6f
--- /dev/null
+++ b/src/main/java/bjc/funcdata/IFreezable.java
@@ -0,0 +1,73 @@
+package bjc.funcdata;
+
+/**
+ * Indicates that an object can switch between immutable and mutable modes.
+ * 
+ * Note that this only implements 'shallow' immutability. Namely, any sub-objects
+ * are not made immutable, and if the type is a collection, the elements are still
+ * as mutable as they were before.
+ * 
+ * Implementations of this interface may choose to throw {@link ObjectFrozen} if
+ * you attempt to modify a frozen object, but they may also choose not to.
+ * 
+ * @author Ben Culkin
+ */
+public interface IFreezable {
+	/**
+	 * Freezes the internal state of this object, making it immutable.
+	 * 
+	 * @return True if the object is frozen, false if it couldn't be frozen.
+	 */
+	public boolean freeze();
+	/**
+	 * Thaws the internal state of this object, making it mutable.
+	 * 
+	 * @return True if the object is thawed, false if it couldn't be thawed.
+	 */
+	public boolean thaw();
+
+	/**
+	 * 'Deep-freeze' this object, making it immutable and disabling the ability to
+	 * thaw it.
+	 * 
+	 * @return True if the object was deep-frozen, false if that couldn't happen.
+	 */
+	default boolean deepFreeze() {
+		return false;
+	}
+	
+	/**
+	 * Check if this object can be frozen.
+	 * 
+	 * @return Whether or not the object can be frozen.
+	 */
+	default boolean canFreeze() {
+		return false;
+	}
+	
+	/**
+	 * Checks if this object can be thawed.
+	 * 
+	 * @return Whether or not the object can be thawed.
+	 */
+	default boolean canThaw() {
+		return false;
+	}
+	
+	/**
+	 * Determines if this object is frozen.
+	 * 
+	 * @return True if the object is frozen, false if the object is thawed.
+	 */
+	public boolean isFrozen();
+	
+
+	/**
+	 * Determines if this object is thawed.
+	 * 
+	 * @return True if the object is thawed, false if the object is thawed.
+	 */
+	default boolean isThawed() {
+		return !isFrozen();
+	}
+}
diff --git a/src/main/java/bjc/funcdata/ObjectFrozen.java b/src/main/java/bjc/funcdata/ObjectFrozen.java
new file mode 100644
index 0000000..2260a0e
--- /dev/null
+++ b/src/main/java/bjc/funcdata/ObjectFrozen.java
@@ -0,0 +1,47 @@
+package bjc.funcdata;
+
+/**
+ * Exception that implementations of {@link IFreezable} can throw if you attempt
+ * to modify a frozen object.
+ * 
+ * @author Ben Culkin
+ *
+ */
+public class ObjectFrozen extends RuntimeException {
+	private static final long serialVersionUID = -1567447627139090728L;
+
+	/**
+	 * Create a new ObjectFrozen exception.
+	 */
+	public ObjectFrozen() {
+		super();
+	}
+
+	/**
+	 * Create a new ObjectFrozen exception.
+	 * 
+	 * @param message The message of the exception.
+	 */
+	public ObjectFrozen(String message) {
+		super(message);
+	}
+
+	/**
+	 * Create a new ObjectFrozen exception.
+	 * 
+	 * @param cause The root cause of this exception.
+	 */
+	public ObjectFrozen(Throwable cause) {
+		super(cause);
+	}
+
+	/**
+	 * Create a new ObjectFrozen exception.
+	 * 
+	 * @param message The message of the exception.
+	 * @param cause The root cause of this exception.
+	 */
+	public ObjectFrozen(String message, Throwable cause) {
+		super(message, cause);
+	}
+}