or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

attributes.mdbean-style.mdcode-generation.mdcollections.mdcore-immutable.mdindex.mdintegrations.mdjson-marshaling.mdruntime-marshaling.mdstyling.md
tile.json

tessl/maven-org-immutables--immutables

Comprehensive Java annotation processing framework for generating immutable value objects, marshalers, repositories, and custom code generators with extensive integration support.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.immutables/immutables@1.1.x

To install, run

npx @tessl/cli install tessl/maven-org-immutables--immutables@1.1.0

index.mddocs/

Immutables Value

A comprehensive Java annotation processing framework for generating immutable value objects with builders, copy methods, and structural sharing. The library eliminates boilerplate code while providing type safety, high performance, and extensive customization options through compile-time code generation.

Package Information

  • Package Name: org.immutables:value
  • Package Type: maven
  • Language: Java
  • Installation: Add to your Maven pom.xml:
<dependency>
  <groupId>org.immutables</groupId>
  <artifactId>value</artifactId>
  <version>1.1.3</version>
</dependency>

For Gradle:

implementation 'org.immutables:value:1.1.3'

Core Imports

import org.immutables.value.Value;

For JSON marshaling:

import org.immutables.value.Json;

For Jackson integration:

import org.immutables.value.Jackson;

Basic Usage

import org.immutables.value.Value;
import java.util.Optional;

// Define an abstract value type
@Value.Immutable
public interface Person {
  String name();
  int age();
  Optional<String> email();
}

// Generated implementation usage
public class Example {
  public static void main(String[] args) {
    // Create immutable instances using generated builder
    ImmutablePerson person = ImmutablePerson.builder()
        .name("Alice")
        .age(30)
        .email("alice@example.com")
        .build();
    
    // Copy with modifications using generated copy methods
    ImmutablePerson olderPerson = person.withAge(31);
    
    // Structural equality and hashCode work correctly
    System.out.println(person.equals(olderPerson)); // false
    System.out.println(person.name()); // "Alice"
    System.out.println(person.toString()); // "Person{name=Alice, age=30, email=alice@example.com}"
  }
}

Architecture

Immutables uses annotation processing to generate implementations at compile-time:

  • Abstract Value Types: Interfaces or abstract classes annotated with @Value.Immutable
  • Generated Implementations: Concrete immutable classes with Immutable prefix
  • Builder Pattern: Fluent builder interfaces for complex object construction
  • Copy Methods: Methods prefixed with with for creating modified copies
  • Structural Sharing: Efficient memory usage through shared immutable collections
  • Style System: Comprehensive customization through @Value.Style annotations

The annotation processor integrates with build tools (Maven, Gradle) and IDEs, generating code that runs on JDK 6+ while supporting modern Java features.

Capabilities

Core Immutable Generation

Primary annotation for generating immutable value objects with builders, copy methods, validation, and comprehensive customization options.

@interface Value.Immutable {
  boolean singleton() default false;
  boolean intern() default false;
  boolean copy() default true;
  boolean prehash() default false;
  boolean builder() default true;
  boolean jdkOnly() default false;
  ImplementationVisibility visibility() default ImplementationVisibility.SAME;
}

enum ImplementationVisibility {
  PUBLIC, SAME, PACKAGE, PRIVATE
}

Core Immutable Generation

Attribute Customization

Annotations for customizing individual attributes including default values, lazy computation, validation, and parameter ordering.

@interface Value.Default {}
@interface Value.Derived {}
@interface Value.Lazy {}
@interface Value.Parameter {
  int order() default 0;
}
@interface Value.Check {}
@interface Value.Auxiliary {}

Attribute Customization

Style and Naming Customization

Comprehensive style system for customizing generated class names, method names, builder patterns, and structural conventions.

@interface Value.Style {
  String[] get() default {};
  String init() default "*";
  String with() default "with*";
  String add() default "add*";
  String addAll() default "addAll*";
  String put() default "put*";
  String putAll() default "putAll*";
  String copyOf() default "copyOf";
  String of() default "of";
  String instance() default "instance";
  String builder() default "builder";
  String build() default "build";
  String typeBuilder() default "*Builder";
  String[] typeAbstract() default {};
  String typeImmutable() default "Immutable*";
  String typeImmutableEnclosing() default "*";
  String typeImmutableNested() default "*";
  Immutable defaults() default @Immutable;
}

Style and Naming

JSON Marshaling

Built-in JSON marshaling capabilities with customizable field names, subclass handling, and integration with streaming JSON APIs.

@interface Json.Marshaled {}
@interface Json.Named {
  String value();
}
@interface Json.Ignore {}
@interface Json.ForceEmpty {}
@interface Json.Import {
  Class<?>[] value();
}
@interface Json.Subclasses {
  Class<?>[] value();
}

JSON Marshaling

Third-Party Integrations

Integration annotations for popular frameworks including Jackson, Gson, and MongoDB with seamless serialization and repository generation.

@interface Jackson.Mapped {}

@interface Gson.TypeAdapted {}
@interface Gson.Named {}
@interface Gson.Subclasses {
  Class<?>[] value();
}

@interface Mongo.Repository {
  String value() default "";
}
@interface Mongo.Id {}

Third-Party Integrations

Collection Ordering

Annotations for specifying ordering behavior in generated sorted collections, supporting both natural and reverse ordering.

@interface Value.NaturalOrder {}
@interface Value.ReverseOrder {}

Collection Ordering

Bean Style Support

Annotations for generating bean-style accessors and applying conservative coding conventions for enterprise environments.

@interface BeanStyle.Accessors {}
@interface BeanStyle.Conservative {}

Bean Style Support

Code Generation Framework

Advanced annotation processing framework for creating custom code generators and template-based processors beyond basic immutable generation.

@interface Generator.Template {}
@interface Generator.Import {
  Class<?>[] value();
}
@interface Generator.Typedef {}
@interface Generator.Memoised {}
@interface Generator.SupportedAnnotations {
  Class<? extends Annotation>[] value();
}

Code Generation Framework

Runtime Marshaling Framework

Runtime utilities for JSON marshaling, async operations, and framework integrations providing serialization and database operation foundations.

public abstract class Marshaler<T> {
  public abstract T unmarshalInstance(JsonParser parser) throws IOException;
  public abstract void marshalInstance(JsonGenerator generator, T instance) throws IOException;
  public abstract Class<T> getExpectedType();
}

public final class Marshaling {
  public static String toJson(Object object);
  public static <T> T fromJson(String json, Class<? extends T> expectedType);
  public static <T> Marshaler<T> marshalerFor(Class<? extends T> expectedType);
}

public interface FluentFuture<V> extends ListenableFuture<V> {
  V getUnchecked();
  <T> FluentFuture<T> transform(Function<? super V, ? extends T> function);
}

Runtime Marshaling Framework

Types

enum ImplementationVisibility {
  PUBLIC,    // Generated implementation is public
  SAME,      // Same visibility as abstract type
  PACKAGE,   // Package-private implementation
  PRIVATE    // Private implementation (requires factory methods)
}