com.datastax.oss.driver.api.core

Class DriverException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

com.datastax.oss.driver.api.core.DriverException

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

AllNodesFailedException, BusyConnectionException, ClosedConnectionException, ConnectionInitException, CoordinatorException, CrcMismatchException, DriverExecutionException, DriverTimeoutException, FrameTooLongException, HeartbeatException, InvalidKeyspaceException, MapperException, RequestThrottlingException, UnsupportedProtocolVersionException

public abstract class DriverException
extends RuntimeException

Base class for all exceptions thrown by the driver.

Note that, for obvious programming errors, the driver might throw JDK runtime exceptions, such as IllegalArgumentException or IllegalStateException. In all other cases, it will be an instance of this class.

One special case is when the driver tried multiple nodes to complete a request, and they all failed; the error returned to the client will be an AllNodesFailedException, which wraps a map of errors per node.

Some implementations make the stack trace not writable to improve performance (see Throwable.Throwable(String, Throwable, boolean, boolean)). This is only done when the exception is thrown in a small number of well-known cases, and the stack trace wouldn't add any useful information (for example, server error responses). Instances returned by copy() always have a stack trace.

See Also:

Serialized Form

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DriverException(String message, ExecutionInfo executionInfo, Throwable cause, boolean writableStackTrace)

Method Summary

Modifier and Type	Method and Description
abstract DriverException	copy() Copy the exception.
ExecutionInfo	getExecutionInfo() Returns execution information about the request that led to this error.
void	setExecutionInfo(ExecutionInfo executionInfo) This is for internal use by the driver, a client application has no reason to call it.

Methods inherited from class java.lang.Throwable

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

Methods inherited from class java.lang.Object

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

Constructor Detail

DriverException

protected DriverException(@Nullable
                          String message,
                          @Nullable
                          ExecutionInfo executionInfo,
                          @Nullable
                          Throwable cause,
                          boolean writableStackTrace)

Method Detail

getExecutionInfo

public ExecutionInfo getExecutionInfo()

Returns execution information about the request that led to this error.

This is similar to the information returned for a successful query in ResultSet, except that some fields may be absent:

• ExecutionInfo.getCoordinator() may be null if the error occurred before any node was contacted;
• ExecutionInfo.getErrors() will contain the errors encountered for other nodes, but not this error itself;
• ExecutionInfo.getSuccessfulExecutionIndex() may be -1 if the error occurred before any execution was started;
• ExecutionInfo.getPagingState() and ExecutionInfo.getTracingId() will always be null;
• ExecutionInfo.getWarnings() and ExecutionInfo.getIncomingPayload() will always be empty;
• ExecutionInfo.isSchemaInAgreement() will always be true;
• ExecutionInfo.getResponseSizeInBytes() and ExecutionInfo.getCompressedResponseSizeInBytes() will always be -1.

Note that this is only set for exceptions that are rethrown directly to the client from a session call. For example, individual node errors stored in AllNodesFailedException.getAllErrors() or ExecutionInfo.getErrors() do not contain their own execution info, and therefore return null from this method.

This method will also return null for low-level exceptions thrown directly from a driver channel, such as ConnectionInitException or ClosedConnectionException.

It will also be null if you serialize and deserialize an exception.

setExecutionInfo

public void setExecutionInfo(ExecutionInfo executionInfo)

This is for internal use by the driver, a client application has no reason to call it.

copy

@NonNull
public abstract DriverException copy()

Copy the exception.

This returns a new exception, equivalent to the original one, except that because a new object is created in the current thread, the top-most element in the stacktrace of the exception will refer to the current thread. The original exception may or may not be included as the copy's cause, depending on whether that is deemed useful (this is left to the discretion of each implementation).

This is intended for the synchronous wrapper methods of the driver, in order to produce a more user-friendly stack trace (that includes the line in the user code where the driver rethrew the error).