Class LogFieldSyntax<T>
- java.lang.Object
-
- com.unboundid.ldap.sdk.unboundidds.logs.v2.syntax.LogFieldSyntax<T>
-
- Type Parameters:
T
- The type of value represented by this syntax.
- Direct Known Subclasses:
BooleanLogFieldSyntax
,CommaDelimitedStringListLogFieldSyntax
,DNLogFieldSyntax
,FilterLogFieldSyntax
,FloatingPointLogFieldSyntax
,GeneralizedTimeLogFieldSyntax
,IntegerLogFieldSyntax
,JSONLogFieldSyntax
,RFC3339TimestampLogFieldSyntax
,StringLogFieldSyntax
@NotExtensible @ThreadSafety(level=INTERFACE_THREADSAFE) public abstract class LogFieldSyntax<T> extends java.lang.Object
This class defines the base class for syntaxes that may be used for field values in log messages.
NOTE: This class, and other classes within the
com.unboundid.ldap.sdk.unboundidds
package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.
-
-
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.
-
-
-
Field Detail
-
CARRIAGE_RETURN_CODE_POINT
protected static final int CARRIAGE_RETURN_CODE_POINT
The code point that represents the ASCII carriage return character.- See Also:
- Constant Field Values
-
DOUBLE_QUOTE_CODE_POINT
protected static final int DOUBLE_QUOTE_CODE_POINT
The code point that represents the ASCII double quote character.- See Also:
- Constant Field Values
-
NEWLINE_CODE_POINT
protected static final int NEWLINE_CODE_POINT
The code point that represents the ASCII newline character.- See Also:
- Constant Field Values
-
OCTOTHORPE_CODE_POINT
protected static final int OCTOTHORPE_CODE_POINT
The code point that represents the ASCII octothorpe character.- See Also:
- Constant Field Values
-
TAB_CODE_POINT
protected static final int TAB_CODE_POINT
The code point that represents the ASCII tab character.- See Also:
- Constant Field Values
-
REDACTED_STRING
@NotNull public static final java.lang.String REDACTED_STRING
A string that will be used to indicate that the value has been redacted.- See Also:
- Constant Field Values
-
TOKEN_PREFIX_STRING
@NotNull public static final java.lang.String TOKEN_PREFIX_STRING
A prefix that will be used before a token in a tokenized value.- See Also:
- Constant Field Values
-
TOKEN_SUFFIX_STRING
@NotNull public static final java.lang.String TOKEN_SUFFIX_STRING
A suffix that will be used after a token in a tokenized value.- See Also:
- Constant Field Values
-
-
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 benull
.- 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 benull
.buffer
- The buffer to which the string representation should be appended. It must not benull
.
-
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 benull
.fieldValue
- The value to use for the field. It must not benull
.buffer
- The buffer to which the sanitized log field should be appended. It must not benull
.
-
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 benull
.fieldValue
- The value to use for the field. It must not benull
.buffer
- The buffer to which the sanitized log field should be appended. It must not benull
.
-
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 benull
.buffer
- The buffer to which the sanitized value should be appended. It must not benull
.
-
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 benull
.- 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 benull
.buffer
- The buffer to which the sanitized representation should be appended. It must not benull
.
-
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 benull
.- Returns:
true
if the provided value string represents a value that has been completely redacted, orfalse
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, orfalse
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 benull
.
-
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 benull
.buffer
- The buffer to which the sanitized log field should be appended. It must not benull
.
-
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 benull
.buffer
- The buffer to which the sanitized log field should be appended. It must not benull
.
-
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 benull
.
-
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, orfalse
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 benull
.- Returns:
true
if the provided value string represents a value that has had one or more components redacted, orfalse
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 benull
.- 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 benull
.buffer
- The buffer to which the redacted string representation should be appended. It must not benull
.
-
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 benull
.fieldValue
- The value to use for the field. It must not benull
.buffer
- The buffer to which the sanitized log field should be appended. It must not benull
.
-
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 benull
.fieldValue
- The value to use for the field. It must not benull
.buffer
- The buffer to which the sanitized log field should be appended. It must not benull
.
-
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 benull
.buffer
- The buffer to which the redacted value should be appended. It must not benull
.
-
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 benull
.- Returns:
true
if the provided value string represents a value that has been completely tokenized, orfalse
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, orfalse
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 benull
.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 benull
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 benull
.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 benull
and should not be empty.buffer
- The buffer to which the tokenized representation should be appended. It must not benull
.
-
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 benull
.fieldValue
- The value to use for the field. It must not benull
.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 benull
and should not be empty.buffer
- The buffer to which the sanitized log field should be appended. It must not benull
.
-
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 benull
.fieldValue
- The value to use for the field. It must not benull
.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 benull
and should not be empty.buffer
- The buffer to which the sanitized log field should be appended. It must not benull
.
-
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 benull
.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 benull
and should not be empty.buffer
- The buffer to which the tokenized value should be appended. It must not benull
.
-
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, orfalse
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 benull
.- Returns:
true
if the provided value string represents a value that has had one or more components tokenized, orfalse
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 benull
.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 benull
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 benull
.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 benull
and should not be empty.buffer
- The buffer to which the tokenized representation should be appended. It must not benull
.
-
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 benull
.fieldValue
- The value to use for the field. It must not benull
.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 benull
and should not be empty.buffer
- The buffer to which the sanitized log field should be appended. It must not benull
.
-
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 benull
.fieldValue
- The value to use for the field. It must not benull
.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 benull
and should not be empty.buffer
- The buffer to which the sanitized log field should be appended. It must not benull
.
-
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 benull
.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 benull
and should not be empty.buffer
- The buffer to which the tokenized value should be appended. It must not benull
.
-
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 benull
.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 benull
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 benull
.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 benull
and should not be empty.buffer
- The buffer to which the tokenized representation should be appended. It must not benull
.
-
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 benull
.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 benull
and should not be empty.buffer
- The buffer to which the tokenized representation should be appended. It must not benull
.
-
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 benull
.- Returns:
- The bytes that comprise the SHA-256 digest.
-
getTemporaryBuffer
@NotNull protected ByteStringBuffer getTemporaryBuffer()
Retrieves a temporary thread-local buffer that may be used during processing. When it is no longer needed, the buffer should be returned with thereleaseTemporaryBuffer(ByteStringBuffer)
method.- Returns:
- A temporary thread-local buffer that may be used during processing.
-
releaseTemporaryBuffer
protected void releaseTemporaryBuffer(@NotNull ByteStringBuffer buffer)
Releases the provided temporary buffer.- Parameters:
buffer
- The buffer to release. It must not benull
.
-
-