Package org.apache.drill.common.exceptions

Class UserException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

org.apache.drill.common.exceptions.DrillRuntimeException

org.apache.drill.common.exceptions.UserException

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

UserRemoteException

public class UserException
extends DrillRuntimeException

Base class for all user exception. The goal is to separate out common error conditions where we can give users useful feedback.

Throwing a user exception will guarantee it's message will be displayed to the user, along with any context information added to the exception at various levels while being sent to the client.

A specific class of user exceptions are system exception. They represent system level errors that don't display any specific error message to the user apart from "A system error has occurred" along with information to retrieve the details of the exception from the logs.

Although system exception should only display a generic message to the user, for now they will display the root error message, until all user errors are properly sent from the server side.

Any thrown exception that is not wrapped inside a user exception will automatically be converted to a system exception before being sent to the client.

See Also:

• UserBitShared.DrillPBError.ErrorType
• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	UserException.Builder	Builder class for DrillUserException.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	MEMORY_ERROR_MSG

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	UserException(UserBitShared.DrillPBError.ErrorType errorType, String message, Throwable cause)

Method Summary

Modifier and Type	Method	Description
static UserException.Builder	connectionError()	Creates a new user exception builder.
static UserException.Builder	connectionError(Throwable cause)	Wraps the passed exception inside a connection error.
static UserException.Builder	dataReadError()	Creates a new user exception builder.
static UserException.Builder	dataReadError(Throwable cause)	Wraps the passed exception inside a data read error.
static UserException.Builder	dataWriteError()	Creates a new user exception builder .
static UserException.Builder	dataWriteError(Throwable cause)	Wraps the passed exception inside a data write error.
static UserException.Builder	executionError(Throwable cause)	Wraps an error that arises from execution due to issues in the query, in the environment and so on -- anything other than "this should never occur" type checks.
static UserException.Builder	functionError()	Creates a new user exception builder .
static UserException.Builder	functionError(Throwable cause)	Wraps the passed exception inside a function error.
String	getErrorId()
String	getErrorLocation()
UserBitShared.DrillPBError.ErrorType	getErrorType()
String	getMessage()	generates the message that will be displayed to the client without the stack trace.
String	getMessage(boolean includeErrorIdAndIdentity)
UserBitShared.DrillPBError	getOrCreatePBError(boolean verbose)	returns or creates a DrillPBError object corresponding to this user exception.
String	getOriginalMessage()
String	getVerboseMessage()	generates the message that will be displayed to the client.
String	getVerboseMessage(boolean includeErrorIdAndIdentity)
static UserException.Builder	internalError()
static UserException.Builder	internalError(Throwable cause)	Indicates an internal validation failed or similar unexpected error.
static UserException.Builder	memoryError()	Creates a RESOURCE error with a prebuilt message for out of memory exceptions
static UserException.Builder	memoryError(String format, Object... args)
static UserException.Builder	memoryError(Throwable cause)	Creates a RESOURCE error with a prebuilt message for out of memory exceptions
static UserException.Builder	parseError()	Creates a new user exception builder .
static UserException.Builder	parseError(Throwable cause)	Wraps the passed exception inside a parse error.
static UserException.Builder	permissionError()	creates a new user exception builder .
static UserException.Builder	permissionError(Throwable cause)	Wraps the passed exception inside a permission error.
static UserException.Builder	planError()	Creates a new user exception builder .
static UserException.Builder	planError(Throwable cause)	Wraps the passed exception inside a plan error.
static UserException.Builder	pluginError(Throwable cause)	Wraps the passed exception inside a plugin error.
UserException.Builder	rebuild()
static UserException.Builder	resourceError()	Creates a new user exception builder .
static UserException.Builder	resourceError(Throwable cause)	Wraps the passed exception inside a resource error.
static UserException.Builder	schemaChangeError()
static UserException.Builder	schemaChangeError(Throwable cause)	Report an unsupported schema change.
static UserException.Builder	systemError(Throwable cause)	Wraps the passed exception inside a system error.
static UserException.Builder	unspecifiedError(Throwable cause)	Indicates an unspecified error: code caught the exception, but does not have visibility into the cause well enough to pick one of the more specific error types.
static UserException.Builder	unsupportedError()	Creates a new user exception builder .
static UserException.Builder	unsupportedError(Throwable cause)	Wraps the passed exception inside a unsupported error.
static UserException.Builder	validationError()	Creates a new user exception builder .
static UserException.Builder	validationError(Throwable cause)	wraps the passed exception inside a validation error.

