This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/master by this push:
new d5b115f41 Javadocs
d5b115f41 is described below
commit d5b115f4128f2ce907b4a05463c07506c573a1a1
Author: JamesBognar <james.bog...@salesforce.com>
AuthorDate: Sat Jun 11 10:48:15 2022 -0400
Javadocs
---
juneau-doc/src/main/javadoc/overview.html | 64 +++++++++++++++++++++-
.../src/main/javadoc/resources/fragments/toc.html | 2 +-
2 files changed, 62 insertions(+), 4 deletions(-)
diff --git a/juneau-doc/src/main/javadoc/overview.html
b/juneau-doc/src/main/javadoc/overview.html
index 83df7ca58..a40251cdd 100644
--- a/juneau-doc/src/main/javadoc/overview.html
+++ b/juneau-doc/src/main/javadoc/overview.html
@@ -221,7 +221,7 @@
<li><p><a class='doclink'
href='#juneau-marshall.jm.SimpleVariableLanguage.jm.DefaultVarResolver'>VarResolver.DEFAULT</a><span
class='update'>created: 8.1.0</span></p>
<li><p><a class='doclink'
href='#juneau-marshall.jm.SimpleVariableLanguage.jm.SvlOtherNotes'>Other
Notes</a></p>
</ol>
- <li><p><a class='doclink'
href='#juneau-marshall.jm.Encoders'>Encoders</a><span class='update'>created:
<b>9.0.0</b>, <b><red>TODO</red></b></span></p>
+ <li><p><a class='doclink'
href='#juneau-marshall.jm.Encoders'>Encoders</a><span class='update'>created:
<b>9.0.0</b></span></p>
<li><p><a class='doclink'
href='#juneau-marshall.jm.HttpParts'>HTTP Parts</a><span
class='update'>created: <b>9.0.0</b>, <b><red>TODO</red></b></span></p>
<li><p><a class='doclink'
href='#juneau-marshall.jm.PojoTools'>POJO Tools</a><span
class='update'>created: <b>9.0.0</b>, <b><red>TODO</red></b></span></p>
<li><p><a class='doclink'
href='#juneau-marshall.jm.JsonDetails'>JSON Details</a></p>
@@ -6177,11 +6177,69 @@
<!--
====================================================================================================
-->
-<h3 class='topic' onclick='toggle(this)'><a
href='#juneau-marshall.jm.Encoders' id='juneau-marshall.jm.Encoders'>2.23 -
Encoders</a><span class='update'>created: <b>9.0.0</b>,
<b><red>TODO</red></b></span></h3>
+<h3 class='topic' onclick='toggle(this)'><a
href='#juneau-marshall.jm.Encoders' id='juneau-marshall.jm.Encoders'>2.23 -
Encoders</a><span class='update'>created: <b>9.0.0</b></span></h3>
<div class='topic'><!-- START: 2.23 - juneau-marshall.jm.Encoders -->
<div class='topic'>
<p>
- TODO
+ The {@link org.apache.juneau.encoders} package defines an API
for handling encoding-based matching
+ of <c>Accept-Encoding</c>/<c>Content-Encoding</c> HTTP headers.
It consists of the following classes:
+ </p>
+ <ul class='javatree'>
+ <li class='jc'>{@link org.apache.juneau.encoders.EncoderSet}
+ <li class='jcc'>{@link org.apache.juneau.encoders.Encoder}
+ <ul>
+ <li class='jc'>{@link
org.apache.juneau.encoders.IdentityEncoder}
+ <li class='jc'>{@link
org.apache.juneau.encoders.GzipEncoder}
+ </ul>
+ </ul>
+ <h5 class='topic'>EncoderSet</h5>
+ <p>
+ The {@link org.apache.juneau.encoders.EncoderSet} class
represents the set of {@link Encoder encoders} keyed by codings.
+ It maintains a set of encoders and the codings that they can
handle.
+ The {@link
org.apache.juneau.encoders.EncoderSet#getEncoderMatch(String)
getEncoderMatch(String)} and {@link
org.apache.juneau.encoders.EncoderSet#getEncoder(String)}
+ methods are then used to find appropriate encoders for specific
<c>Accept-Encoding</c> and <c>Content-Encoding</c> header values.
+ </p>
+
+ <h5 class='topic'>Match ordering</h5>
+ <p>
+ Encoders are tried in the order they appear in the set. The
{@link org.apache.juneau.encoders.EncoderSet.Builder#add(Class...)} / {@link
org.apache.juneau.encoders.EncoderSet.Builder#add(Encoder...)}
+ methods prepend the values to the list to allow them the
opportunity to override encoders already in the list.
+ </p>
+ <p>
+ For example, calling
<code>builder.add(E1.<jk>class</jk>,E2.<jk>class</jk>).add(E3.<jk>class</jk>,
+ E4.<jk>class</jk>)</code> will result in the order <c>E3, E4,
E1, E2</c>.
+ </p>
+
+ <h5 class='section'>Example:</h5>
+ <p class='bjava'>
+ <jc>// Create an encoder group with support for gzip compression.</jc>
+ EncoderSet <jv>encoders</jv> = EncoderSet
+ .<jsm>create</jsm>()
+ .add(GzipEncoder.<jk>class</jk>)
+ .build();
+
+ <jc>// Should return "gzip"</jc>
+ String <jv>matchedCoding</jv> =
<jv>encoders</jv>.findMatch(<js>"compress;q=1.0, gzip;q=0.8, identity;q=0.5,
*;q=0"</js>);
+
+ <jc>// Get the encoder</jc>
+ Encoder <jv>encoder</jv> =
<jv>encoders</jv>.getEncoder(<jv>matchedCoding</jv>);
+ </p>
+
+ <h5 class='topic'>Encoder API</h5>
+ <p>
+ The {@link org.apache.juneau.encoders.Encoder} interface is
used for enabling decompression on requests and compression on responses, such
as support for GZIP compression.
+ It is used to wrap input and output streams within
compression/decompression streams.
+ </p>
+ <ul class='javatree'>
+ <li class='jac'>{@link org.apache.juneau.encoders.Encoder}
+ <ul class='javatreec'>
+ <li class='jm'>{@link
org.apache.juneau.encoders.Encoder#getCodings() getCodings()}
+ <li class='jm'>{@link
org.apache.juneau.encoders.Encoder#getInputStream(InputStream)
getInputStream(InputStream)}
+ <li class='jm'>{@link
org.apache.juneau.encoders.Encoder#getOutputStream(OutputStream)
getOutputStream(OutputStream)}
+ </ul>
+ </ul>
+ <p>
+ Encoders are registered with <c>RestServlets</c> through the
<ja>@Rest(encoders)</ja> annotation.
</p>
</div>
</div><!-- END: 2.23 - juneau-marshall.jm.Encoders -->
diff --git a/juneau-doc/src/main/javadoc/resources/fragments/toc.html
b/juneau-doc/src/main/javadoc/resources/fragments/toc.html
index 3ad946521..cdf4ddec2 100644
--- a/juneau-doc/src/main/javadoc/resources/fragments/toc.html
+++ b/juneau-doc/src/main/javadoc/resources/fragments/toc.html
@@ -75,7 +75,7 @@
<li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-marshall.jm.SimpleVariableLanguage.jm.DefaultVarResolver'>VarResolver.DEFAULT</a><span
class='update'>created: 8.1.0</span></p>
<li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-marshall.jm.SimpleVariableLanguage.jm.SvlOtherNotes'>Other
Notes</a></p>
</ol>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-marshall.jm.Encoders'>Encoders</a><span
class='update'>created: <b>9.0.0</b>, <b><red>TODO</red></b></span></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-marshall.jm.Encoders'>Encoders</a><span
class='update'>created: <b>9.0.0</b></span></p>
<li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-marshall.jm.HttpParts'>HTTP Parts</a><span
class='update'>created: <b>9.0.0</b>, <b><red>TODO</red></b></span></p>
<li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-marshall.jm.PojoTools'>POJO Tools</a><span
class='update'>created: <b>9.0.0</b>, <b><red>TODO</red></b></span></p>
<li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-marshall.jm.JsonDetails'>JSON Details</a></p>
