Package org.opensearch

Class OpenSearchException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

org.opensearch.OpenSearchException

All Implemented Interfaces:

Serializable, Writeable, ToXContent, ToXContentFragment

Direct Known Subclasses:

CircuitBreakingException, IndexShardSnapshotException, NotSerializableExceptionWrapper, OpenSearchParseException, ParsingException, TaskCancelledException

@PublicApi(since="1.0.0")
public class OpenSearchException
extends RuntimeException
implements Writeable, ToXContentFragment

A core library base class for all opensearch exceptions.

See Also:

• Serialized Form

Opensearch.api:

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	OpenSearchException.OpenSearchExceptionHandle	This is the list of Exceptions OpenSearch can throw over the wire or save into a corruption marker.
static class	OpenSearchException.OpenSearchExceptionHandleRegistry	Registry of ExceptionHandlers

Nested classes/interfaces inherited from interface org.opensearch.core.xcontent.ToXContent

ToXContent.DelegatingMapParams, ToXContent.MapParams, ToXContent.Params

Nested classes/interfaces inherited from interface org.opensearch.core.common.io.stream.Writeable

Writeable.Reader<V>, Writeable.WriteableRegistry, Writeable.Writer<V>

Field Summary

Fields

Modifier and Type	Field	Description
protected final Map<String,List<String>>	headers
protected final Map<String,List<String>>	metadata
static final String	REST_EXCEPTION_SKIP_STACK_TRACE	Passed in the ToXContent.Params of generateThrowableXContent(XContentBuilder, ToXContent.Params, Throwable) to control if the stack_trace element should render.
static final boolean	REST_EXCEPTION_SKIP_STACK_TRACE_DEFAULT
static final String	STACK_TRACE
protected static final Version	UNKNOWN_VERSION_ADDED

Fields inherited from interface org.opensearch.core.xcontent.ToXContent

EMPTY_PARAMS

Constructor Summary

Constructors

Constructor	Description
OpenSearchException(String msg, Object... args)	Construct a OpenSearchException with the specified detail message.
OpenSearchException(String msg, Throwable cause, Object... args)	Construct a OpenSearchException with the specified detail message and nested exception.
OpenSearchException(Throwable cause)	Construct a OpenSearchException with the specified cause exception.
OpenSearchException(StreamInput in)

Method Summary

Modifier and Type	Method	Description
void	addHeader(String key, String... value)	Adds a new header with the given key.
void	addHeader(String key, List<String> value)	Adds a new header with the given key.
void	addMetadata(String key, String... values)	Adds a new piece of metadata with the given key.
void	addMetadata(String key, List<String> values)	Adds a new piece of metadata with the given key.
static OpenSearchException	failureFromXContent(XContentParser parser)	Parses the output of generateFailureXContent(XContentBuilder, Params, Exception, boolean)
static OpenSearchException	fromXContent(XContentParser parser)	Generate a OpenSearchException from a XContentParser.
static void	generateFailureXContent(XContentBuilder builder, ToXContent.Params params, Exception e, boolean detailed)	Render any exception as a xcontent, encapsulated within a field or object named "error".
static void	generateThrowableXContent(XContentBuilder builder, ToXContent.Params params, Throwable t)	Static toXContent helper method that renders OpenSearchException or Throwable instances as XContent, delegating the rendering to toXContent(XContentBuilder, ToXContent.Params) or innerToXContent(XContentBuilder, ToXContent.Params, Throwable, String, String, Map, Map, Throwable).
String	getDetailedMessage()	Return the detail message, including the message from the nested exception if there is one.
protected String	getExceptionName()
static String	getExceptionName(Throwable ex)	Returns an underscore case name for the given exception.
static String	getExceptionSimpleClassName(Throwable ex)
List<String>	getHeader(String key)	Returns the list of header values for the given key or null if no header for the given key exists.
Set<String>	getHeaderKeys()	Returns a set of all header keys on this exception
protected Map<String,List<String>>	getHeaders()
static int	getId(Class<? extends OpenSearchException> exception)	Returns the serialization id the given exception.
Index	getIndex()
protected Map<String,List<String>>	getMetadata()
List<String>	getMetadata(String key)	Returns the list of metadata values for the given key or null if no metadata for the given key exists.
Set<String>	getMetadataKeys()	Returns a set of all metadata keys on this exception
List<String>	getResourceId()
String	getResourceType()
Throwable	getRootCause()	Retrieve the innermost cause of this exception, if none, returns the current exception.
ShardId	getShardId()
OpenSearchException[]	guessRootCauses()	Returns the root cause of this exception or multiple if different shards caused different exceptions
static OpenSearchException[]	guessRootCauses(Throwable t)	Returns the root cause of this exception or multiple if different shards caused different exceptions.
protected static void	headerToXContent(XContentBuilder builder, String key, List<String> values)
static OpenSearchException	innerFromXContent(XContentParser parser, boolean parseRootCauses)
protected static void	innerToXContent(XContentBuilder builder, ToXContent.Params params, Throwable throwable, String type, String message, Map<String,List<String>> headers, Map<String,List<String>> metadata, Throwable cause)
static boolean	isRegistered(Class<? extends Throwable> exception, Version version)	Returns true iff the given class is a registered for an exception to be read.
protected void	metadataToXContent(XContentBuilder builder, ToXContent.Params params)	Renders additional per exception information into the XContent
static <T extends StreamInput> OpenSearchException	readException(T input, int id)
static <T extends Throwable> T	readStackTrace(T throwable, StreamInput in)	Deserializes stacktrace elements as well as suppressed exceptions from the given output stream and adds it to the given exception.
void	setIndex(String index)
void	setIndex(Index index)
void	setResources(String type, String... id)
void	setShard(ShardId shardId)
RestStatus	status()	Returns the rest status code associated with this exception.
String	toString()
XContentBuilder	toXContent(XContentBuilder builder, ToXContent.Params params)
Throwable	unwrapCause()	Unwraps the actual cause from the exception for cases when the exception is a OpenSearchWrapperException.
static <S extends StreamOutput, T extends Throwable> T	writeStackTraces(T throwable, StreamOutput out, Writeable.Writer<Throwable> exceptionWriter)	Serializes the given exceptions stacktrace elements as well as it's suppressed exceptions to the given output stream.
void	writeTo(StreamOutput out)	Write this into the StreamOutput.

