org.elasticsearch.common.logging

Class DeprecationLogger

java.lang.Object

org.elasticsearch.common.logging.DeprecationLogger

public class DeprecationLogger
extends java.lang.Object

A logger that logs deprecation notices.

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.regex.Pattern	WARNING_HEADER_PATTERN Regular expression to test if a string matches the RFC7234 specification for warning headers.

Constructor Summary

Constructors

Constructor and Description
DeprecationLogger(org.apache.logging.log4j.Logger parentLogger) Creates a new deprecation logger based on the parent logger.

Method Summary

Modifier and Type	Method and Description
void	deprecated(java.lang.String msg, java.lang.Object... params) Logs a deprecation message, adding a formatted warning message as a response header on the thread context.
void	deprecatedAndMaybeLog(java.lang.String key, java.lang.String msg, java.lang.Object... params) Adds a formatted warning message as a response header on the thread context, and logs a deprecation message if the associated key has not recently been seen.
static java.lang.String	escapeAndEncode(java.lang.String s) Escape and encode a string as a valid RFC 7230 quoted-string.
static java.lang.String	extractWarningValueFromWarningHeader(java.lang.String s) Extracts the warning value from the value of a warning header that is formatted according to RFC 7234.
static java.lang.String	formatWarning(java.lang.String s) Format a warning string in the proper warning format by prepending a warn code, warn agent, wrapping the warning string in quotes, and appending the RFC 7231 date.
static void	removeThreadContext(ThreadContext threadContext) Remove the ThreadContext used to add deprecation headers to network responses.
static void	setThreadContext(ThreadContext threadContext) Set the ThreadContext used to add deprecation headers to network responses.

Methods inherited from class java.lang.Object

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

Field Detail

WARNING_HEADER_PATTERN

public static java.util.regex.Pattern WARNING_HEADER_PATTERN

Regular expression to test if a string matches the RFC7234 specification for warning headers. This pattern assumes that the warn code is always 299. Further, this pattern assumes that the warn agent represents a version of Elasticsearch including the build hash.

Constructor Detail

DeprecationLogger

public DeprecationLogger(org.apache.logging.log4j.Logger parentLogger)

Creates a new deprecation logger based on the parent logger. Automatically prefixes the logger name with "deprecation", if it starts with "org.elasticsearch.", it replaces "org.elasticsearch" with "org.elasticsearch.deprecation" to maintain the "org.elasticsearch" namespace.

Method Detail

setThreadContext

public static void setThreadContext(ThreadContext threadContext)

Set the ThreadContext used to add deprecation headers to network responses.

This is expected to only be invoked by the Node's constructor (therefore once outside of tests).

Parameters:

threadContext - The thread context owned by the ThreadPool (and implicitly a Node)

Throws:

java.lang.IllegalStateException - if this threadContext has already been set

removeThreadContext

public static void removeThreadContext(ThreadContext threadContext)

Remove the ThreadContext used to add deprecation headers to network responses.

This is expected to only be invoked by the Node's close method (therefore once outside of tests).

Parameters:

threadContext - The thread context owned by the ThreadPool (and implicitly a Node)

Throws:

java.lang.IllegalStateException - if this threadContext is unknown (and presumably already unset before)

deprecated

public void deprecated(java.lang.String msg,
                       java.lang.Object... params)

Logs a deprecation message, adding a formatted warning message as a response header on the thread context.

deprecatedAndMaybeLog

public void deprecatedAndMaybeLog(java.lang.String key,
                                  java.lang.String msg,
                                  java.lang.Object... params)

Adds a formatted warning message as a response header on the thread context, and logs a deprecation message if the associated key has not recently been seen.

Parameters:

key - the key used to determine if this deprecation should be logged

msg - the message to log

params - parameters to the message

extractWarningValueFromWarningHeader

public static java.lang.String extractWarningValueFromWarningHeader(java.lang.String s)

Extracts the warning value from the value of a warning header that is formatted according to RFC 7234. That is, given a string 299 Elasticsearch-6.0.0 "warning value" "Sat, 25 Feb 2017 10:27:43 GMT", the return value of this method would be warning value.

Parameters:

s - the value of a warning header formatted according to RFC 7234.

Returns:

the extracted warning value

formatWarning

public static java.lang.String formatWarning(java.lang.String s)

Format a warning string in the proper warning format by prepending a warn code, warn agent, wrapping the warning string in quotes, and appending the RFC 7231 date.

Parameters:

s - the warning string to format

Returns:

a warning value formatted according to RFC 7234

escapeAndEncode

public static java.lang.String escapeAndEncode(java.lang.String s)

Escape and encode a string as a valid RFC 7230 quoted-string.

Parameters:

s - the string to escape and encode

Returns:

the escaped and encoded string