Package com.tino1b2be.dtmf.io.internal

Record Class ProviderScore

java.lang.Object
java.lang.Record
com.tino1b2be.dtmf.io.internal.ProviderScore
Record Components:
provider - the provider this score belongs to; never null
score - the SPI Priority Score returned by AudioSourceProvider.canOpen(java.nio.file.Path): an integer in [0, 100] when the provider is applicable, or -1 when it declined (including the case where canOpen threw an IOException that AudioSources caught and logged per Requirement 5.9)
priority - the value of AudioSourceProvider.priority() at the time of scoring, used as the tie-breaker when two providers return the same score
public record ProviderScore(AudioSourceProvider provider, int score, int priority) extends Record
Scoring bookkeeping for a single AudioSourceProvider during the content-based dispatch performed by AudioSources.open(...). Pairs a provider with the SPI Priority Score it returned from AudioSourceProvider.canOpen(java.nio.file.Path) and the priority() value captured at scoring time so the tie-break (Requirement 5.6) is decided from a single, consistent snapshot.

Extracting this tuple keeps AudioSources's scoring loop readable: the facade collects one ProviderScore per provider it consults, filters out the non-applicable ones (score < 0), and picks the winner with java.util.Collections.max(eligible, BY_SCORE_THEN_PRIORITY). The full list of ProviderScores also feeds the diagnostic population on UnsupportedAudioFormatException (Requirements 6.4, 6.5, 6.6) when every provider returned -1.

This class is not part of the published API. It lives in com.tino1b2be.dtmf.io.internal, whose stability contract (see the package Javadoc) explicitly allows breakage between any two releases. It is public at the type level purely so AudioSources — which lives in the parent package and cannot otherwise see a package-private type here — can reach it; external callers MUST NOT depend on it.

Since:
2.1.0

  • Field Details

    • BY_SCORE_THEN_PRIORITY

      public static final Comparator<ProviderScore> BY_SCORE_THEN_PRIORITY
      Ordering used to pick the winning provider during dispatch (Requirement 5.6). Orders ascending first by score() and then, on ties, ascending by priority() — so the greatest pair under this ordering is the provider that returned the strictly greatest SPI Priority Score, tie-broken by the greatest priority() value.

      Typical use in AudioSources: 

      
 ProviderScore winner = Collections.max(eligible, ProviderScore.BY_SCORE_THEN_PRIORITY);

      When two ProviderScores are equal under both score and priority, the comparator returns zero; in that case AudioSources picks the earlier entry in discovery order simply because Collections.max returns the last maximal element while the scoring loop encounters the providers in discovery order — but the whole system does not depend on which way that coin lands, since two providers genuinely indistinguishable by this ordering are, by construction, equally valid choices.

  • Constructor Details

    • ProviderScore

      public ProviderScore(AudioSourceProvider provider, int score, int priority)
      Compact constructor enforcing that provider is non-null.
      Throws:
      NullPointerException - if provider is null

  • Method Details

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • provider

      public AudioSourceProvider provider()
      Returns the value of the provider record component.
      Returns:
      the value of the provider record component

    • score

      public int score()
      Returns the value of the score record component.
      Returns:
      the value of the score record component

    • priority

      public int priority()
      Returns the value of the priority record component.
      Returns:
      the value of the priority record component