Package com.tino1b2be.dtmf.io

Class UnsupportedAudioFormatException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.io.IOException
com.tino1b2be.dtmf.io.UnsupportedAudioFormatException
All Implemented Interfaces:
Serializable
public class UnsupportedAudioFormatException extends IOException
Thrown when no AudioSourceProvider can open a given input, or when a provider that scored non-negative on AudioSourceProvider.canOpen(java.nio.file.Path) cannot in fact decode the file once it opens it (structural mismatch, unsupported compression code, malformed header after the magic-byte prefix, etc.).

This exception exists to distinguish "the bytes are not valid audio in a recognised format" from bare IOException ("the disk is broken," "the network timed out," "the file was deleted between stat and open"). Callers can catch UnsupportedAudioFormatException on its own to surface a helpful "unsupported format" message to end users, and let real I/O failures propagate to a separate handler (Requirement 6, Requirement 12.4). Because it extends IOException, code that only cares about the generic I/O failure case can still catch IOException and pick both up in one handler.

Diagnostics

When AudioSources.open(java.nio.file.Path) (or its InputStream/URL overloads) throws this exception because no provider was willing to open the input, providersConsulted() lists the AudioSourceProvider.formatName() of every provider that was asked to score the input, in discovery order, and providerScores() maps each consulted provider's format name to the SPI Priority Score it returned (Requirements 6.4, 6.5, 6.6). A provider whose canOpen threw an IOException is recorded with a score of -1. Providers that were not consulted (e.g. because none are registered on the classpath) do not appear in either collection.

When a AudioSourceProvider constructs and throws this exception itself from inside open(...) — for example, the WAV provider rejecting a μ-law compressed file after the magic bytes matched — providersConsulted() and providerScores() are both empty (Requirement 6.4: "empty list when no providers were consulted"). Only AudioSources populates the diagnostics collections; they are not part of the public constructor surface.

Thread safety and immutability

Instances are immutable after construction. The collections returned from providersConsulted() and providerScores() are unmodifiable views over defensively-copied snapshots, so handing a caught exception to multiple consumers is safe; attempting to mutate the returned collections throws UnsupportedOperationException.
Since:
2.1.0
See Also:

  • Constructor Details

    • UnsupportedAudioFormatException

      public UnsupportedAudioFormatException(String message)
      Construct an UnsupportedAudioFormatException with the given detail message and no cause. providersConsulted() and providerScores() are both empty immutable collections (Requirement 6.4: "empty list when no providers were consulted").
      Parameters:
      message - detail message; may be null

    • UnsupportedAudioFormatException

      public UnsupportedAudioFormatException(String message, Throwable cause)
      Construct an UnsupportedAudioFormatException wrapping an underlying cause. providersConsulted() and providerScores() are both empty immutable collections.
      Parameters:
      message - detail message; may be null
      cause - underlying cause; may be null

  • Method Details

    • providersConsulted

      public List<String> providersConsulted()
      Format names of every AudioSourceProvider that was asked to score the input, in ServiceLoader discovery order (Requirement 6.4).

      Returns an empty list when this exception was constructed via one of the public constructors (e.g. thrown from inside a provider's open(...) method) rather than by AudioSources.

      Returns:
      immutable list of consulted provider format names; never null

    • providerScores

      public Map<String,Integer> providerScores()
      Score returned by each consulted AudioSourceProvider, keyed by formatName() (Requirement 6.5).

      A provider whose canOpen threw an IOException is recorded here with a value of -1 (the score AudioSources assigns to any failing or not-applicable provider). Returns an empty map when this exception was not constructed by AudioSources.

      Returns:
      immutable map of provider format name to SPI Priority Score; never null