Package org.elasticsearch.common.logging

Class DeprecationLogger

  • public class DeprecationLogger
extends java.lang.Object
    A logger that logs deprecation notices.

    • Field Summary

      Fields 
      Modifier and Type Field 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 Description
      DeprecationLogger​(org.apache.logging.log4j.Logger parentLogger)
      Creates a new deprecation logger based on the parent logger.

    • Method Summary

      Modifier and Type Method 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 final 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", 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