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. 😉

[DrDrunkenstien-10]

@ppkarwasz Thank you for the feedback!

I’ll work on updating the PR to incorporate these changes.

[DrDrunkenstien-10]

@ppkarwasz

Updated the PR to validate invalid SD-ID and MSGID inputs, renamed id to sdId and type to msgId in both the code and Javadocs, and updated the Javadocs to mention that StructuredDataId is recommended because it allows specifying allowed keys.

I did not implement enforcement of the allowed keys defined by StructuredDataId, since that appears to be a separate behavioral issue and may be better addressed in its own PR. I'm happy to include that change in this PR as well if you would prefer.