RFR: 8328914: Document the java.security.debug property in javadoc [v9]

[Weijun Wang]

On Tue, 25 Feb 2025 19:37:54 GMT, Sean Coffey <coffeys at openjdk.org> wrote:

>> src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 68:
>> 
>>> 66:     system property to print additional information:
>>> 67: <ul>
>>> 68:     <li><code>+thread:</code>Print thread and caller information</li>
>> 
>> Put `:` outside `<code>`.
>> 
>> Hi @coffeys and @seanjmullan, now that we have a formal format for options and sub-options, shall we have one for these modifiers? Should it always be appended after the sub-option(s)? Like
>> 
>> x509:ava+thread,certpath:ocsp,verbose+timestamp+thread
>> 
>> On the other hand, I'm a little suspicious on the line above. If there is a comma between `oscp` and `verbose`, will it break away from `certpath`? Will `+timestamp` and `+thread` only apply to the `verbose` sub-option?
>> 
>> Also, how do we specify multiple engines in `provider`? Should it look like this?
>> 
>> provider:engine=Cipher,Mac
>> 
>> 
>> While this PR is about the doc, I really think we need a test to ensure the format is correctly described.
>
> I'd probably have to point to the CSR that introduced the +thread, +timestamp options :
> https://bugs.openjdk.org/browse/JDK-8327569
> 
> The "+" symbol should directly follow a valid debug option to be legitimate IMO. It's probably the most intuitive assumption also. 
> 
> note that I'd like to switch on `timestamp `and `thread `options by default in a JDK feature release (maybe JDK 25)
> They made more sense for the backport (JDK Update) release lines where addition of such meta data might have caused issue for some frameworks parsing this data.
> 
> I just logged https://bugs.openjdk.org/browse/JDK-8350689 to track that effort.

Anyone still cares about this comment?

I've tried `-Djava.security.debug=certpath:ocsp,verbose+timestamp` (which follows the grammar in this PR) and there is no timestamp shown. Obviously, it's broken into `certpath:ocsp` and `verbose+timestamp` at https://github.com/openjdk/jdk/blob/940aa7c4cf1bf770690660c8bb21fb3ddc5186e4/src/java.base/share/classes/sun/security/util/Debug.java#L192 and the `+timestamp` modifier is not applied to the `certpath` option.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1985290873