<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<p>Chen,<br>
<br>
thank you for your API documentation proposal.<br>
<br>
For me it is easier to have some code at hand to discuss about, so
I have filed a Jira-Ticket
<a class="moz-txt-link-freetext" href="https://bugs.openjdk.org/browse/JDK-8353795">https://bugs.openjdk.org/browse/JDK-8353795</a> with accompanying PR
<a class="moz-txt-link-freetext" href="https://github.com/openjdk/jdk/pull/24469">https://github.com/openjdk/jdk/pull/24469</a>, and I would propose to
continue our discussion in that PR's thread. I will adapt the PR
to stay aligned with the discussion.<br>
<br>
Regards<br>
-Markus<br>
<br>
</p>
<div class="moz-cite-prefix">Am 24.03.2025 um 04:48 schrieb Chen
Liang:<br>
</div>
<blockquote type="cite"
cite="mid:SJ2PR10MB7669CB93A994C9EF55C30ECDA2A42@SJ2PR10MB7669.namprd10.prod.outlook.com">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<style type="text/css" style="display:none;">P {margin-top:0;margin-bottom:0;}</style>
<div class="elementToProof"
style="font-family: "Calibri Light", "Helvetica Light", sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
Indeed, you are right: The Writer is for legacy APIs to consume
instead of intended for users to operate on directly. The lack
of IOE on those methods have no impact on the users. Even if we
bikeshed about try-catching the returned Writer, StringWriter
still declares to throw IOE on its close method, so returning it
as a concrete type provides little value.</div>
<div class="elementToProof"
style="font-family: "Calibri Light", "Helvetica Light", sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div class="elementToProof"
style="font-family: "Calibri Light", "Helvetica Light", sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
That said, we can probably start drafting the API documentation
of this new API Writer.of(StringBuilder):</div>
<div class="elementToProof"
style="font-family: "Calibri Light", "Helvetica Light", sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div class="elementToProof"
style="font-family: "Calibri Light", "Helvetica Light", sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
{@return a character stream that redirects to a specified
StringBuilder}</div>
<div class="elementToProof"
style="font-family: "Calibri Light", "Helvetica Light", sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<p></div>
<div class="elementToProof"
style="font-family: "Calibri Light", "Helvetica Light", sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
The {@code write} and {@code append} invocations are redirected
to the {@code append} methods with the same parameter types on
the specified StringBuilder, except {@code write(int)}, which
delegates to {@code append(char)}. The {@code flush} and {@code
close} invocations have no effect.</div>
<div class="elementToProof"
style="font-family: "Calibri Light", "Helvetica Light", sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div class="elementToProof"
style="font-family: "Calibri Light", "Helvetica Light", sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
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.</div>
<div class="elementToProof"
style="font-family: "Calibri Light", "Helvetica Light", sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div class="elementToProof"
style="font-family: "Calibri Light", "Helvetica Light", sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
Chen</div>
<div class="elementToProof"
style="font-family: "Calibri Light", "Helvetica Light", sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<hr style="display:inline-block;width:98%" tabindex="-1">
<div id="divRplyFwdMsg" dir="ltr"><font face="Calibri, sans-serif"
style="font-size:11pt" color="#000000"><b>From:</b>
core-libs-dev <a class="moz-txt-link-rfc2396E" href="mailto:core-libs-dev-retn@openjdk.org"><core-libs-dev-retn@openjdk.org></a> on behalf
of Markus KARG <a class="moz-txt-link-rfc2396E" href="mailto:markus@headcrashing.eu"><markus@headcrashing.eu></a><br>
<b>Sent:</b> Sunday, March 23, 2025 11:02 AM<br>
<b>To:</b> Chen Liang <a class="moz-txt-link-rfc2396E" href="mailto:liangchenblue@gmail.com"><liangchenblue@gmail.com></a><br>
<b>Cc:</b> core-libs-dev <a class="moz-txt-link-rfc2396E" href="mailto:core-libs-dev@openjdk.org"><core-libs-dev@openjdk.org></a><br>
<b>Subject:</b> Re: Request for Enhancement:
java.io.Writer.of(Appendable) as an efficient alternative to
java.io.StringWriter</font>
<div> </div>
</div>
<div>
<p>Chen,</p>
<p>limiting param type to StringBuilder (instead of Appendable)
really makes things easier (without standing in the way of
some future more general of() variant, eventually): We can
easily clarify in JavaDocs how things work like (in the sense
of "close and flush are no-ops"). I will prepare a PR on that
agreement to have some code at hand to discuss in detail.<br>
<br>
Restricting result type to StringWriter (instead of Writer)
IMHO is *impossible*, due to the existence of
StringWriter::getBuffer(): That method returns StringBuffer,
which is synchronized (hence spoils the core idea of
Writer.of(): being *non*-synchronized), and unfortunately also
is final (so we can't get rid of synchronized using
inheritance). Did I miss something?<br>
<br>
Anyways, I actually think that being *as least specific as
possible* regarding the actual result type is a *good* thing,
so users do not imply anything, but actually accept the rules
we lay out in the JavaDocs. We should not limit our future
possibilities to change without good reason.</p>
<p>-Markus</p>
<p><br>
</p>
<div class="x_moz-cite-prefix">Am 23.03.2025 um 10:06 schrieb
Chen Liang:<br>
</div>
<blockquote type="cite">
<div dir="ltr">Sorry for a late reply.
<div>I wonder if we should make the return type
StringWriter, given StringWriter does not throw on its
Writer methods and has a convenient toString. (Making its
close() not throws IOE is binary compatible but possibly
not source compatible)</div>
<div>I think this StringBuilder-accepting version in general
fits most of the demands, and we can make it emulate
StringWriter in a lot of behaviors and avoid the nasty
issues around closing/flushing.</div>
</div>
<br>
<div class="x_gmail_quote">
<div dir="ltr" class="x_gmail_attr">On Sat, Mar 15, 2025,
12:58 PM Markus KARG <<a
href="mailto:markus@headcrashing.eu" target="_blank"
class="x_moz-txt-link-freetext moz-txt-link-freetext"
moz-do-not-send="true">markus@headcrashing.eu</a>>
wrote:<br>
</div>
<blockquote class="x_gmail_quote"
style="margin:0px 0px 0px 0.8ex; border-left:1px solid rgb(204,204,204); padding-left:1ex">
Chen,<br>
<br>
thank you for sharing your opinion!<br>
<br>
Thinking about what you wrote about the "trifecta"
complexity, I think <br>
it might be better to restart my idea from scratch:<br>
<br>
As explained in my original proposal <br>
(<a
href="https://mail.openjdk.org/pipermail/core-libs-dev/2024-December/137807.html"
rel="noreferrer noreferrer" target="_blank"
class="x_moz-txt-link-freetext moz-txt-link-freetext"
moz-do-not-send="true">https://mail.openjdk.org/pipermail/core-libs-dev/2024-December/137807.html</a>),
<br>
the actual driver for my proposal was to provide a
StringWriter <br>
alternative which solves two main problems: It shall
prevent String <br>
copies, and it shall be non-synchronized.<br>
<br>
What comes into mind is: Writer.of(StringBuilder).<br>
<br>
While compared to Appendable this signature is much less
flexible, it <br>
also makes less headaches, but solved in fact those 99% of
cases that <br>
triggered this whole idea: It does not create String
copies, and it is <br>
non-synchronized. What this writer would simply, simply
would be routing <br>
all incoming "append" and "write" calls down to the
provided string builder.<br>
<br>
Hence, kindly asking for comments on this updated idea:
WDYT about <br>
Writer.of(StringBuilder)?<br>
<br>
Thanks!<br>
<br>
-Markus<br>
<br>
<br>
Am 10.02.2025 um 01:51 schrieb Chen Liang:<br>
> Hi Mark,<br>
> After thinking about the
Appendable-Closeable-Flushable trio versus <br>
> Writer, I believe that one problem with Writer.of is
that it goes <br>
> against interface segregation principle represented
by the trifecta, <br>
> and accidentally leaking the Closeable or Flushable
functionality is <br>
> still dubious to me. This appears simple, but it may
cause unintended <br>
> consequences, such as if Appendable b implements
Closeable too, its <br>
> closing behavior is not proxied and users may find
this inconsistency <br>
> weird. And as for interface segregation principle, it
means APIs <br>
> should request Appendable instead of Writer if they
only need writing <br>
> abilities with no lifecycle; using Writer as the type
implies <br>
> potential dependency on closing/flushing behavior,
which can sometimes <br>
> be dangerous.<br>
</blockquote>
</div>
</blockquote>
</div>
</blockquote>
</body>
</html>