Looks like documentation has been added to the Java Virtual Machine Guide, Tools Reference Guide and to "What's New in Oracle JDK 9". All looks good to me so I think this can be closed as resolved.
Answering Clifford Wayne's question, "... can we say why someone might choose to disable compact strings?"
Cases where it may be beneficial to disable Compact Strings include; one, when it is known that an application will overwhelmingly be allocating multi-byte character Strings, or possibly two, In the unexpected event where a performance regression is observed in migrating from Java 8 to Java 9 and an analysis shows Compact Strings introduces the regression. In both of these scenarios, disabling Compact Strings makes sense.
Tobias - I made the text fix described above in the Tools Ref Guide text.
An additional review comment received is: "...can we say why someone might choose to disable compact strings?"
Is there description text that can be added for this comment?
The description looks good to me but there is a little typo "Disabling the Compact Strings features" should be "Disabling the Compact Strings feature".
Added new command and text input from Charlie Hunt to the Tools Ref Guide:
Could we get the following text, or something that communicates the same in the ���Advanced Runtime Options��� section of the Java Platform, Standard Edition Tools Reference Guide Release 9 for OpenJDK on Solaris, Linux, OS X, and Windows��� .
Disables the Compact Strings feature. By default, this option is enabled. When this option is enabled, Java Strings containing only single byte characters will be internally represented and stored as single byte per character Strings using ISO-8859-1 / Latin-1 encoding. Thus reducing by 50% the amount of space required for Strings containing only single byte characters. For Java Strings containing at least one multi-byte character, these are represented and stored as two bytes per character using UTF-16 encoding. Disabling the Compact Strings features forces the use of UTF-16 encoding as the internal representation for all Java Strings.
The update is staged for review at:
Added blocking link for the Tools Ref Guide. It's listed on https://wiki.se.oracle.com/display/JPG/Compiler+doc as the primary doc for feature.
This item is listed on the new Compiler doc wiki as a Tools Ref Guide item. Should it be linked as a blocker to the Tools Ref Guide?
Maybe the new -XX:CompactStrings command line flag should also be mentioned in the 'java' section of the Tools Reference Guide.
No separate documentation beyond What's New and Migration Guide. (discussed with Jeff Dinkins)
This feature can be turned off to revert to prior behavior. This should be mentioned in the Migration Guide as well as What's New.