Methods inherited from class org.apache.drill.common.exceptions.DrillRuntimeException

checkInterrupted, create, create

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

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

Field Details

MEMORY_ERROR_MSG

public static final String MEMORY_ERROR_MSG

See Also:

• Constant Field Values

Constructor Details

UserException

protected UserException(UserBitShared.DrillPBError.ErrorType errorType,
 String message,
 Throwable cause)

Method Details

memoryError

public static UserException.Builder memoryError(Throwable cause)

Creates a RESOURCE error with a prebuilt message for out of memory exceptions

Parameters:

cause - exception that will be wrapped inside a memory error

Returns:

resource error builder

memoryError

public static UserException.Builder memoryError(String format,
 Object... args)

memoryError

public static UserException.Builder memoryError()

Creates a RESOURCE error with a prebuilt message for out of memory exceptions

Returns:

resource error builder

systemError

public static UserException.Builder systemError(Throwable cause)

Wraps the passed exception inside a system error.

The cause message will be used unless UserException.Builder.message(String, Object...) is called.

If the wrapped exception is, or wraps, a user exception it will be returned by UserException.Builder.build(Logger) instead of creating a new exception. Any added context will be added to the user exception as well.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.SYSTEM

connectionError

public static UserException.Builder connectionError()

Creates a new user exception builder.

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.CONNECTION

connectionError

public static UserException.Builder connectionError(Throwable cause)

Wraps the passed exception inside a connection error.

The cause message will be used unless UserException.Builder.message(String, Object...) is called.

If the wrapped exception is, or wraps, a user exception it will be returned by UserException.Builder.build(Logger) instead of creating a new exception. Any added context will be added to the user exception as well.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.CONNECTION

dataReadError

public static UserException.Builder dataReadError()

Creates a new user exception builder.

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.DATA_READ

dataReadError

public static UserException.Builder dataReadError(Throwable cause)

Wraps the passed exception inside a data read error.

The cause message will be used unless UserException.Builder.message(String, Object...) is called.

If the wrapped exception is, or wraps, a user exception it will be returned by UserException.Builder.build(Logger) instead of creating a new exception. Any added context will be added to the user exception as well.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.DATA_READ

dataWriteError

public static UserException.Builder dataWriteError()

Creates a new user exception builder .

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.DATA_WRITE

dataWriteError

public static UserException.Builder dataWriteError(Throwable cause)

Wraps the passed exception inside a data write error.

The cause message will be used unless UserException.Builder.message(String, Object...) is called.

If the wrapped exception is, or wraps, a user exception it will be returned by UserException.Builder.build(Logger) instead of creating a new exception. Any added context will be added to the user exception as well.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.DATA_WRITE

functionError

public static UserException.Builder functionError()

Creates a new user exception builder .

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.FUNCTION

functionError

public static UserException.Builder functionError(Throwable cause)

Wraps the passed exception inside a function error.

The cause message will be used unless UserException.Builder.message(String, Object...) is called.

If the wrapped exception is, or wraps, a user exception it will be returned by UserException.Builder.build(Logger) instead of creating a new exception. Any added context will be added to the user exception as well.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.FUNCTION

parseError

public static UserException.Builder parseError()

Creates a new user exception builder .

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.PARSE

parseError

public static UserException.Builder parseError(Throwable cause)

Wraps the passed exception inside a parse error.

The cause message will be used unless UserException.Builder.message(String, Object...) is called.

If the wrapped exception is, or wraps, a user exception it will be returned by UserException.Builder.build(Logger) instead of creating a new exception. Any added context will be added to the user exception as well.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.PARSE

validationError

public static UserException.Builder validationError()

Creates a new user exception builder .

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.VALIDATION

validationError

public static UserException.Builder validationError(Throwable cause)

wraps the passed exception inside a validation error.

the cause message will be used unless UserException.Builder.message(String, Object...) is called.

if the wrapped exception is, or wraps, a user exception it will be returned by UserException.Builder.build(Logger) instead of creating a new exception. Any added context will be added to the user exception as well.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.VALIDATION

permissionError

public static UserException.Builder permissionError()

creates a new user exception builder .

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.PERMISSION

permissionError

public static UserException.Builder permissionError(Throwable cause)

Wraps the passed exception inside a permission error.

