Package org.apache.sis.util

## Class CorruptedObjectException

- Object
- - Throwable
  - - Exception
    - - RuntimeException
      - - CorruptedObjectException

- All Implemented Interfaces:
    `Serializable`

      public class CorruptedObjectException
      extends RuntimeException

  May be thrown on attempt to use an object which has been corrupted by a previous operation. Apache SIS throws this exception only on a best effort basis, when it detected an object in an inconsistent state after the original problem.
  Analogy: this exception has a similar goal than `ConcurrentModificationException`: to reduce the risk of non-deterministic behavior at an undetermined time in the future after an event has compromised the data integrity. Like `ConcurrentModificationException`, this `CorruptedObjectException` should be used only to detect bugs; it would be wrong to write a program that depends on this exception for its correctness.

  This exception is different than `AssertionError` in that `CorruptedObjectException` is not necessarily caused by a bug in the library. An object may become corrupted because of external factors, as illustrated in the use cases below.

  Some use cases for this exception are:
  - Attempt to use an aborted calculation:
    if an operation failed in the middle of a structural modification, some specific exception (not this `CorruptedObjectException`) should be thrown and the object discarded. But if the user does not discard the object and try to use it again, unpredictable behavior may happen. Some implementations are robust enough for detecting such unsafe usage: their methods may throw this `CorruptedObjectException` on attempt to use the object after the original failure.
  - Change in an “immutable” object:
    some objects are expected to be immutable. For example the same Coordinate Reference System (CRS) instance is typically shared by thousands of objects. However `CoordinateReferenceSystem` is an interface, Therefore, nothing prevent users from providing a mutable instance. For example if the value returned by `CoordinateSystem​.getDimension()` changes between two invocations, many objects that use that coordinate system will fall in an inconsistent state. If an operation detects such inconsistency, it may throw this `CorruptedObjectException`.
  Exception cause
  Since this exception may be thrown an undetermined amount of time after the data corruption, the root cause is often unknown at this point. Sometime a more descriptive exception has been thrown earlier, but may have been ignored by the user.
  Since:
    0.5
  See Also:
    Serialized Form

  Defined in the `sis-utility` module

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `CorruptedObjectException()` | Constructs a new exception with no message.
    `CorruptedObjectException​(Exception cause)` | Constructs a new exception with the specified cause.
    `CorruptedObjectException​(String message)` | Constructs a new exception with the specified detail message.
    `CorruptedObjectException​(IdentifiedObject object)` | Constructs a new exception with the name of the given object.

  - ### Method Summary

    - ### Methods inherited from class Throwable

      `addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString`

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### CorruptedObjectException

          public CorruptedObjectException()

      Constructs a new exception with no message.

    - #### CorruptedObjectException

          public CorruptedObjectException​(String message)

      Constructs a new exception with the specified detail message.
      Parameters:
        `message` - the detail message, or `null` if none.

    - #### CorruptedObjectException

          public CorruptedObjectException​(Exception cause)

      Constructs a new exception with the specified cause.
      Parameters:
        `cause` - the cause, or `null` if none.
      Since:
        1.0

    - #### CorruptedObjectException

          public CorruptedObjectException​(IdentifiedObject object)

      Constructs a new exception with the name of the given object.
      Parameters:
        `object` - the corrupted object, or `null` if unknown.
      Since:
        0.6