Package org.immutables.value

Annotation Type Value.Immutable

Enclosing class:
Value
@Documented @Target(TYPE) public static @interface Value.Immutable
Instruct processor to generate immutable implementation of abstract value type. Classes, Interface and Annotation types are supported including top level and non-private static inner types.

Annotation has attributes to configure generation of immutable implementation classes, which are usually configured per-type: should the builder (builder()) be generated or instances interned (intern()). You can use Value.Style or custom style annotation to tune naming conventions and other settings of code-generation, along with default value for per-type attributes (Value.Style.defaults())

Generated accessor methods have annotation copied from original accessor method. However org.immutables.* and java.lang.* are not copied. Be warned that such immutable object may contain attributes with types that are not guaranteed to be immutable, thus not every object will be recursively immutable. While this may be useful in some cases, one should generally avoid creating immutable object with attribute values that could be mutated.

See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    builder
    If builder=false, disables generation of builder().
    boolean
    copy
    If copy=false then generation of copying methods will be disabled.
    boolean
    intern
    If intern=true then instances will be strong interned on construction.
    boolean
    lazyhash
    If lazyhash=true then internal hashCode will be computed (and cached) on first hashCode() method call.
    boolean
    prehash
    If prehash=true then hashCode will be precomputed during construction.
    boolean
    singleton
    If singleton=true, generates internal singleton object constructed without any specified parameters.

  • Element Details

    • singleton

      boolean singleton
      If singleton=true, generates internal singleton object constructed without any specified parameters. Default is false. To access singleton instance use .of() static accessor method.

      This requires that all attributes have default value (including collections which can be left empty). If some required attributes exist it will result in compilation error. Note that in case object does not have attributes, singleton instance will be generated automatically.

      Note that singleton=true does not imply that only one instance of given abstract type. But it does mean that only one "default" instance of the immutable implementation type exist.

      Returns:
      if generate singleton default instance
      Default:
      false

    • intern

      boolean intern
      If intern=true then instances will be strong interned on construction. Default is false.
      Returns:
      if generate strongly interned instances
      Default:
      false

    • copy

      boolean copy
      If copy=false then generation of copying methods will be disabled. This applies to static "copyOf" methods as well as modify-by-copy "withAttributeName" methods which return modified copy using structural sharing where possible. Default value is true, i.e generate copy methods.
      Returns:
      if generate copy methods
      Default:
      true

    • prehash

      boolean prehash
      If prehash=true then hashCode will be precomputed during construction. This could speed up map/set lookups for objects with lots of attributes and nested objects. In general, use this when hashCode computation is expensive and will be used a lot. Note that if Value.Style.privateNoargConstructor() == true this option will be ignored. For lazy (deferred) hashCode computation use lazyhash()
      Returns:
      if generate hash code precomputing
      Default:
      false

    • lazyhash

      boolean lazyhash
      If lazyhash=true then internal hashCode will be computed (and cached) on first hashCode() method call. For eager hashCode computation (in constructor) use prehash().
      Returns:
      to lazily compute the hashCode
      Default:
      false

    • builder

      boolean builder
      If builder=false, disables generation of builder(). Default is true.
      Returns:
      if generate builder
      Default:
      true