The cause message will be used unless UserException.Builder.message(String, Object...) is called.

If the wrapped exception is, or wraps, a user exception it will be returned by UserException.Builder.build(Logger) instead of creating a new exception. Any added context will be added to the user exception as well.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.PERMISSION

planError

public static UserException.Builder planError()

Creates a new user exception builder .

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.PLAN

planError

public static UserException.Builder planError(Throwable cause)

Wraps the passed exception inside a plan error.

The cause message will be used unless UserException.Builder.message(String, Object...) is called.

If the wrapped exception is, or wraps, a user exception it will be returned by UserException.Builder.build(Logger) instead of creating a new exception. Any added context will be added to the user exception as well.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.PLAN

pluginError

public static UserException.Builder pluginError(Throwable cause)

Wraps the passed exception inside a plugin error.

The cause message will be used unless UserException.Builder.message(String, Object...) is called.

If the wrapped exception is, or wraps, a user exception it will be returned by UserException.Builder.build(Logger) instead of creating a new exception. Any added context will be added to the user exception as well.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.PLUGIN

resourceError

public static UserException.Builder resourceError()

Creates a new user exception builder .

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.RESOURCE

resourceError

public static UserException.Builder resourceError(Throwable cause)

Wraps the passed exception inside a resource error.

The cause message will be used unless UserException.Builder.message(String, Object...) is called.

If the wrapped exception is, or wraps, a user exception it will be returned by UserException.Builder.build(Logger) instead of creating a new exception. Any added context will be added to the user exception as well.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.RESOURCE

unsupportedError

public static UserException.Builder unsupportedError()

Creates a new user exception builder .

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.UNSUPPORTED_OPERATION

unsupportedError

public static UserException.Builder unsupportedError(Throwable cause)

Wraps the passed exception inside a unsupported error.

The cause message will be used unless UserException.Builder.message(String, Object...) is called.

If the wrapped exception is, or wraps, a user exception it will be returned by UserException.Builder.build(Logger) instead of creating a new exception. Any added context will be added to the user exception as well.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

See Also:

• UserBitShared.DrillPBError.ErrorType.UNSUPPORTED_OPERATION

schemaChangeError

public static UserException.Builder schemaChangeError(Throwable cause)

Report an unsupported schema change.

Parameters:

cause - the SchemaChangeException. (Not typed because that class is not visible to this package.)

Returns:

user exception builder.

schemaChangeError

public static UserException.Builder schemaChangeError()

executionError

public static UserException.Builder executionError(Throwable cause)

Wraps an error that arises from execution due to issues in the query, in the environment and so on -- anything other than "this should never occur" type checks.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

internalError

public static UserException.Builder internalError(Throwable cause)

Indicates an internal validation failed or similar unexpected error. Indicates the problem is likely within Drill itself rather than due to the environment, query, etc.

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

internalError

public static UserException.Builder internalError()

unspecifiedError

public static UserException.Builder unspecifiedError(Throwable cause)

Indicates an unspecified error: code caught the exception, but does not have visibility into the cause well enough to pick one of the more specific error types. In practice, using this exception indicates that error handling should be moved closer to the source of the exception so we can provide the user with a better explanation than "something went wrong."

Parameters:

cause - exception we want the user exception to wrap. If cause is, or wraps, a user exception it will be returned by the builder instead of creating a new user exception

Returns:

user exception builder

rebuild

public UserException.Builder rebuild()

getMessage

public String getMessage()

generates the message that will be displayed to the client without the stack trace.

Overrides:

getMessage in class Throwable

Returns:

non verbose error message

getMessage

public String getMessage(boolean includeErrorIdAndIdentity)

getOriginalMessage

public String getOriginalMessage()

Returns:

the error message that was passed to the builder

getVerboseMessage

public String getVerboseMessage()

generates the message that will be displayed to the client. The message also contains the stack trace.

Returns:

verbose error message

getVerboseMessage

public String getVerboseMessage(boolean includeErrorIdAndIdentity)

getOrCreatePBError

public UserBitShared.DrillPBError getOrCreatePBError(boolean verbose)

returns or creates a DrillPBError object corresponding to this user exception.

Parameters:

verbose - should the error object contain the verbose error message ?

Returns:

protobuf error object

getErrorId

public String getErrorId()

getErrorType

public UserBitShared.DrillPBError.ErrorType getErrorType()

getErrorLocation

public String getErrorLocation()