Class CodecException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
org.jwcarman.codec.CodecException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
InvalidPayloadException, InvalidValueException, TransientCodecException, UnsupportedFormatException
public class CodecException extends RuntimeException
The root of every failure a Codec reports from Codec.encode(T) or Codec.decode(byte[]).

This class is never thrown directly; it exists for the coarse catch (CodecException e) — "something went wrong in the codec". Its four subclasses are keyed to what the caller does next, and a catch for one of them is the precise form:

  • InvalidValueException — the value handed to encode cannot be encoded: fix the value or the configuration.
  • InvalidPayloadException — the payload handed to decode is malformed, corrupt, or forged: quarantine it.
  • UnsupportedFormatException — the payload is well-formed but this reader cannot handle it (a format version or algorithm it does not know): hold it, route it to a newer reader, or upgrade.
  • TransientCodecException — something the codec depends on failed; the input is not at fault: retry, or alert on infrastructure.

The rule for extending the hierarchy: subclass by what the caller does next. A failure with one of the four answers above is a subclass of that family, never a fifth sibling. A more specific subclass earns its existence only when it carries information the family does not.

Construction and configuration errors — a bad builder argument, a null mapper, a type a factory cannot create a codec for, a null passed to encode or decode — are programmer errors at wiring time and remain IllegalArgumentException, IllegalStateException and NullPointerException; they are not codec failures.

See Also:

  • Constructor Details

    • CodecException

      protected CodecException(String message)
      Creates a codec failure with the given message; for subclasses.
      Parameters:
      message - what went wrong, in plain words, never containing payload contents

    • CodecException

      protected CodecException(String message, Throwable cause)
      Creates a codec failure with the given message and cause; for subclasses.
      Parameters:
      message - what went wrong, in plain words, never containing payload contents
      cause - the underlying exception, typically the wrapped library's own