Update StructuredDataMessage Javadoc for RFC 5424 compliance

[DrDrunkenstien-10]

Fixes #4051

This pull request improves the Javadoc of StructuredDataMessage constructors by clarifying
the expected format and usage of the id (SD-ID) and type (MSGID) parameters.

Specifically:

• Adds references to RFC 5424 sections for SD-ID and MSGID
• Documents that these parameters are expected to conform to the RFC syntax
• Clarifies that they are treated as trusted inputs (typically compile-time constants)
• Highlights that validation/sanitization is the caller's responsibility when using untrusted input
• Recommends using StructuredDataId instead of raw String where applicable

This change is documentation-only and does not modify runtime behavior.

This improvement is based on feedback from the YesWeHack bug bounty report (#YWH-PGM10209-37),
which identified a lack of clarity in the existing documentation.

Checklist

• Base your changes on 2.x branch if you are targeting Log4j 2; use main otherwise

  • Yes (based on 2.x)

• ./mvnw verify succeeds (the build instructions)

  • Yes

• Non-trivial changes contain an entry file in the src/changelog/.2.x.x directory

  • Not applicable (documentation-only change; no behavioral impact)

• Tests are provided

  • Not applicable (documentation-only change)

[vy]

@ppkarwasz, would you mind helping with reviewing this one, please?

[ppkarwasz]

Hi @DrDrunkenstien-10,

Thank you for the contribution, the Javadoc improvement is very appreciated! ❤️

However, since we'll be preparing a new minor version soon, I think we can push this further: throw an IllegalArgumentException, whenever a user passes an invalid argument. This is already true, whenever a user calls one of the with(...) methods on this class: the key is checked for compliance with RFC5424. We could have exactly the same behavior for id and type (BTW: it would be useful to rename them to sdId and msgId).

Regarding the recommendation of using StructuredDataId, we should add a reason:

StructuredDataId allows you to specify the list of allowed keys

While the above is true, there seems to be another small problem in the code: the possible fields specified by StructuredDataId are never actually checked. 😉