Methods inherited from class java.lang.Throwable

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

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.opensearch.core.xcontent.ToXContentFragment

isFragment

Field Details

UNKNOWN_VERSION_ADDED

protected static final Version UNKNOWN_VERSION_ADDED

REST_EXCEPTION_SKIP_STACK_TRACE

public static final String REST_EXCEPTION_SKIP_STACK_TRACE

Passed in the ToXContent.Params of generateThrowableXContent(XContentBuilder, ToXContent.Params, Throwable) to control if the stack_trace element should render. Unlike most parameters to toXContent methods this parameter is internal only and not available as a URL parameter. Use the error_trace parameter instead.

See Also:

• Constant Field Values

REST_EXCEPTION_SKIP_STACK_TRACE_DEFAULT

public static final boolean REST_EXCEPTION_SKIP_STACK_TRACE_DEFAULT

See Also:

• Constant Field Values

STACK_TRACE

public static final String STACK_TRACE

See Also:

• Constant Field Values

metadata

protected final Map<String,List<String>> metadata

headers

protected final Map<String,List<String>> headers

Constructor Details

OpenSearchException

public OpenSearchException(Throwable cause)

Construct a OpenSearchException with the specified cause exception.

OpenSearchException

public OpenSearchException(String msg,
 Object... args)

Construct a OpenSearchException with the specified detail message.

The message can be parameterized using {} as placeholders for the given arguments

Parameters:

msg - the detail message

args - the arguments for the message

OpenSearchException

public OpenSearchException(String msg,
 Throwable cause,
 Object... args)

Construct a OpenSearchException with the specified detail message and nested exception.

The message can be parameterized using {} as placeholders for the given arguments

Parameters:

msg - the detail message

cause - the nested exception

args - the arguments for the message

OpenSearchException

public OpenSearchException(StreamInput in)
                    throws IOException

Throws:

IOException

Method Details

writeTo

public void writeTo(StreamOutput out)
             throws IOException

Description copied from interface: Writeable

Write this into the StreamOutput.

Specified by:

writeTo in interface Writeable

Throws:

IOException

addMetadata

public void addMetadata(String key,
 String... values)

Adds a new piece of metadata with the given key. If the provided key is already present, the corresponding metadata will be replaced

addMetadata

public void addMetadata(String key,
 List<String> values)

Adds a new piece of metadata with the given key. If the provided key is already present, the corresponding metadata will be replaced

getMetadataKeys

public Set<String> getMetadataKeys()

Returns a set of all metadata keys on this exception

getMetadata

public List<String> getMetadata(String key)

Returns the list of metadata values for the given key or null if no metadata for the given key exists.

getMetadata

protected Map<String,List<String>> getMetadata()

addHeader

public void addHeader(String key,
 List<String> value)

Adds a new header with the given key. This method will replace existing header if a header with the same key already exists

addHeader

public void addHeader(String key,
 String... value)

Adds a new header with the given key. This method will replace existing header if a header with the same key already exists

getHeaderKeys

public Set<String> getHeaderKeys()

Returns a set of all header keys on this exception

getHeader

public List<String> getHeader(String key)

Returns the list of header values for the given key or null if no header for the given key exists.

getHeaders

protected Map<String,List<String>> getHeaders()

status

public RestStatus status()

Returns the rest status code associated with this exception.

unwrapCause

public Throwable unwrapCause()

Unwraps the actual cause from the exception for cases when the exception is a OpenSearchWrapperException.

See Also:

• ExceptionsHelper.unwrapCause(Throwable)

getDetailedMessage

public String getDetailedMessage()

