• Immutable Objects are often also ValueObjects, e.g. when used as Map keys

• ValueObject

• Request For Enhancement: Add Immutable Types To Java
• Pattern Enforcing Compiler (PEC™): A compiler that can enforce the immutable pattern amongst other patterns

• To mutate or not to mutate

-- JohnOHanley - 23 Jul 2003

• always put all data in the constructor, instead of using a no-argument constructor combined with subsequent calls to setXXX methods

<-- changed some field names slightly to be more in sync with Java styleguides -->

/** * A mutable object field. In this case, the state of this mutable field * is to be changed only by this class. (In other cases, it makes perfect * sense to allow the state of a field to be changed outside the native * class; this is the case when a field acts as a "pointer" to an object * created elsewhere.) */ private final Date dateOfDiscovery;

/** Sole constructor */ public Planet (double mass, String name, Date dateOfDiscovery) { this.mass = mass; this.name = name; //make a private copy of dateOfDiscovery //this is the only way to keep the dateOfDiscovery

<-- This creates the navigation links to :  Home | Help | Index | etc.  -->

Immutable Object

Objects have identity (location in memory), state (data), and behavior (methods). Once constructed, an Immutable Object cannot change state.

Immutable objects greatly simplify your program, since they

• are simple to construct, test, and use
• are automatically thread-safe and have no synchronization issues
• do not need a copy constructor
• do not need an implementation of clone
• do not need to be copied defensively when used as a field
• make good Map keys and Set elements (these objects must not change state while in the collection)

Make a class immutable by following these guidelines :

• always construct an object completely, instead of using a no-argument constructor combined with subsequent calls to setXXX methods
• do not provide any methods which can change the state of the object in any way - not just setXXX methods, but any method which can change state
• ensure no methods can be overridden - make the class final, or use static factories and keep constructors private
• make fields final
• if a mutable object field's state is "owned" by the native class, such that no other class is to be allowed to change the state of the field, then when the field "crosses the interface" (as in a get method, when the field is returned to the user, or in the constructor itself), then a defensive copy must be made, in order to maintain encapsulation.
• if a mutable object field's state is not "owned" by the native class, then defensive copies of the object field are not necessary

Example

import java.util.Date;

/**
* Planet is an immutable class, since there is no way to change
* its state after construction.
*/
public final class Planet {

  public Planet (double aMass, String aName, Date aDateOfDiscovery) {
     super();
     fMass = aMass;
     fName = aName;
     //make a private copy of aDateOfDiscovery
     //this is the only way to keep the fDateOfDiscovery
     //field private, and shields this class from any changes
     //to the original aDateOfDiscovery object
     fDateOfDiscovery = new Date(aDateOfDiscovery.getTime());
  }

  //gets but no sets, and no methods which change state
  public double getMass() {
    return fMass;
  }

  public String getName() {
    return fName;
  }

  /**
  * Returns a defensive copy of the field.
  * The caller of this method can do anything they want with the
  * returned Date object, without affecting the internals of this
  * class in any way.
  */
  public Date getDateOfDiscovery() {
    return new Date(fDateOfDiscovery.getTime());
  }

  // PRIVATE /////

  /**
  * Primitive data is always immutable.
  */
  private final double fMass;

  /**
  * An immutable object field. (String objects never change state.)
  */
  private final String fName;

  /**
  * A mutable object field. In this case, the state of this mutable field
  * is to be changed only by this class. (In other cases, it makes perfect
  * sense to allow the state of a field to be changed outside the native
  * class; this is the case when a field acts as a "pointer" to an object
  * created elsewhere.)
  */
  private final Date fDateOfDiscovery;
}

-- JohnOHanley - 19 Jul 2003

<-- anchor to allow a link to the discussion about this article -->

Discussion about ImmutableObject

<-- generate a header for the discussion part of page -->