vy commented on code in PR #4103:
URL: https://github.com/apache/logging-log4j2/pull/4103#discussion_r3361442844
##########
log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataMessage.java:
##########
@@ -57,133 +61,363 @@ public enum Format {
}
/**
- * Creates a StructuredDataMessage using an ID (max 32 characters),
message, and type (max 32 characters).
- * @param id The String id.
- * @param msg The message.
- * @param type The message type.
+ * Creates a StructuredDataMessage using an SD-ID (max 32 characters),
message,
+ * and
+ * MSGID (max 32 characters).
+ * <p>
+ * The {@code sdId} 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,
+ * as it allows specifying a set of allowed keys for structured data
elements.
+ * </p>
+ * <p>
+ * The {@code msgId} 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 sdId} and {@code msgId} 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 sdId The String SD-ID.
+ * @param msg The message.
+ * @param msgId The identifier MSGID.
*/
- public StructuredDataMessage(final String id, final String msg, final
String type) {
- this(id, msg, type, MAX_LENGTH);
+ public StructuredDataMessage(final String sdId, final String msg, final
String msgId) {
+ this(sdId, msg, msgId, MAX_LENGTH);
}
/**
- * Creates a StructuredDataMessage using an ID (user specified max
characters), message, and type (user specified
+ * Creates a StructuredDataMessage using an SD-ID (user specified max
+ * characters),
+ * message, and MSGID (user specified
* maximum number of characters).
- * @param id The String id.
- * @param msg The message.
- * @param type The message type.
+ * <p>
+ * The {@code sdId} 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,
+ * as it allows specifying a set of allowed keys for structured data
elements.
+ * </p>
+ * <p>
+ * The {@code msgId} 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 sdId} and {@code msgId} 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 sdId The String SD-ID.
+ * @param msg The message.
+ * @param msgId The message identifier MSGID.
* @param maxLength The maximum length of keys;
* @since 2.9.0
*/
- public StructuredDataMessage(final String id, final String msg, final
String type, final int maxLength) {
- this.id = new StructuredDataId(id, null, null, maxLength);
+ public StructuredDataMessage(final String sdId, final String msg, final
String msgId, final int maxLength) {
+ validateSdId(sdId);
+ validateMsgId(msgId);
+
+ this.sdId = new StructuredDataId(sdId, null, null, maxLength);
Review Comment:
Doesn't `StructuredDataId::new` need to have some validation too?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
