Class LogFieldSyntax<T>

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static int CARRIAGE_RETURN_CODE_POINT
      The code point that represents the ASCII carriage return character.
      protected static int DOUBLE_QUOTE_CODE_POINT
      The code point that represents the ASCII double quote character.
      protected static int NEWLINE_CODE_POINT
      The code point that represents the ASCII newline character.
      protected static int OCTOTHORPE_CODE_POINT
      The code point that represents the ASCII octothorpe character.
      static java.lang.String REDACTED_STRING
      A string that will be used to indicate that the value has been redacted.
      protected static int TAB_CODE_POINT
      The code point that represents the ASCII tab character.
      static java.lang.String TOKEN_PREFIX_STRING
      A prefix that will be used before a token in a tokenized value.
      static java.lang.String TOKEN_SUFFIX_STRING
      A suffix that will be used after a token in a tokenized value.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected LogFieldSyntax​(int maxStringLengthCharacters)
      Creates a new instance of this log field syntax implementation.
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract boolean completelyRedactedValueConformsToSyntax()
      Indicates whether values that have been completely redacted still conform to this syntax.
      abstract boolean completelyTokenizedValueConformsToSyntax()
      Indicates whether values that have been completely tokenized still conform to this syntax.
      protected int getMaxStringLengthCharacters()
      Retrieves the maximum length (in characters) to use for strings within values.
      abstract java.lang.String getSyntaxName()
      Retrieves the name for this syntax.
      protected ByteStringBuffer getTemporaryBuffer()
      Retrieves a temporary thread-local buffer that may be used during processing.
      abstract void logCompletelyRedactedFieldToJSONFormattedLog​(java.lang.String fieldName, JSONBuffer buffer)
      Appends a completely redacted representation of the specified field (both field name and value) for a JSON-formatted log message to the given buffer.
      abstract void logCompletelyRedactedFieldToTextFormattedLog​(java.lang.String fieldName, ByteStringBuffer buffer)
      Appends a completely redacted representation of the specified field (both field name and value) for a text-formatted log message to the given buffer.
      abstract void logCompletelyRedactedValueToJSONFormattedLog​(JSONBuffer buffer)
      Appends a completely redacted representation of a value (without a field name, as might be suitable for a value included in a JSON array) for a JSON-formatted log message to the given buffer.
      abstract void logCompletelyTokenizedFieldToJSONFormattedLog​(java.lang.String fieldName, T fieldValue, byte[] pepper, JSONBuffer buffer)
      Appends a completely tokenized representation of the specified field (both field name and value) for a JSON-formatted log message to the given buffer.
      abstract void logCompletelyTokenizedFieldToTextFormattedLog​(java.lang.String fieldName, T fieldValue, byte[] pepper, ByteStringBuffer buffer)
      Appends a completely tokenized representation of the specified field (both field name and value) for a text-formatted log message to the given buffer.
      abstract void logCompletelyTokenizedValueToJSONFormattedLog​(T value, byte[] pepper, JSONBuffer buffer)
      Appends a completely tokenized representation of the provided value (without a field name, as might be suitable for a value included in a JSON array) for a JSON-formatted log message to the given buffer.
      abstract void logRedactedComponentsFieldToJSONFormattedLog​(java.lang.String fieldName, T fieldValue, JSONBuffer buffer)
      Appends a representation of the specified field (both field name and value) with redacted value components for a JSON-formatted log message to the given buffer.
      abstract void logRedactedComponentsFieldToTextFormattedLog​(java.lang.String fieldName, T fieldValue, ByteStringBuffer buffer)
      Appends a representation of the specified field (both field name and value) with redacted value components for a text-formatted log message to the given buffer.
      abstract void logRedactedComponentsValueToJSONFormattedLog​(T value, JSONBuffer buffer)
      Appends a representation of the provided value (without a field name, as might be suitable for a value included in a JSON array) with redacted components for a JSON-formatted log message to the given buffer.
      abstract void logSanitizedFieldToJSONFormattedLog​(java.lang.String fieldName, T fieldValue, JSONBuffer buffer)
      Appends a sanitized representation of the specified field (both field name and value) for a JSON-formatted log message to the given buffer.
      abstract void logSanitizedFieldToTextFormattedLog​(java.lang.String fieldName, T fieldValue, ByteStringBuffer buffer)
      Appends a sanitized representation of the specified field (both field name and value) for a text-formatted log message to the given buffer.
      abstract void logSanitizedValueToJSONFormattedLog​(T value, JSONBuffer buffer)
      Appends a sanitized representation of the provided value (without a field name, as might be suitable for a value included in a JSON array) for a JSON-formatted log message to the given buffer.
      abstract void logTokenizedComponentsFieldToJSONFormattedLog​(java.lang.String fieldName, T fieldValue, byte[] pepper, JSONBuffer buffer)
      Appends a representation of the specified field (both field name and value) with tokenized value components for a JSON-formatted log message to the given buffer.
      abstract void logTokenizedComponentsFieldToTextFormattedLog​(java.lang.String fieldName, T fieldValue, byte[] pepper, ByteStringBuffer buffer)
      Appends a representation of the specified field (both field name and value) with tokenized value components for a text-formatted log message to the given buffer.
      abstract void logTokenizedComponentsValueToJSONFormattedLog​(T value, byte[] pepper, JSONBuffer buffer)
      Appends a representation of the provided value (without a field name, as might be suitable for a value included in a JSON array) with tokenized value components for a JSON-formatted log message to the given buffer.
      abstract T parseValue​(java.lang.String valueString)
      Attempts to parse the provided string as a value in accordance with this syntax.
      java.lang.String redactComponents​(T value)
      Retrieves a string that provides a representation of the given value with zero or more of its components redacted.
      void redactComponents​(T value, ByteStringBuffer buffer)
      Appends a string representation of the given value with redacted components to the provided buffer.
      java.lang.String redactEntireValue()
      Retrieves a string that may be included in a log message to indicate that the entire value for a field with this syntax has been redacted.
      void redactEntireValue​(ByteStringBuffer buffer)
      Appends a string representation of a redacted entire value to the provided buffer.
      protected void releaseTemporaryBuffer​(ByteStringBuffer buffer)
      Releases the provided temporary buffer.
      protected java.lang.String sanitize​(java.lang.String string)
      Retrieves a sanitized version of the provided string.
      protected void sanitize​(java.lang.String string, ByteStringBuffer buffer)
      Appends an appropriately sanitized version of the provided string to the given buffer.
      protected byte[] sha256​(ByteStringBuffer buffer)
      Retrieves a SHA-256 digest of the contents of the provided buffer.
      abstract boolean supportsRedactedComponents()
      Indicates whether this syntax supports redacting individual components of the entire value.
      abstract boolean supportsTokenizedComponents()
      Indicates whether this syntax supports tokenizing individual components of the entire value.
      protected void tokenize​(byte[] bytes, byte[] pepper, ByteStringBuffer buffer)
      Appends a tokenized representation of the provided bytes to the given buffer.
      protected java.lang.String tokenize​(java.lang.String string, byte[] pepper)
      Retrieves a tokenized representation of the provided string.
      protected void tokenize​(java.lang.String string, byte[] pepper, ByteStringBuffer buffer)
      Appends a tokenized representation of the provided string to the given buffer.
      java.lang.String tokenizeComponents​(T value, byte[] pepper)
      Retrieves a string that provides a representation of the given value with zero or more of its components tokenized.
      void tokenizeComponents​(T value, byte[] pepper, ByteStringBuffer buffer)
      Appends a string representation of the given value with zero or more of its components tokenized to the provided buffer.
      java.lang.String tokenizeEntireValue​(T value, byte[] pepper)
      Retrieves a string that represents a tokenized representation of the provided value.
      abstract void tokenizeEntireValue​(T value, byte[] pepper, ByteStringBuffer buffer)
      Appends a tokenized representation of the provided value to the given buffer.
      boolean valueStringIncludesRedactedComponent​(java.lang.String valueString)
      Determines whether the provided value string represents a value that has had one or more components redacted.
      boolean valueStringIncludesTokenizedComponent​(java.lang.String valueString)
      Determines whether the provided value string represents a value that has had one or more components tokenized.
      boolean valueStringIsCompletelyRedacted​(java.lang.String valueString)
      Determines whether the provided value string represents a value that has been completely redacted.
      boolean valueStringIsCompletelyTokenized​(java.lang.String valueString)
      Determines whether the provided value string represents a value that has been completely tokenized.
      java.lang.String valueToSanitizedString​(T value)
      Encodes the provided value to a sanitized string representation suitable for inclusion in a log message.
      abstract void valueToSanitizedString​(T value, ByteStringBuffer buffer)
      Encodes the provided value to a sanitized string representation suitable for inclusion in a log message.
      abstract boolean valueWithRedactedComponentsConformsToSyntax()
      Indicates whether values with one or more redacted components still conform to this syntax.
      abstract boolean valueWithTokenizedComponentsConformsToSyntax()
      Indicates whether values with one or more tokenized components still conform to this syntax.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • LogFieldSyntax

        protected LogFieldSyntax​(int maxStringLengthCharacters)
        Creates a new instance of this log field syntax implementation.
        Parameters:
        maxStringLengthCharacters - The maximum length (in characters) to use for strings within values. Strings that are longer than this should be truncated before inclusion in the log. This value must be greater than or equal to zero.
    • Method Detail

      • getMaxStringLengthCharacters

        protected int getMaxStringLengthCharacters()
        Retrieves the maximum length (in characters) to use for strings within values. Strings that are longer than this should be truncated before inclusion in the log.
        Returns:
        The maximum length (in characters) to use for strings within values.
      • getSyntaxName

        @NotNull
        public abstract java.lang.String getSyntaxName()
        Retrieves the name for this syntax.
        Returns:
        The name for this syntax.
      • valueToSanitizedString

        @NotNull
        public java.lang.String valueToSanitizedString​(@NotNull
                                                       T value)
        Encodes the provided value to a sanitized string representation suitable for inclusion in a log message. The sanitized string should at least be cleaned of control characters and other non-printable characters, but depending on the syntax, it may clean other characters as well.
        Parameters:
        value - The value to be encoded. It must not be null.
        Returns:
        The encoded representation of the value. It must not be null, but may be empty.
      • valueToSanitizedString

        public abstract void valueToSanitizedString​(@NotNull
                                                    T value,
                                                    @NotNull
                                                    ByteStringBuffer buffer)
        Encodes the provided value to a sanitized string representation suitable for inclusion in a log message. The sanitized string should at least be cleaned of control characters and other non-printable characters, but depending on the syntax, it may clean other characters as well.
        Parameters:
        value - The value to be encoded. It must not be null.
        buffer - The buffer to which the string representation should be appended. It must not be null.
      • logSanitizedFieldToTextFormattedLog

        public abstract void logSanitizedFieldToTextFormattedLog​(@NotNull
                                                                 java.lang.String fieldName,
                                                                 @NotNull
                                                                 T fieldValue,
                                                                 @NotNull
                                                                 ByteStringBuffer buffer)
        Appends a sanitized representation of the specified field (both field name and value) for a text-formatted log message to the given buffer.
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.
      • logSanitizedFieldToJSONFormattedLog

        public abstract void logSanitizedFieldToJSONFormattedLog​(@NotNull
                                                                 java.lang.String fieldName,
                                                                 @NotNull
                                                                 T fieldValue,
                                                                 @NotNull
                                                                 JSONBuffer buffer)
        Appends a sanitized representation of the specified field (both field name and value) for a JSON-formatted log message to the given buffer.
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.
      • logSanitizedValueToJSONFormattedLog

        public abstract void logSanitizedValueToJSONFormattedLog​(@NotNull
                                                                 T value,
                                                                 @NotNull
                                                                 JSONBuffer buffer)
        Appends a sanitized representation of the provided value (without a field name, as might be suitable for a value included in a JSON array) for a JSON-formatted log message to the given buffer.
        Parameters:
        value - The value to be appended to the buffer. It must not be null.
        buffer - The buffer to which the sanitized value should be appended. It must not be null.
      • sanitize

        @NotNull
        protected final java.lang.String sanitize​(@NotNull
                                                  java.lang.String string)
        Retrieves a sanitized version of the provided string.
        Parameters:
        string - The string to be sanitized. It must not be null.
        Returns:
        The sanitized version of the provided string.
      • sanitize

        protected final void sanitize​(@NotNull
                                      java.lang.String string,
                                      @NotNull
                                      ByteStringBuffer buffer)
        Appends an appropriately sanitized version of the provided string to the given buffer.
        Parameters:
        string - The string to be sanitized. It must not be null.
        buffer - The buffer to which the sanitized representation should be appended. It must not be null.
      • parseValue

        @NotNull
        public abstract T parseValue​(@NotNull
                                     java.lang.String valueString)
                              throws RedactedValueException,
                                     TokenizedValueException,
                                     LogSyntaxException
        Attempts to parse the provided string as a value in accordance with this syntax.
        Parameters:
        valueString - The string to be parsed.
        Returns:
        The value that was parsed.
        Throws:
        RedactedValueException - If the provided value has been redacted (either the complete value or one or more of its components), and the redacted form cannot be represented in this syntax.
        TokenizedValueException - If the provided value has been tokenized (either the complete value or one or more of its components), and the redacted form cannot be represented in this syntax.
        LogSyntaxException - If the provided value cannot be parsed in accordance with this syntax.
      • valueStringIsCompletelyRedacted

        public boolean valueStringIsCompletelyRedacted​(@NotNull
                                                       java.lang.String valueString)
        Determines whether the provided value string represents a value that has been completely redacted.
        Parameters:
        valueString - The value for which to make the determination. It must not be null.
        Returns:
        true if the provided value string represents a value that has been completely redacted, or false if not.
      • completelyRedactedValueConformsToSyntax

        public abstract boolean completelyRedactedValueConformsToSyntax()
        Indicates whether values that have been completely redacted still conform to this syntax.
        Returns:
        true if values that have been completely redacted still conform to this syntax, or false if not.
      • redactEntireValue

        @NotNull
        public java.lang.String redactEntireValue()
        Retrieves a string that may be included in a log message to indicate that the entire value for a field with this syntax has been redacted.
        Returns:
        A string that may be included in a log message to indicate that the entire value for a field with this syntax has been redacted.
      • redactEntireValue

        public void redactEntireValue​(@NotNull
                                      ByteStringBuffer buffer)
        Appends a string representation of a redacted entire value to the provided buffer.
        Parameters:
        buffer - The buffer to which the redacted string representation should be appended. It must not be null.
      • logCompletelyRedactedFieldToTextFormattedLog

        public abstract void logCompletelyRedactedFieldToTextFormattedLog​(@NotNull
                                                                          java.lang.String fieldName,
                                                                          @NotNull
                                                                          ByteStringBuffer buffer)
        Appends a completely redacted representation of the specified field (both field name and value) for a text-formatted log message to the given buffer.
        Parameters:
        fieldName - The name for the field. It must not be null.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.
      • logCompletelyRedactedFieldToJSONFormattedLog

        public abstract void logCompletelyRedactedFieldToJSONFormattedLog​(@NotNull
                                                                          java.lang.String fieldName,
                                                                          @NotNull
                                                                          JSONBuffer buffer)
        Appends a completely redacted representation of the specified field (both field name and value) for a JSON-formatted log message to the given buffer.
        Parameters:
        fieldName - The name for the field. It must not be null.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.
      • logCompletelyRedactedValueToJSONFormattedLog

        public abstract void logCompletelyRedactedValueToJSONFormattedLog​(@NotNull
                                                                          JSONBuffer buffer)
        Appends a completely redacted representation of a value (without a field name, as might be suitable for a value included in a JSON array) for a JSON-formatted log message to the given buffer.
        Parameters:
        buffer - The buffer to which the redacted value should be appended. It must not be null.
      • supportsRedactedComponents

        public abstract boolean supportsRedactedComponents()
        Indicates whether this syntax supports redacting individual components of the entire value.
        Returns:
        true if this syntax supports redacting individual components of the entire value, or false if not.
      • valueStringIncludesRedactedComponent

        public boolean valueStringIncludesRedactedComponent​(@NotNull
                                                            java.lang.String valueString)
        Determines whether the provided value string represents a value that has had one or more components redacted.
        Parameters:
        valueString - The value for which to make the determination. It must not be null.
        Returns:
        true if the provided value string represents a value that has had one or more components redacted, or false if not.
      • valueWithRedactedComponentsConformsToSyntax

        public abstract boolean valueWithRedactedComponentsConformsToSyntax()
        Indicates whether values with one or more redacted components still conform to this syntax.
        Returns:
        true if values with one or more redacted components still conform to this syntax.
      • redactComponents

        @NotNull
        public java.lang.String redactComponents​(@NotNull
                                                 T value)
        Retrieves a string that provides a representation of the given value with zero or more of its components redacted. If this syntax does not support redacted components, then the entire value should be redacted.
        Parameters:
        value - The value for which to obtain the redacted representation. It must not be null.
        Returns:
        A string representation of the given value with zero or more of its components redacted.
      • redactComponents

        public void redactComponents​(@NotNull
                                     T value,
                                     @NotNull
                                     ByteStringBuffer buffer)
        Appends a string representation of the given value with redacted components to the provided buffer.
        Parameters:
        value - The value for which to obtain the redacted representation. It must not be null.
        buffer - The buffer to which the redacted string representation should be appended. It must not be null.
      • logRedactedComponentsFieldToTextFormattedLog

        public abstract void logRedactedComponentsFieldToTextFormattedLog​(@NotNull
                                                                          java.lang.String fieldName,
                                                                          @NotNull
                                                                          T fieldValue,
                                                                          @NotNull
                                                                          ByteStringBuffer buffer)
        Appends a representation of the specified field (both field name and value) with redacted value components for a text-formatted log message to the given buffer. If this syntax does not support redacting components within a value, then it should redact the entire value.
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.
      • logRedactedComponentsFieldToJSONFormattedLog

        public abstract void logRedactedComponentsFieldToJSONFormattedLog​(@NotNull
                                                                          java.lang.String fieldName,
                                                                          @NotNull
                                                                          T fieldValue,
                                                                          @NotNull
                                                                          JSONBuffer buffer)
        Appends a representation of the specified field (both field name and value) with redacted value components for a JSON-formatted log message to the given buffer. If this syntax does not support redacting components within a value, then it should redact the entire value.
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.
      • logRedactedComponentsValueToJSONFormattedLog

        public abstract void logRedactedComponentsValueToJSONFormattedLog​(@NotNull
                                                                          T value,
                                                                          @NotNull
                                                                          JSONBuffer buffer)
        Appends a representation of the provided value (without a field name, as might be suitable for a value included in a JSON array) with redacted components for a JSON-formatted log message to the given buffer. If this syntax does not support redacting components within a value, then it should redact the entire value.
        Parameters:
        value - The value to be appended to the buffer in redacted form. It must not be null.
        buffer - The buffer to which the redacted value should be appended. It must not be null.
      • valueStringIsCompletelyTokenized

        public boolean valueStringIsCompletelyTokenized​(@NotNull
                                                        java.lang.String valueString)
        Determines whether the provided value string represents a value that has been completely tokenized.
        Parameters:
        valueString - The value for which to make the determination. It must not be null.
        Returns:
        true if the provided value string represents a value that has been completely tokenized, or false if not.
      • completelyTokenizedValueConformsToSyntax

        public abstract boolean completelyTokenizedValueConformsToSyntax()
        Indicates whether values that have been completely tokenized still conform to this syntax.
        Returns:
        true if values that have been completely tokenized still conform to this syntax, or false if not.
      • tokenizeEntireValue

        @NotNull
        public java.lang.String tokenizeEntireValue​(@NotNull
                                                    T value,
                                                    @NotNull
                                                    byte[] pepper)
        Retrieves a string that represents a tokenized representation of the provided value.

        The resulting token will protect the provided value by representing it in a way that makes it at infeasible to determine what the original value was. However, tokenizing the same value with the same pepper should consistently yield the same token value, so that it will be possible to identify the same value across multiple log messages.
        Parameters:
        value - The value for which to generate the token. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        Returns:
        A string that represents a tokenized representation of the provided value.
      • tokenizeEntireValue

        public abstract void tokenizeEntireValue​(@NotNull
                                                 T value,
                                                 @NotNull
                                                 byte[] pepper,
                                                 @NotNull
                                                 ByteStringBuffer buffer)
        Appends a tokenized representation of the provided value to the given buffer.

        The resulting token will protect the provided value by representing it in a way that makes it at infeasible to determine what the original value was. However, tokenizing the same value with the same pepper should consistently yield the same token value, so that it will be possible to identify the same value across multiple log messages.
        Parameters:
        value - The value for which to generate the token. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the tokenized representation should be appended. It must not be null.
      • logCompletelyTokenizedFieldToTextFormattedLog

        public abstract void logCompletelyTokenizedFieldToTextFormattedLog​(@NotNull
                                                                           java.lang.String fieldName,
                                                                           @NotNull
                                                                           T fieldValue,
                                                                           @NotNull
                                                                           byte[] pepper,
                                                                           @NotNull
                                                                           ByteStringBuffer buffer)
        Appends a completely tokenized representation of the specified field (both field name and value) for a text-formatted log message to the given buffer.
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.
      • logCompletelyTokenizedFieldToJSONFormattedLog

        public abstract void logCompletelyTokenizedFieldToJSONFormattedLog​(@NotNull
                                                                           java.lang.String fieldName,
                                                                           @NotNull
                                                                           T fieldValue,
                                                                           @NotNull
                                                                           byte[] pepper,
                                                                           @NotNull
                                                                           JSONBuffer buffer)
        Appends a completely tokenized representation of the specified field (both field name and value) for a JSON-formatted log message to the given buffer.
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.
      • logCompletelyTokenizedValueToJSONFormattedLog

        public abstract void logCompletelyTokenizedValueToJSONFormattedLog​(@NotNull
                                                                           T value,
                                                                           @NotNull
                                                                           byte[] pepper,
                                                                           @NotNull
                                                                           JSONBuffer buffer)
        Appends a completely tokenized representation of the provided value (without a field name, as might be suitable for a value included in a JSON array) for a JSON-formatted log message to the given buffer.
        Parameters:
        value - The value to be appended to the buffer in tokenized form. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the tokenized value should be appended. It must not be null.
      • supportsTokenizedComponents

        public abstract boolean supportsTokenizedComponents()
        Indicates whether this syntax supports tokenizing individual components of the entire value.
        Returns:
        true if this syntax supports tokenizing individual components of the entire value, or false if not.
      • valueStringIncludesTokenizedComponent

        public boolean valueStringIncludesTokenizedComponent​(@NotNull
                                                             java.lang.String valueString)
        Determines whether the provided value string represents a value that has had one or more components tokenized.
        Parameters:
        valueString - The value for which to make the determination. It must not be null.
        Returns:
        true if the provided value string represents a value that has had one or more components tokenized, or false if not.
      • valueWithTokenizedComponentsConformsToSyntax

        public abstract boolean valueWithTokenizedComponentsConformsToSyntax()
        Indicates whether values with one or more tokenized components still conform to this syntax.
        Returns:
        true if values with one or more tokenized components still conform to this syntax.
      • tokenizeComponents

        @NotNull
        public java.lang.String tokenizeComponents​(@NotNull
                                                   T value,
                                                   @NotNull
                                                   byte[] pepper)
        Retrieves a string that provides a representation of the given value with zero or more of its components tokenized. If this syntax does not support tokenized components, then the entire value should be tokenized.

        The resulting tokens will protect components of the provided value by representing them in a way that makes it at infeasible to determine what the original components were. However, tokenizing the same value with the same pepper should consistently yield the same token value, so that it will be possible to identify the same value across multiple log messages.
        Parameters:
        value - The value whose components should be tokenized. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        Returns:
        A string that represents a tokenized representation of the provided value.
      • tokenizeComponents

        public void tokenizeComponents​(@NotNull
                                       T value,
                                       @NotNull
                                       byte[] pepper,
                                       @NotNull
                                       ByteStringBuffer buffer)
        Appends a string representation of the given value with zero or more of its components tokenized to the provided buffer. If this syntax does not support tokenized components, then the entire value should be tokenized.

        The resulting tokens will protect components of the provided value by representing them in a way that makes it at infeasible to determine what the original components were. However, tokenizing the same value with the same pepper should consistently yield the same token value, so that it will be possible to identify the same value across multiple log messages.
        Parameters:
        value - The value whose components should be tokenized. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the tokenized representation should be appended. It must not be null.
      • logTokenizedComponentsFieldToTextFormattedLog

        public abstract void logTokenizedComponentsFieldToTextFormattedLog​(@NotNull
                                                                           java.lang.String fieldName,
                                                                           @NotNull
                                                                           T fieldValue,
                                                                           @NotNull
                                                                           byte[] pepper,
                                                                           @NotNull
                                                                           ByteStringBuffer buffer)
        Appends a representation of the specified field (both field name and value) with tokenized value components for a text-formatted log message to the given buffer. If this syntax does not support tokenizing components within a value, then it should tokenize the entire value.
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.
      • logTokenizedComponentsFieldToJSONFormattedLog

        public abstract void logTokenizedComponentsFieldToJSONFormattedLog​(@NotNull
                                                                           java.lang.String fieldName,
                                                                           @NotNull
                                                                           T fieldValue,
                                                                           @NotNull
                                                                           byte[] pepper,
                                                                           @NotNull
                                                                           JSONBuffer buffer)
        Appends a representation of the specified field (both field name and value) with tokenized value components for a JSON-formatted log message to the given buffer. If this syntax does not support tokenizing components within a value, then it should tokenize the entire value.
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.
      • logTokenizedComponentsValueToJSONFormattedLog

        public abstract void logTokenizedComponentsValueToJSONFormattedLog​(@NotNull
                                                                           T value,
                                                                           @NotNull
                                                                           byte[] pepper,
                                                                           @NotNull
                                                                           JSONBuffer buffer)
        Appends a representation of the provided value (without a field name, as might be suitable for a value included in a JSON array) with tokenized value components for a JSON-formatted log message to the given buffer. If this syntax does not support tokenizing components within a value, then it should tokenize the entire value.
        Parameters:
        value - The value to be appended to the buffer in tokenized form. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the tokenized value should be appended. It must not be null.
      • tokenize

        @NotNull
        protected final java.lang.String tokenize​(@NotNull
                                                  java.lang.String string,
                                                  @NotNull
                                                  byte[] pepper)
        Retrieves a tokenized representation of the provided string.
        Parameters:
        string - The string to be tokenized. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        Returns:
        A tokenized representation of the provided string.
      • tokenize

        protected final void tokenize​(@NotNull
                                      java.lang.String string,
                                      @NotNull
                                      byte[] pepper,
                                      @NotNull
                                      ByteStringBuffer buffer)
        Appends a tokenized representation of the provided string to the given buffer.
        Parameters:
        string - The string to be tokenized. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the tokenized representation should be appended. It must not be null.
      • tokenize

        protected final void tokenize​(@NotNull
                                      byte[] bytes,
                                      @NotNull
                                      byte[] pepper,
                                      @NotNull
                                      ByteStringBuffer buffer)
        Appends a tokenized representation of the provided bytes to the given buffer.
        Parameters:
        bytes - The bytes to be tokenized. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the tokenized representation should be appended. It must not be null.
      • sha256

        @NotNull
        protected final byte[] sha256​(@NotNull
                                      ByteStringBuffer buffer)
        Retrieves a SHA-256 digest of the contents of the provided buffer.
        Parameters:
        buffer - The buffer containing the data to digest. It must not be null.
        Returns:
        The bytes that comprise the SHA-256 digest.