Skip to content

Update StructuredDataMessage Javadoc for RFC 5424 compliance #4103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DrDrunkenstien-10 wants to merge 1 commit into
base: 2.x
Choose a base branch
from
+116 −0
Open

Update StructuredDataMessage Javadoc for RFC 5424 compliance #4103

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 116 additions & 0 deletions log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataMessage.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,21 @@ public enum Format {

/**
* Creates a StructuredDataMessage using an ID (max 32 characters), message, and type (max 32 characters).
* <p>
* The {@code id} parameter represents the syslog {@code SD-ID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.3.2">RFC 5424 Section 6.3.2</a>.
* It is recommended to use {@link StructuredDataId} instead of a raw {@link String} where possible.
* </p>
* <p>
* The {@code type} parameter represents the syslog {@code MSGID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.7">RFC 5424 Section 6.2.7</a>.
* </p>
* <p>
* Both {@code id} and {@code type} are considered trusted inputs (typically compile-time constants).
* If these values are derived from external or untrusted sources, it is the caller's responsibility
* to validate and sanitize them to ensure RFC-compliant output, especially when used with
* {@code Rfc5424Layout}.
* </p>
* @param id The String id.
* @param msg The message.
* @param type The message type.
Expand All @@ -69,6 +84,21 @@ public StructuredDataMessage(final String id, final String msg, final String typ
/**
* Creates a StructuredDataMessage using an ID (user specified max characters), message, and type (user specified
* maximum number of characters).
* <p>
* The {@code id} parameter represents the syslog {@code SD-ID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.3.2">RFC 5424 Section 6.3.2</a>.
* It is recommended to use {@link StructuredDataId} instead of a raw {@link String} where possible.
* </p>
* <p>
* The {@code type} parameter represents the syslog {@code MSGID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.7">RFC 5424 Section 6.2.7</a>.
* </p>
* <p>
* Both {@code id} and {@code type} are considered trusted inputs (typically compile-time constants).
* If these values are derived from external or untrusted sources, it is the caller's responsibility
* to validate and sanitize them to ensure RFC-compliant output, especially when used with
* {@code Rfc5424Layout}.
* </p>
* @param id The String id.
* @param msg The message.
* @param type The message type.
Expand All @@ -85,6 +115,21 @@ public StructuredDataMessage(final String id, final String msg, final String typ
/**
* Creates a StructuredDataMessage using an ID (max 32 characters), message, type (max 32 characters), and an
* initial map of structured data to include.
* <p>
* The {@code id} parameter represents the syslog {@code SD-ID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.3.2">RFC 5424 Section 6.3.2</a>.
* It is recommended to use {@link StructuredDataId} instead of a raw {@link String} where possible.
* </p>
* <p>
* The {@code type} parameter represents the syslog {@code MSGID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.7">RFC 5424 Section 6.2.7</a>.
* </p>
* <p>
* Both {@code id} and {@code type} are considered trusted inputs (typically compile-time constants).
* If these values are derived from external or untrusted sources, it is the caller's responsibility
* to validate and sanitize them to ensure RFC-compliant output, especially when used with
* {@code Rfc5424Layout}.
* </p>
* @param id The String id.
* @param msg The message.
* @param type The message type.
Expand All @@ -97,6 +142,21 @@ public StructuredDataMessage(final String id, final String msg, final String typ
/**
* Creates a StructuredDataMessage using an (user specified max characters), message, and type (user specified
* maximum number of characters, and an initial map of structured data to include.
* <p>
* The {@code id} parameter represents the syslog {@code SD-ID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.3.2">RFC 5424 Section 6.3.2</a>.
* It is recommended to use {@link StructuredDataId} instead of a raw {@link String} where possible.
* </p>
* <p>
* The {@code type} parameter represents the syslog {@code MSGID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.7">RFC 5424 Section 6.2.7</a>.
* </p>
* <p>
* Both {@code id} and {@code type} are considered trusted inputs (typically compile-time constants).
* If these values are derived from external or untrusted sources, it is the caller's responsibility
* to validate and sanitize them to ensure RFC-compliant output, especially when used with
* {@code Rfc5424Layout}.
* </p>
* @param id The String id.
* @param msg The message.
* @param type The message type.
Expand All @@ -115,6 +175,20 @@ public StructuredDataMessage(

/**
* Creates a StructuredDataMessage using a StructuredDataId, message, and type (max 32 characters).
* <p>
* The {@link StructuredDataId} parameter represents the syslog {@code SD-ID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.3.2">RFC 5424 Section 6.3.2</a>.
* </p>
* <p>
* The {@code type} parameter represents the syslog {@code MSGID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.7">RFC 5424 Section 6.2.7</a>.
* </p>
* <p>
* Both {@code id} and {@code type} are considered trusted inputs (typically compile-time constants).
* If these values are derived from external or untrusted sources, it is the caller's responsibility
* to validate and sanitize them to ensure RFC-compliant output, especially when used with
* {@code Rfc5424Layout}.
* </p>
* @param id The StructuredDataId.
* @param msg The message.
* @param type The message type.
Expand All @@ -125,6 +199,20 @@ public StructuredDataMessage(final StructuredDataId id, final String msg, final

/**
* Creates a StructuredDataMessage using a StructuredDataId, message, and type (max 32 characters).
* <p>
* The {@link StructuredDataId} parameter represents the syslog {@code SD-ID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.3.2">RFC 5424 Section 6.3.2</a>.
* </p>
* <p>
* The {@code type} parameter represents the syslog {@code MSGID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.7">RFC 5424 Section 6.2.7</a>.
* </p>
* <p>
* Both {@code id} and {@code type} are considered trusted inputs (typically compile-time constants).
* If these values are derived from external or untrusted sources, it is the caller's responsibility
* to validate and sanitize them to ensure RFC-compliant output, especially when used with
* {@code Rfc5424Layout}.
* </p>
* @param id The StructuredDataId.
* @param msg The message.
* @param type The message type.
Expand All @@ -141,6 +229,20 @@ public StructuredDataMessage(final StructuredDataId id, final String msg, final
/**
* Creates a StructuredDataMessage using a StructuredDataId, message, type (max 32 characters), and an initial map
* of structured data to include.
* <p>
* The {@link StructuredDataId} parameter represents the syslog {@code SD-ID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.3.2">RFC 5424 Section 6.3.2</a>.
* </p>
* <p>
* The {@code type} parameter represents the syslog {@code MSGID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.7">RFC 5424 Section 6.2.7</a>.
* </p>
* <p>
* Both {@code id} and {@code type} are considered trusted inputs (typically compile-time constants).
* If these values are derived from external or untrusted sources, it is the caller's responsibility
* to validate and sanitize them to ensure RFC-compliant output, especially when used with
* {@code Rfc5424Layout}.
* </p>
* @param id The StructuredDataId.
* @param msg The message.
* @param type The message type.
Expand All @@ -154,6 +256,20 @@ public StructuredDataMessage(
/**
* Creates a StructuredDataMessage using a StructuredDataId, message, type (max 32 characters), and an initial map
* of structured data to include.
* <p>
* The {@link StructuredDataId} parameter represents the syslog {@code SD-ID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.3.2">RFC 5424 Section 6.3.2</a>.
* </p>
* <p>
* The {@code type} parameter represents the syslog {@code MSGID} and is expected to conform to
* <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.7">RFC 5424 Section 6.2.7</a>.
* </p>
* <p>
* Both {@code id} and {@code type} are considered trusted inputs (typically compile-time constants).
* If these values are derived from external or untrusted sources, it is the caller's responsibility
* to validate and sanitize them to ensure RFC-compliant output, especially when used with
* {@code Rfc5424Layout}.
* </p>
* @param id The StructuredDataId.
* @param msg The message.
* @param type The message type.
Expand Down