Core Immutable Generation

/**
 * Generate immutable implementation of abstract value type.
 * Works with classes, interfaces, and annotation types including top level 
 * and non-private static inner types.
 */
@interface Value.Immutable {
    /**
     * Generate internal singleton object constructed without parameters.
     * Requires all attributes have default values.
     * Access via .of() static method.
     */
    boolean singleton() default false;
    
    /**
     * Enable strong interning - instances will be interned on construction.
     * Improves memory efficiency for frequently used identical objects.
     */
    boolean intern() default false;
    
    /**
     * Generate copying methods including static copyOf and modify-by-copy 
     * withAttributeName methods with structural sharing.
     */
    boolean copy() default true;
    
    /**
     * Precompute hashCode during construction for expensive computations
     * that will be used frequently in collections.
     */
    boolean prehash() default false;
    
    /**
     * Compute and cache hashCode on first hashCode() method call.
     * Alternative to prehash for deferred computation.
     */
    boolean lazyhash() default false;
    
    /**
     * Generate builder() factory method and Builder class.
     * Set to false to disable builder generation.
     */
    boolean builder() default true;
}

// Basic immutable generation
@Value.Immutable
public interface Person {
    String name();
    int age();
}

// Generated: ImmutablePerson class with builder
Person person = ImmutablePerson.builder()
    .name("Alice")
    .age(25)
    .build();

// Singleton pattern for constants
@Value.Immutable(singleton = true)
public interface Empty {
    @Value.Default
    default String message() { return "empty"; }
}

// Access singleton via .of()
Empty empty = ImmutableEmpty.of();

// Performance optimizations
@Value.Immutable(intern = true, prehash = true)
public interface Coordinate {
    double x();
    double y();
}

// Interned instances for memory efficiency
Coordinate origin = ImmutableCoordinate.builder().x(0).y(0).build();

// Disable builder for parameter-only construction
@Value.Immutable(builder = false)
public interface Point {
    @Value.Parameter int x();
    @Value.Parameter int y();
}

// Only constructor available: ImmutablePoint.of(x, y)
Point point = ImmutablePoint.of(10, 20);

/**
 * Generated implementation class structure (example for Person interface)
 * 
 * class ImmutablePerson implements Person {
 *   // Private final fields for all attributes
 *   private final String name;
 *   private final int age;
 *   
 *   // Constructor (package-private or private)
 *   ImmutablePerson(String name, int age) { ... }
 *   
 *   // Accessor methods matching abstract type
 *   public String name() { return name; }
 *   public int age() { return age; }
 *   
 *   // Copy methods (if copy = true)
 *   public ImmutablePerson withName(String name) { ... }
 *   public ImmutablePerson withAge(int age) { ... }
 *   
 *   // Factory methods
 *   public static ImmutablePerson.Builder builder() { ... }
 *   public static ImmutablePerson copyOf(Person instance) { ... }
 *   
 *   // Standard object methods
 *   public boolean equals(Object obj) { ... }
 *   public int hashCode() { ... }
 *   public String toString() { ... }
 *   
 *   // Nested Builder class
 *   public static final class Builder { ... }
 * }
 */

/**
 * Generated Builder class structure provides:
 * - Fluent method chaining
 * - Type safety at compile time
 * - Validation before building
 * - Optional from() method for copying
 */
public static final class Builder {
    // Setter methods for each attribute
    public Builder name(String name);
    public Builder age(int age);
    
    // Collection methods (for collection attributes)
    public Builder addHobbies(String element);
    public Builder addHobbies(String... elements);
    public Builder addAllHobbies(Iterable<String> elements);
    
    // Build method with validation
    public ImmutablePerson build();
    
    // Copy constructor (if enabled)
    public Builder from(Person instance);
}

/**
 * Copy methods provide efficient immutable updates using structural sharing.
 * Only changed attributes create new objects; unchanged attributes are shared.
 */

// Modify-by-copy methods for each attribute
public ImmutablePerson withName(String name);
public ImmutablePerson withAge(int age);

// Static copy constructor
public static ImmutablePerson copyOf(Person instance);

// Original object
Person person = ImmutablePerson.builder()
    .name("Alice")
    .age(25)
    .addHobbies("reading", "swimming")
    .build();

// Efficient updates with structural sharing
Person older = person.withAge(26);
Person renamed = person.withName("Alice Smith");

// Copy from existing instance
Person copy = ImmutablePerson.copyOf(person);

// Chain copy operations
Person updated = person
    .withAge(26)
    .withName("Alice Smith");