To create an immutable Java Bean, you need to type:

• The list of private fields.
• A constructor containing the fields and assigning this.myField = myField.
• int hashCode() - ideally generating the hashCode as part of the constructor and storing it for immediate recall.
• Generating the hashCode in the constructor improves performance when looking up beans in HashMap collections. The hashCode is calculated once rather than every time a lookup is performed.
• boolean equals(Object)
• String toString()
• Normally a java.io.Serializable designation (by implementing the interface) and a serialVersionUID declaration.

The @ImmutableBean annotation transforms a Java class with just private fields declared on it into a best-practise immutable bean. Some of the fields must be marked with @BusinessKey; these fields take part in hashCode() and equals(). @NotInToString is also provided, allowing yout to specify that you don't want a bean property to appear in the toString() output.

The @ImmutableBean annotation processor works with javac (which, of course, Maven typically uses). It cannot produce the correct results when running under Eclipse. The Eclipse engine sorts the fields and methods before presenting them to to the annotation processor. javac follows the Pluggable Annotation Processing API specification (JSR 269) and presents the fields and methods in the natural ordering that they were declared in the .java source file. This is a known bug in Eclipse filed as Eclipse-Bug-300408.

Options on the @ImmutableBean tag allow you to:

• Override the default that the bean is Serializable.
• Specify an override to the serialVersionUID value which defaults to 1 (long).
• Generate code required by JPA (not nice, but it gets the job done).
• Empty constructor :(
• private setter methods for every property
• hashCode generated in the hashCode() method rather than calculated on construction.

To get ImmutableBean using Maven, configure a repository URL:

• http://immutablebean.googlecode.com/svn/maven

• http://immutablebean.googlecode.com/svn/maven-snapshot

Then add this dependency to your pom.xml:

        <dependency>
            <groupId>org.immutablebean</groupId>
            <artifactId>ImmutableBean</artifactId>
            <version>1.3</version>
            <scope>compile</scope> <!-- Not required at runtime -->
        </dependency>

That's all you need to do if you are just generating beans in a separate project which will be packaged into its own jar and managed as a shared dependency of your other projects (recommended).

If you want to have bean definitions and code that uses the beans then you have to ensure that the beans are generated and compiled before the main compilation execution (default-compile). Take a look here for an example of how to specify an additional compilation step bound to the generate-sources lifecycle stage:

• http://code.google.com/p/immutablebean/source/browse/#svn/ImmutableBeanExample

Example input;

package org.immutablebean.beantemplates;

import java.math.BigDecimal;
import java.util.Date;
import java.util.List;

import org.immutablebean.BusinessKey;
import org.immutablebean.ImmutableBean;
import org.immutablebean.NotInToString;

@ImmutableBean(outputClassName="org.immutablebean.test.BasicInterfaceBean",
		       hashCodeInitialNonZeroOddNumber=17,
		       hashCodeMultiplierNonZeroOddNumber=99)
public interface BeanInterfaceTemplate {
	
	@BusinessKey String getIdentifier();
	@BusinessKey int getVersion();
	Date getCreationDate();
	BigDecimal getPrice();
	BigDecimal getQuantity();
	List<String> getDescriptions();
	@NotInToString boolean isActive();
	
}

Example output:

package org.immutablebean.test;

@javax.annotation.Generated(value={"org.immutablebean.processor.ImmutableBeanProcessor"}, date="2010-07-22T21:29:15.506+0100")
public final class BasicInterfaceBean implements org.immutablebean.beantemplates.BeanInterfaceTemplate {

    private java.lang.String identifier;
    private int version;
    private java.util.Date creationDate;
    private java.math.BigDecimal price;
    private java.math.BigDecimal quantity;
    private java.util.List<java.lang.String> descriptions;
    private boolean active;

    private int hashCode;

    public BasicInterfaceBean(java.lang.String identifier, int version, java.util.Date creationDate,
                              java.math.BigDecimal price, java.math.BigDecimal quantity,
                              java.util.List<java.lang.String> descriptions, boolean active) {
        this.identifier = identifier;
        this.version = version;
        this.creationDate = creationDate;
        this.price = price;
        this.quantity = quantity;
        this.descriptions = descriptions;
        this.active = active;

        hashCode =  new org.apache.commons.lang.builder.HashCodeBuilder(17, 99)
            .append(identifier)
            .append(version)
            .toHashCode();
    }

    public java.lang.String getIdentifier() {
        return identifier;
    }

    public int getVersion() {
        return version;
    }

    public java.util.Date getCreationDate() {
        return creationDate;
    }

    public java.math.BigDecimal getPrice() {
        return price;
    }

    public java.math.BigDecimal getQuantity() {
        return quantity;
    }

    public java.util.List<java.lang.String> getDescriptions() {
        return descriptions;
    }

    public boolean isActive() {
        return active;
    }

    public int hashCode() {
        return hashCode;
    }

    public boolean equals(Object obj) {
        if (obj == null) { return false; }
        if (obj == this) { return true; }
        if (obj.getClass() != getClass()) {
            return false;
        }
        BasicInterfaceBean rhs = (BasicInterfaceBean)obj;
        return new org.apache.commons.lang.builder.EqualsBuilder()
            .append(identifier, rhs.identifier)
            .append(version, rhs.version)
            .isEquals();
    }

    public String toString() {
        return new org.apache.commons.lang.builder.ToStringBuilder(this)
            .append("identifier", identifier)
            .append("version", version)
            .append("creationDate", creationDate)
            .append("price", price)
            .append("quantity", quantity)
            .append("descriptions", descriptions)
            .toString();
    }

}