# AnnotationAwareOrderComparator class

A Jetleaf-provided OrderComparator implementation that determines ordering based on the presence of the `@Order` annotation or the Ordered interface.

This comparator extends the standard OrderComparator to provide annotation-aware ordering capabilities, making it the primary ordering mechanism throughout the Jetleaf framework for components that use declarative ordering via annotations.

### Order Resolution Strategy:

1. `@Order` Annotation: Highest precedence, directly specifies order value
2. `PriorityOrdered` Interface: Second highest precedence for programmatic control
3. `Ordered` Interface: Standard programmatic ordering
4. Default Fallback: Ordered.LOWEST_PRECEDENCE when no order specified

### Supported Types:

- Classes: Inspects `@Order` annotation and Ordered interface implementation
- Sources: Checks for `@Order` annotation on source elements
- Executables: Methods and constructors with parameter count as tiebreaker
- Direct Objects: Objects implementing Ordered or PriorityOrdered
- Raw Integers: Direct order values for programmatic use

### Framework Integration:

- Used in pod factory post-processor execution ordering
- Applied to application context initializer sorting
- Utilized for event listener ordering
- Employed in configuration class processing sequence

### Example:

    @Order(1)
    class HighPriorityService {
      // This service will be processed first due to @Order(1)
    }

    @Order(5)
    class MediumPriorityService {
      // Processed after HighPriorityService but before LowPriorityService
    }

    class LowPriorityService implements Ordered {
      @override
      int get order => 10; // Processed last
    }

    class DefaultPriorityService {
      // No order specified - uses LOWEST_PRECEDENCE (Integer.MAX_VALUE)
    }

    void main() {
      final comparator = AnnotationAwareOrderComparator();

      // Check order values
      final order1 = comparator.findOrder(Class<HighPriorityService>());
      print(order1); // 1

      final order2 = comparator.findOrder(Class<LowPriorityService>());
      print(order2); // 10

      final order3 = comparator.findOrder(Class<DefaultPriorityService>());
      print(order3); // 2147483647 (Ordered.LOWEST_PRECEDENCE)

      // Sort a list of classes by their order precedence
      final classes = [
        Class<LowPriorityService>(),
        Class<HighPriorityService>(),
        Class<DefaultPriorityService>(),
        Class<MediumPriorityService>()
      ];

      AnnotationAwareOrderComparator.sort(classes);

      // Classes are now sorted: High, Medium, Low, Default
      for (final cls in classes) {
        print('${cls.getSimpleName()}: ${comparator.findOrder(cls)}');
      }
    }

### Advanced Usage with Mixed Types:

    // Mix of different order specification methods
    final components = [
      Class<AnnotatedComponent>(),      // Uses @Order(2)
      ManualOrderComponent(),           // Implements Ordered returning 1
      Class<DefaultComponent>(),        // No order specified
      PriorityComponent(),              // Implements PriorityOrdered returning 0
      5                                 // Raw integer order value
    ];

    AnnotationAwareOrderComparator.sort(components);
    // Order: PriorityComponent (0), ManualOrderComponent (1),
    //        AnnotatedComponent (2), 5 (5), DefaultComponent (MAX_VALUE)

See also:

- OrderComparator for the base ordering implementation
- Ordered for the standard ordering interface
- PriorityOrdered for highest precedence ordering
- Order for the ordering annotation

Inheritance
  - Object
  - Comparator<Object>
  - OrderComparator
  - AnnotationAwareOrderComparator

## Constructors

AnnotationAwareOrderComparator.new()
  A Jetleaf-provided OrderComparator implementation that determines ordering based on the presence of the `@Order` annotation or the Ordered interface.

## Properties

hashCode → int
  The hash code for this object.
  no setter inherited
runtimeType → Type
  A representation of the runtime type of the object.
  no setter inherited

## Methods

compare(Object o1, Object o2) → int
  Compares two objects for order.
  inherited
compareTo(Object other) → int
  Allows this comparator to be compared with other objects.
  inherited
doCompare(Object? o1, Object? o2, [OrderSourceProvider? provider]) → int
  Internal comparison implementation that handles the core ordering logic.
  inherited
doGet(Object? obj) → int
  Internal method to resolve order value with fallback handling.
  inherited
doGetOrder(Object? obj) → int?
  Internal method to extract order value from various source types.
  inherited
findOrder(Object? obj) → int?
  Finds the order value for the given object using annotation-aware resolution.
getOrder(Object? obj, OrderSourceProvider? provider) → int
  Resolves the order value of the given object.
  inherited
getPriority(Object obj) → int?
  Optionally override this to expose a numeric "priority" classification.
  override
noSuchMethod(Invocation invocation) → dynamic
  Invoked when a nonexistent method or property is accessed.
  inherited
reversed() → Comparator<Object>
  Returns a comparator that imposes the reverse ordering of this comparator.
  inherited
thenComparing(Comparator<Object> other) → Comparator<Object>
  Chains another comparator to be used if this comparator returns 0 (equality).
  inherited
thenComparingComparable<U extends Comparable<U>>(U keyExtractor(Object)) → Comparator<Object>
  Chains a comparator by extracting a `Comparable` key from each element.
  inherited
thenComparingWith<U>(U keyExtractor(Object), Comparator<U> keyComparator) → Comparator<Object>
  Chains a comparator by extracting a key with `keyExtractor` and comparing it using the given `keyComparator`.
  inherited
toString() → String
  A string representation of this object.
  inherited
whenCompared(Object? o1, Object? o2) → int
  Compares two objects using annotation-aware ordering rules.
  override
withSource(OrderSourceProvider sourceProvider) → Comparator<Object>
  Returns a new comparator that uses the given OrderSourceProvider to determine order metadata indirectly from an associated source.
  inherited
withSourceProvider(OrderSourceProvider sourceProvider) → Comparable<Object>
  Configures this comparator instance to use the given OrderSourceProvider.
  inherited

## Operators

operator ==(Object other) → bool
  The equality operator.
  inherited

## Static Methods

reverseSort(List<Object> list) → void
  Sorts a list in reverse order according to annotation-aware rules.
sort(List<Object> list) → void
  Utility method to sort a list of objects according to Jetleaf's annotation and order-based rules.