Collection Ordering

/**
 * Apply natural ordering to sorted collections.
 * Elements will be ordered using their natural comparison order
 * (Comparable implementation). This is the default behavior for
 * sorted collections, but can be made explicit with this annotation.
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
@interface Value.NaturalOrder {}

import org.immutables.value.Value;
import java.util.SortedSet;
import java.util.NavigableSet;
import java.util.SortedMap;

@Value.Immutable
public interface UserProfile {
  String username();
  
  @Value.NaturalOrder
  SortedSet<String> tags();        // Tags sorted alphabetically
  
  @Value.NaturalOrder
  NavigableSet<Integer> scores();  // Scores sorted numerically (ascending)
  
  @Value.NaturalOrder
  SortedMap<String, String> metadata();  // Keys sorted alphabetically
}

// Usage - collections maintain natural ordering
UserProfile profile = ImmutableUserProfile.builder()
    .username("alice")
    .addTags("developer", "admin", "beta-tester")  // Will be sorted: admin, beta-tester, developer
    .addScores(85, 92, 78, 95)                     // Will be sorted: 78, 85, 92, 95
    .putMetadata("role", "developer")
    .putMetadata("department", "engineering")
    .putMetadata("level", "senior")                // Keys sorted: department, level, role
    .build();

// Collections are automatically sorted
SortedSet<String> tags = profile.tags();
// Iteration order: ["admin", "beta-tester", "developer"]

NavigableSet<Integer> scores = profile.scores();
// Iteration order: [78, 85, 92, 95]

/**
 * Apply reverse natural ordering to sorted collections.
 * Elements will be ordered in reverse of their natural comparison order.
 * Equivalent to using Collections.reverseOrder() comparator.
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
@interface Value.ReverseOrder {}

import org.immutables.value.Value;
import java.util.SortedSet;
import java.util.NavigableSet;
import java.util.SortedMap;
import java.time.LocalDateTime;

@Value.Immutable
public interface TaskQueue {
  String name();
  
  @Value.ReverseOrder
  SortedSet<Priority> priorities();    // Highest priority first
  
  @Value.ReverseOrder
  NavigableSet<LocalDateTime> timestamps();  // Most recent first
  
  @Value.ReverseOrder
  SortedMap<Integer, String> rankingsByScore();  // Highest scores first
}

enum Priority implements Comparable<Priority> {
  LOW, MEDIUM, HIGH, CRITICAL
}

// Usage - collections maintain reverse ordering
TaskQueue queue = ImmutableTaskQueue.builder()
    .name("production-tasks")
    .addPriorities(Priority.LOW, Priority.CRITICAL, Priority.MEDIUM)  // Sorted: CRITICAL, MEDIUM, LOW
    .addTimestamps(
        LocalDateTime.of(2023, 1, 1, 10, 0),
        LocalDateTime.of(2023, 1, 1, 14, 30),
        LocalDateTime.of(2023, 1, 1, 9, 15)
    )  // Sorted: 14:30, 10:00, 09:15 (most recent first)
    .putRankingsByScore(85, "alice")
    .putRankingsByScore(92, "bob")  
    .putRankingsByScore(78, "charlie")  // Sorted by key: 92->bob, 85->alice, 78->charlie
    .build();

// Collections maintain reverse order
SortedSet<Priority> priorities = queue.priorities();
// Iteration order: [CRITICAL, MEDIUM, LOW]

NavigableSet<LocalDateTime> timestamps = queue.timestamps();
// Iteration order: [14:30, 10:00, 09:15] (newest first)

import org.immutables.value.Value;
import java.util.SortedSet;
import java.util.NavigableSet;
import java.time.LocalDate;
import java.math.BigDecimal;

@Value.Immutable
public interface SortedSetExample {
  @Value.NaturalOrder
  SortedSet<String> naturalStrings();
  
  @Value.ReverseOrder
  SortedSet<Integer> reverseNumbers();
  
  @Value.NaturalOrder
  NavigableSet<LocalDate> naturalDates();
  
  @Value.ReverseOrder
  NavigableSet<BigDecimal> reverseDecimals();
}

import org.immutables.value.Value;
import java.util.SortedMap;
import java.util.NavigableMap;
import java.time.LocalDateTime;

@Value.Immutable
public interface SortedMapExample {
  @Value.NaturalOrder
  SortedMap<String, Object> naturalKeyMap();
  
  @Value.ReverseOrder
  SortedMap<Integer, String> reverseKeyMap();
  
  @Value.NaturalOrder
  NavigableMap<LocalDateTime, String> naturalDateMap();
  
  @Value.ReverseOrder
  NavigableMap<Double, String> reverseScoreMap();
}

// Generated builder methods for ordered sets
public Builder addTags(String element) { ... }
public Builder addTags(String... elements) { ... }
public Builder addAllTags(Iterable<String> elements) { ... }

// The elements are automatically ordered according to the annotation

// Generated builder methods for ordered maps
public Builder putMetadata(String key, String value) { ... }
public Builder putAllMetadata(Map<String, String> entries) { ... }

// The entries are automatically ordered by key according to the annotation

import org.immutables.value.Value;
import java.util.SortedSet;
import java.util.TreeSet;
import java.util.Comparator;

@Value.Immutable
public interface CustomOrderedData {
  // Use annotation for simple cases
  @Value.ReverseOrder
  SortedSet<String> reverseAlphabetic();
  
  // Use factory methods for complex ordering
  static ImmutableCustomOrderedData.Builder builder() {
    return ImmutableCustomOrderedData.builder();
  }
  
  // Custom comparator for complex sorting
  static SortedSet<Task> createTaskSet() {
    return new TreeSet<>(
        Comparator
            .comparing(Task::priority)
            .thenComparing(Task::createdAt)
            .reversed()
    );
  }
}

@Value.Immutable
public interface Event {
  String name();
  LocalDateTime timestamp();
  Priority priority();
}

@Value.Immutable
public interface EventLog {
  @Value.ReverseOrder
  SortedSet<Event> events();  // Most recent events first (if Event implements Comparable)
}

// Event must implement Comparable for ordering to work
// Events will be sorted by their natural order (typically by timestamp or priority)