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