net.degreedays.api

Class Failure

java.lang.Object

net.degreedays.api.Failure

All Implemented Interfaces:

java.io.Serializable

public final class Failure
extends java.lang.Object
implements java.io.Serializable

Contains details of a failure in the server-side processing of all or part of an API request.

Failure codes

Every failure has a code() that indicates the cause of the failure.

These codes are named in a hierarchical way. For example, if a failure is caused by an invalid request, its code will begin with "InvalidRequest". The idea is that you can quickly test for broader types of failure code without having to know or itemize all the sub-types (like "InvalidRequestAccount" and "InvalidRequestSignature").

New codes may be added into the API at any time. New codes might be sub-types of existing types (like if "InvalidRequestSomeNewCode" was added as a sub-type of "InvalidRequest"), or they might be completely new (like "SomeCompletelyNewCode"). If you're writing logic that checks for different failure codes, make sure that it won't blow up if it comes across a code that it doesn't recognize. (Though note that you probably won't need to write such logic if you're making your API requests through DegreeDaysApi, since that will automatically wrap failures up into appropriate exceptions.)

You are unlikely to need to deal with failure codes directly, as API methods like DataApi.getLocationData(LocationDataRequest) and DataSets.get(DataSpec) will automatically turn any failure codes into appropriate subclasses of FailureException.

See Also:

FailureException

Instances of this class are immutable. You can safely reuse them and call them from multiple threads at once.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Failure.Builder A builder class for creating immutable Failure objects e.g. for testing purposes.

Method Summary

Modifier and Type	Method and Description
java.lang.String	code() Returns the non-null, non-empty code associated with this failure.
boolean	equals(java.lang.Object o) A Failure can only be equal to another Failure with an equal code() and message().
int	hashCode() Overridden to ensure consistency with equals.
java.lang.String	message() Returns the non-null, non-empty message associated with this failure, providing explanatory information about the code() and what went wrong.
java.lang.String	toString() Returns a non-null, non-empty string representation of this object for logging and debugging purposes.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

code

public final java.lang.String code()

Returns the non-null, non-empty code associated with this failure.

See Also:

failure codes

message

public final java.lang.String message()

Returns the non-null, non-empty message associated with this failure, providing explanatory information about the code() and what went wrong.

The format of messages, and any details contained within them, are unspecified and subject to change. By all means use them for logging and display purposes, but please don't parse specific details from them. If you need programmatic access to information that is only available in a message, please let us know so we can think about how we could make that information available in another format.

equals

public boolean equals(java.lang.Object o)

A Failure can only be equal to another Failure with an equal code() and message(). Note that you might sometimes want to compare just the codes for equality, like failure1.code().equals(failure2.code()).

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overridden to ensure consistency with equals.

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Returns a non-null, non-empty string representation of this object for logging and debugging purposes.

The exact details of the representation are unspecified and subject to change.

Overrides:

toString in class java.lang.Object