com.iparelan.util
Interface ImmutabilityStrategy<T>

Type Parameters:

T - The value type.

@Copyright(value="Copyright © 2008, Iparelan Solutions, LLC. All rights reserved.")
public interface ImmutabilityStrategy<T>

An algorithm for guarding a specified value with respect to value changes. This strategy ensures that nothing can accidentally or maliciously alter a value through the value produced by the strategy.

Note that this strategy does not necessarily produce immutable objects. Rather, it produces objects that cannot mutate the objects passed to it. For example, producing a mutable copy is sufficient to guard the original object from change (via the mutable copy).

There are three cases to consider:

1. If a value is of a type that is already immutable, then a reasonable immutability strategy is to produce that value directly.
2. Produce a copy, sometimes called a clone, of the value. This is the "Prototype" pattern.

   The particular manner in which this operation is done depends on the type being copied. Some types support a clone operation, others have a copy constructor, but some types have no support for the Prototype pattern. In such cases, custom copying code must be written to adapt the type for copying.

   Note that this approach will most likely "unlink" the copy from from the original. This is important if the original is not "totally immutable," in other words, if the original object may be changed elsewhere. Such a change will not be reflected in the copy unless some update mechanism is created to link the original to all copies of it.

   The clone is produced instead of the object that holds the immutable value.

3. Use the "Decorator" pattern to wrap the object holding the value in a decorator that does not permit mutation operations. Such a decorator creates a "read-only" view of the value by forwarding only accessor operations and intercepting mutator operatations.

   The decorator is produced instead of the object that holds the "immutable" value.

Version:

July 2008

Author:

Greg Mattes

To Do:

• Consider the null object pattern rather than the null value when creating immutability strategies for types that are already immutable.

Field Summary

static ImmutabilityStrategy<Integer>

INTEGER

Method Summary

T	freeze(T immutable) Produces the same value as immutable, but the value produced does not have the capability of changing immutable.

Field Detail

INTEGER

static final ImmutabilityStrategy<Integer> INTEGER

Method Detail

freeze

@Nullable
T freeze(@Nullable
                  T immutable)

Produces the same value as immutable, but the value produced does not have the capability of changing immutable. Note that this is slightly different than ensuring that the value immutable may never change.

Parameters:

immutable - A value that may not be altered by the value produced by this method. May be null.

Returns:

The same value as immutable, but without the capability of changing immutable. null iff immutable is null. The value produce may or may not be the same object as immutable.

Throws:

ConfigurationException - Iff some error occurs while attempting to protect the integrity of immutable.