or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdattributes.mdcore-immutable.mdindex.mdstyle-configuration.mdvalidation.md
tile.json

tessl/maven-org-immutables--value

Compile-time annotation processor for generating immutable value objects with builder patterns and compile-time validation.

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

To install, run

npx @tessl/cli install tessl/maven-org-immutables--value@2.10.0

index.mddocs/

Immutables Value

Immutables Value is a Java annotation processing toolkit for generating immutable value objects at compile time. It enables developers to define value types using interfaces, abstract classes, or annotations, and automatically generates builder patterns, immutable implementations, and fluent APIs with compile-time validation.

Package Information

  • Package Name: org.immutables:value
  • Package Type: Maven
  • Language: Java
  • Installation: 
    <dependency>
  <groupId>org.immutables</groupId>
  <artifactId>value</artifactId>
  <version>2.10.1</version>
  <scope>provided</scope>
</dependency>

Core Imports

import org.immutables.value.Value;

For generated classes (typical pattern):

// Generated class follows naming convention: Immutable + YourClassName
import com.example.ImmutablePerson;

Basic Usage

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

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

// Use the generated immutable implementation
Person person = ImmutablePerson.builder()
    .name("John Doe")
    .age(30)
    .addHobbies("reading", "swimming")
    .email("john@example.com")
    .build();

// Create modified copies
Person updatedPerson = person.withAge(31);

// Access values
String name = person.name();
int age = person.age();
List<String> hobbies = person.hobbies(); // Returns immutable list

Architecture

Immutables Value is built around several key components:

  • Annotation Processing: Compile-time code generation using standard Java annotation processing
  • Builder Pattern: Automatic generation of fluent, type-safe builders for complex object construction
  • Immutable Implementation: Generated classes with immutable state and structural sharing for efficient copying
  • Style System: Comprehensive customization of naming conventions and generation behavior
  • Validation Framework: Built-in support for constraint validation and invariant checking

The library generates immutable implementations that follow the "Immutable" prefix naming convention (customizable via Style), providing builders for construction, copy methods for modification, and standard object methods (equals, hashCode, toString).

Capabilities

Core Immutable Generation

Primary functionality for generating immutable value objects from abstract types with builder patterns, copy methods, and validation support.

@interface Value.Immutable {
    boolean singleton() default false;
    boolean intern() default false;
    boolean copy() default true;
    boolean prehash() default false;
    boolean lazyhash() default false;
    boolean builder() default true;
}

Core Immutable Generation

Attribute Customization

Advanced attribute behavior including default values, lazy computation, derived values, and parameter configuration for flexible object modeling.

@interface Value.Default { }
@interface Value.Lazy { }
@interface Value.Derived { }
@interface Value.Parameter {
    int order() default -1;
    boolean value() default true;
}
@interface Value.Auxiliary { }

Attribute Customization

Style and Configuration

Comprehensive styling system for customizing naming conventions, generation behavior, validation methods, and code structure.

@interface Value.Style {
    // Naming templates (subset of 25+ naming options)
    String[] get() default "get*";
    String init() default "*";
    String with() default "with*";
    String add() default "add*";
    String builder() default "builder";
    String build() default "build";
    String copyOf() default "copyOf";
    String of() default "of";
    
    // Type naming templates (subset of 10+ type naming options)
    String typeImmutable() default "Immutable*";
    String typeBuilder() default "Builder";
    String typeModifiable() default "Modifiable*";
    
    // Behavioral configuration (subset of 50+ configuration options)
    boolean strictBuilder() default false;
    boolean stagedBuilder() default false;
    boolean allParameters() default false;
    boolean jdkOnly() default false;
    ValidationMethod validationMethod() default ValidationMethod.SIMPLE;
    ImplementationVisibility visibility() default ImplementationVisibility.SAME;
    BuilderVisibility builderVisibility() default BuilderVisibility.PUBLIC;
    
    // ... 60+ additional configuration options for advanced customization
}

Style and Configuration

Validation and Constraints

Built-in validation framework with constraint checking, invariant validation, and custom exception handling.

@interface Value.Check { }
@interface Value.Redacted { }
@interface Value.NonAttribute { }

enum ValidationMethod {
    NONE, MANDATORY_ONLY, SIMPLE, VALIDATION_API
}

enum ImplementationVisibility {
    PUBLIC, SAME, PACKAGE, PRIVATE
}

enum BuilderVisibility {
    PUBLIC, SAME, PACKAGE
}

Validation and Constraints

Advanced Features

Specialized features including modifiable companions, collection ordering, inclusion patterns, and enclosing type organization.

@interface Value.Modifiable { }
@interface Value.Include {
    Class<?>[] value();
}
@interface Value.Enclosing { }
@interface Value.NaturalOrder { }
@interface Value.ReverseOrder { }

Advanced Features

Types

@interface Value {
    // Main namespace annotation containing all nested annotations
}

@interface Generated {
    String from() default "";
    String generator() default "";
}