# 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

Inheritance
  - Object
  - Comparator<Object>
  - OrderComparator
Implemented types
  - Comparable<Object>

## Constructors

OrderComparator.new()
  A comparator that sorts objects based on the Ordered and PriorityOrdered interfaces.

## 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.
  override
compareTo(Object other) → int
  Allows this comparator to be compared with other objects.
  override
doCompare(Object? o1, Object? o2, [OrderSourceProvider? provider]) → int
  Internal comparison implementation that handles the core ordering logic.
doGet(Object? obj) → int
  Internal method to resolve order value with fallback handling.
doGetOrder(Object? obj) → int?
  Internal method to extract order value from various source types.
getOrder(Object? obj, OrderSourceProvider? provider) → int
  Resolves the order value of the given object.
getPriority(Object obj) → int?
  Optionally override this to expose a numeric "priority" classification.
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 order metadata.
withSource(OrderSourceProvider sourceProvider) → Comparator<Object>
  Returns a new comparator that uses the given OrderSourceProvider to determine order metadata indirectly from an associated source.
withSourceProvider(OrderSourceProvider sourceProvider) → Comparable<Object>
  Configures this comparator instance to use the given OrderSourceProvider.

## Operators

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

## Static Properties

INSTANCE → OrderComparator
  Singleton instance of the OrderComparator.
  final

## Static Methods

sortArray(List<Object> array) → void
  Alias for sortList.
sortIfNecessary(Object? value) → void
  Sorts the given `value` if it's a `List<Object>`.
sortList(List<Object> list) → void
  Sorts the given `list` using this comparator.