Class QueryException

  • All Implemented Interfaces:
    Serializable, SanitizableException
    Direct Known Subclasses:
    BadQueryException, QueryCapacityExceededException, QueryInterruptedException, QueryTimeoutException, QueryUnsupportedException

    public class QueryException
    extends RuntimeException
    implements SanitizableException
    Base serializable error response.

    The Object Model that QueryException follows is a little non-intuitive as the primary way that a QueryException is generated is through a child class. However, those child classes are *not* equivalent to a QueryException, instead they act as a Factory of QueryException objects. This can be seen in two different places.

    1. When sanitize() is called, the response is a QueryException without any indication of which original exception occurred. 2. When these objects get serialized across the wire the recipient deserializes a QueryException. The client is never expected, and fundamentally is not allowed to, ever deserialize a child class of QueryException.

    For this reason, QueryException must contain all potential state that any of its child classes could ever want to push across the wire. Additionally, any catch clauses expecting one of the child Exceptions must know that it is running inside of code where the exception has not traveled across the wire. If there is a chance that the exception could have been serialized across the wire, the code must catch a QueryException and check the errorCode instead.

    As a corollary, adding new state or adjusting the logic of this class must always be done in a backwards-compatible fashion across all child classes of QueryException.

    If there is any need to do different logic based on the type of error that has happened, the only reliable method of discerning the type of the error is to look at the errorCode String. Because these Strings are considered part of the API, they are not allowed to change and must maintain their same semantics. The known errorCode Strings are pulled together as public static fields on this class in order to make it more clear what options exist.

    QueryResource and SqlResource are expected to emit the JSON form of this object when errors happen.

    See Also:
    Serialized Form