net.degreedays.api

Class FailureException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

net.degreedays.api.DegreeDaysApiException

net.degreedays.api.FailureException

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

RequestFailureException, SourceDataException

public abstract class FailureException
extends DegreeDaysApiException

Superclass of exceptions that indicate a Failure in the API's processing of all or part of a request.

Apart from TransportException, all subclasses of DegreeDaysApiException are subclasses of FailureException, and carry a coded Failure which originates from the server-side processing of an API request.

Most types of FailureException extend RequestFailureException, which indicates that the API servers completely failed to process an API request (sending back only a Failure as their response). But a failure doesn't have to relate to a full request - it is possible for parts of a request to work and parts to fail. Right now the only example of this is SourceDataException which indicates that the API servers failed to generate a specific set of data as part of a batch request.

isDueToXXX() methods on subclasses of FailureException

Some of the subclasses of FailureException have isDueToXXX()-style methods. These work by inspecting the failure code of the Failure object that the exception carries.

The isDueToXXX() methods follow a simple pattern: they will always return true if the failure code starts with the XXX part of the method name. So, for example, ServiceException.isDueToServiceTemporarilyDown() will return true if the code is "ServiceTemporarilyDown" or "ServiceTemporarilyDownForPostalCodeLookups" (a failure code that isn't actually in use at the time of writing, but that may come into use at some point in the future).

If you're checking isDueToXXX() methods, bear in mind that it's possible for none of them to return true. This client library doesn't expose all possible failure codes through the isDueToXXX() methods, only the ones that are likely to arise through use of the client library, and only the ones that were defined at the time this version of the client library was released. New codes may be added into the API over time, and they shouldn't cause incompaiblities with code that you've already written to test the existing isDueToXXX() methods.

In a nutshell: when writing code that tests isDueToXXX() methods (e.g. to decide what message to show in a UI), make sure that your code will work well if none of those methods return true.

This abstract class is not designed to be extended by third-party code, which is why it does not have an accessible constructor.

Method Summary

Modifier and Type	Method and Description
Failure	failure() Returns the non-null Failure object containing details of the failure on the API's servers that led to this exception on the client.
java.lang.String	getMessage() Overridden to return the failure() details as the exception message.

Methods inherited from class java.lang.Throwable

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

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

failure

public final Failure failure()

Returns the non-null Failure object containing details of the failure on the API's servers that led to this exception on the client.

getMessage

public java.lang.String getMessage()

Overridden to return the failure() details as the exception message.

Overrides:

getMessage in class java.lang.Throwable