Return the detail message, including the message from the nested exception if there is one.

getRootCause

public Throwable getRootCause()

Retrieve the innermost cause of this exception, if none, returns the current exception.

readException

public static <T extends StreamInput>
OpenSearchException readException(T input,
 int id)
                           throws IOException

Throws:

IOException

isRegistered

public static boolean isRegistered(Class<? extends Throwable> exception,
 Version version)

Returns true iff the given class is a registered for an exception to be read.

getId

public static int getId(Class<? extends OpenSearchException> exception)

Returns the serialization id the given exception.

toXContent

public XContentBuilder toXContent(XContentBuilder builder,
 ToXContent.Params params)
                           throws IOException

Specified by:

toXContent in interface ToXContent

Throws:

IOException

innerToXContent

protected static void innerToXContent(XContentBuilder builder,
 ToXContent.Params params,
 Throwable throwable,
 String type,
 String message,
 Map<String,List<String>> headers,
 Map<String,List<String>> metadata,
 Throwable cause)
                               throws IOException

Throws:

IOException

headerToXContent

protected static void headerToXContent(XContentBuilder builder,
 String key,
 List<String> values)
                                throws IOException

Throws:

IOException

metadataToXContent

protected void metadataToXContent(XContentBuilder builder,
 ToXContent.Params params)
                           throws IOException

Renders additional per exception information into the XContent

Throws:

IOException

fromXContent

public static OpenSearchException fromXContent(XContentParser parser)
                                        throws IOException

Generate a OpenSearchException from a XContentParser. This does not return the original exception type (ie NodeClosedException for example) but just wraps the type, the reason and the cause of the exception. It also recursively parses the tree structure of the cause, returning it as a tree structure of OpenSearchException instances.

Throws:

IOException

innerFromXContent

public static OpenSearchException innerFromXContent(XContentParser parser,
 boolean parseRootCauses)
                                             throws IOException

Throws:

IOException

generateThrowableXContent

public static void generateThrowableXContent(XContentBuilder builder,
 ToXContent.Params params,
 Throwable t)
                                      throws IOException

Static toXContent helper method that renders OpenSearchException or Throwable instances as XContent, delegating the rendering to toXContent(XContentBuilder, ToXContent.Params) or innerToXContent(XContentBuilder, ToXContent.Params, Throwable, String, String, Map, Map, Throwable).

This method is usually used when the Throwable is rendered as a part of another XContent object, and its result can be parsed back using the OpenSearchException.fromXContent(XContentParser) method.

Throws:

IOException

generateFailureXContent

public static void generateFailureXContent(XContentBuilder builder,
 ToXContent.Params params,
 @Nullable
 Exception e,
 boolean detailed)
                                    throws IOException

Render any exception as a xcontent, encapsulated within a field or object named "error". The level of details that are rendered depends on the value of the "detailed" parameter: when it's false only a simple message based on the type and message of the exception is rendered. When it's true all detail are provided including guesses root causes, cause and potentially stack trace.

This method is usually used when the Exception is rendered as a full XContent object, and its output can be parsed by the #OpenSearchException.failureFromXContent(XContentParser) method.

Throws:

IOException

failureFromXContent

public static OpenSearchException failureFromXContent(XContentParser parser)
                                               throws IOException

Parses the output of generateFailureXContent(XContentBuilder, Params, Exception, boolean)

Throws:

IOException

guessRootCauses

public OpenSearchException[] guessRootCauses()

Returns the root cause of this exception or multiple if different shards caused different exceptions

guessRootCauses

public static OpenSearchException[] guessRootCauses(Throwable t)

Returns the root cause of this exception or multiple if different shards caused different exceptions. If the given exception is not an instance of OpenSearchException an empty array is returned.

getExceptionName

protected String getExceptionName()

getExceptionName

public static String getExceptionName(Throwable ex)

Returns an underscore case name for the given exception. This method strips OpenSearch prefixes from exception names.

getExceptionSimpleClassName

public static String getExceptionSimpleClassName(Throwable ex)

toString

public String toString()

Overrides:

toString in class Throwable

readStackTrace

public static <T extends Throwable> T readStackTrace(T throwable,
 StreamInput in)
                                              throws IOException

Deserializes stacktrace elements as well as suppressed exceptions from the given output stream and adds it to the given exception.

Throws:

IOException

writeStackTraces

public static <S extends StreamOutput,
T extends Throwable>
T writeStackTraces(T throwable,
 StreamOutput out,
 Writeable.Writer<Throwable> exceptionWriter)
            throws IOException

Serializes the given exceptions stacktrace elements as well as it's suppressed exceptions to the given output stream.

Throws:

IOException

setResources

public void setResources(String type,
 String... id)

getResourceId

public List<String> getResourceId()

getResourceType

public String getResourceType()

getIndex

public Index getIndex()

setIndex

public void setIndex(Index index)

setIndex

public void setIndex(String index)

getShardId

public ShardId getShardId()

setShard

public void setShard(ShardId shardId)