8353795: Add Writer.of(StringBuilder)

[mkarg]

This Pull Requests proposes an implementation for JDK-8353795: Adding the new method public static Writer Writer.of(StringBuilder), providing a non-synchronized Writer implementation optimized for writing into StringBuilder.

A basic test is provided to proof that the new Writer behaves as expected. For comparison, the same test is also run against StringWriter.

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue

Issue

• JDK-8353795: Add Writer.of(StringBuilder) (Enhancement - P4)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/24469/head:pull/24469
$ git checkout pull/24469

Update a local copy of the PR:
$ git checkout pull/24469
$ git pull https://git.openjdk.org/jdk.git pull/24469/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 24469

View PR using the GUI difftool:
$ git pr show -t 24469

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/24469.diff

Using Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back mkarg! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

❗ This change is not yet ready to be integrated.
See the Progress checklist in the description for automated requirements.

[openjdk]

@mkarg The following labels will be automatically applied to this pull request:

• core-libs
• nio

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

[mlbridge]

Webrevs

• 00: Full (75efb7fd)

[mkarg]

Continuing from thread "Request for Enhancement: java.io.Writer.of(Appendable) as an efficient alternative to java.io.StringWriter":

@liach wrote:

...we can probably start drafting the API documentation of this new API Writer.of(StringBuilder):

@return a character stream that redirects to a specified StringBuilder}
<p>
The {@code write} and {@code append} invocations are redirected to the {@code append} methods with the same parameter t>ypes on the specified StringBuilder, except {@code write(int)}, which delegates to {@code append(char)}. The {@code flush} and >{@code close} invocations have no effect.

I propose to specify this explicitly as a delegation proxy; we can infer the lack of thread safety from StringBuilder. (If we want, we can add an API note asking to use StringWriter if thread safety is needed). Also, we don't specify the toString behavior on the returned Writer (unlike for StringWriter); I think users should just use the toString on the StringBuilder.

Actually I do not see the benefit of documenting which method redirects to what other method or class, but I see that it binds us in future to today's decisions. Also I do not see what benefit notes about StringWriter and toString would be good for, as leaving it open provides most future flexibility to change eventually (just as we leave open hashCode and equals).

Having said that, instead I started the PR with a typical JavaDoc as it looks like what we did in Reader.of() recently.

WDYT?