Package net.mezzdev.config.api.sorting

Interface ISortingConfig<T>

Type Parameters:
T - effectively immutable value type with stable equality and hash codes
@NonExtendable public interface ISortingConfig<T>
Stores a user's preferred order for values discovered at runtime.

Pass the currently available values to getSortedValues(Collection) whenever they need to be displayed. New values are inserted using the default comparator, missing values are ignored, and any user-hidden values remain hidden. Save edits with setSortedValues(Collection, List).

Create one through IConfigRegistration.createSortingConfig(String, Comparator, boolean). Use the serializer overload for mod-specific value types; those values must be immutable and have stable equality and serialization.

To import an order from an older file format, register a migrator with setLegacyMigration(java.util.List<java.nio.file.Path>, net.mezzdev.config.api.migration.ISortingConfigMigrator<T>) before the saved order is first used. Runtime methods and listener registration are thread-safe. Listener registrations normally live as long as this sorting config, which is usually the full mod lifetime, so callers may ignore their returned removal callbacks. Keep and run a removal callback when its listener captures a shorter-lived object, such as a screen, reloadable runtime, or connection-specific component.

Since:
0.1.0

  • Method Details

    • getSortedValues

      @Unmodifiable List<T> getSortedValues(Collection<T> allValues)
      Apply the saved user preference to the values currently available.
      Parameters:
      allValues - every value that may be sorted
      Returns:
      an unmodifiable, duplicate-free snapshot of the sorted visible values
      Throws:
      IllegalArgumentException - if the supplied values violate the serializer contract or the reconciled file-backed order cannot be safely serialized
      Since:
      0.1.0

    • getDefaultSortedValues

      @Unmodifiable List<T> getDefaultSortedValues(Collection<T> allValues)
      Sort the currently available values without applying the user's saved preference.
      Parameters:
      allValues - every value that may be sorted
      Returns:
      an unmodifiable, duplicate-free snapshot of the default sorted visible values
      Since:
      0.1.0

    • setSortedValues

      boolean setSortedValues(Collection<T> allValues, List<T> sortedValues)
      Save the user's preferred order for the values currently available.

      When removal is allowed, omitting an available value hides it. Otherwise omitted values remain visible and are appended in default order.

      Parameters:
      allValues - every value that may be sorted
      sortedValues - the non-null, duplicate-free sorted values to save
      Returns:
      true if the sort order changed, or false if it was equal to the saved sort order
      Throws:
      IllegalArgumentException - if a collection contains null, sortedValues contains duplicates, a value in sortedValues is not present in allValues, the serializer contract is violated, or the file-backed order cannot be safely serialized
      Since:
      0.1.0

    • getComparator

      Comparator<T> getComparator(Collection<T> allValues)
      Get a comparator that applies the saved preference to the currently available values.
      Parameters:
      allValues - every value that may be sorted
      Returns:
      a comparator using this sort order
      Since:
      0.1.0

    • isVisible

      boolean isVisible(Collection<T> allValues, T value)
      Return whether the user-visible order currently includes a value.
      Parameters:
      allValues - every value that may be sorted
      value - value to check
      Returns:
      true when the value is visible
      Since:
      0.1.0

    • allowsRemovingValues

      boolean allowsRemovingValues()
      Return whether users may hide values by removing them from their saved order.
      Since:
      0.1.0

    • addChangeListener

      Runnable addChangeListener(Runnable listener)
      Run code after the user's saved order changes.

      Use this to refresh a view that displays the sorted values. Callbacks run synchronously after the new order is active.

      Parameters:
      listener - callback to run after the sort order changes
      Returns:
      a callback that removes this listener
      Since:
      0.1.0

    • setLegacyMigration

      ISortingConfig<T> setLegacyMigration(List<Path> legacyPaths, ISortingConfigMigrator<T> migrator)
      Import a saved order from an older file when this sorting config does not have a destination file yet.

      Register this immediately after creating the sorting config, before calling methods that load or save its order. The paths are checked in order when the saved order is first needed. MezzConfig preserves and backs up the selected source, validates the migrated order, and saves it atomically in the current sorting format.

      Parameters:
      legacyPaths - ordered candidate legacy file paths; must not be empty
      migrator - callback that parses the selected file and supplies the migrated order
      Returns:
      this sorting config
      Throws:
      IllegalArgumentException - if the path list is empty, contains null or duplicate normalized paths, or a path cannot be converted to an absolute path
      IllegalStateException - if migration was already registered or the saved order was already loaded or changed
      Since:
      0.3.0
      See Also: