OrderComparator class

A comparator that sorts objects based on the Ordered and PriorityOrdered interfaces.

This comparator is used throughout the JetLeaf framework to impose deterministic, precedence-based ordering on various components, processors, and infrastructure elements.

Ordering Hierarchy:

1. PriorityOrdered: Highest precedence, processed first
2. Ordered: Standard ordering based on order value
3. Default: Objects without ordering use Ordered.LOWEST_PRECEDENCE

Key Features:

• Deterministic Sorting: Consistent ordering across application runs
• Flexible Order Sources: Support for direct ordering and source providers
• Framework Integration: Used in pod processing, event handling, and configuration
• Thread Safety: Stateless design suitable for concurrent use

Basic Usage:

final items = [ComponentA(), ComponentB(), ComponentC()];
OrderComparator.sortList(items);

// Components are now sorted by their order precedence
for (final component in items) {
  print('${component.runtimeType}: ${OrderComparator.INSTANCE.getOrder(component)}');
}

Advanced Usage with Source Provider:

class MyOrderSourceProvider implements OrderSourceProvider {
  @override
  Object? getOrderSource(Object obj) {
    // Provide alternative order metadata for objects
    if (obj is MyComponent) {
      return obj.getMetadata().order;
    }
    return null;
  }
}

final comparator = OrderComparator.INSTANCE.withSourceProvider(MyOrderSourceProvider());
items.sort(comparator.compare);

Order Resolution Process:

1. Check if object implements PriorityOrdered (highest precedence)
2. Check if object implements Ordered
3. Use source provider if available for alternative order resolution
4. Fall back to Ordered.LOWEST_PRECEDENCE if no order information found

See also:

• Ordered for the standard ordering interface
• PriorityOrdered for highest precedence ordering
• OrderSourceProvider for indirect order resolution