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
commit f2feab436ea4d3f82b8659a6d17a57db6016bcb5
Author: JamesBognar <james.bog...@salesforce.com>
AuthorDate: Mon Jun 13 08:24:00 2022 -0400
Javadocs
---
.../01.jm.org.apache.juneau.http.html | 45 +++++-
.../03.jm.org.apache.juneau.http.header.html | 171 ++++++++++++++++++---
.../04.jm.org.apache.juneau.http.part.html | 36 +++--
.../05.jm.org.apache.juneau.http.entity.html | 38 +++--
.../06.jm.org.apache.juneau.http.resource.html | 34 ++--
.../07.jm.org.apache.juneau.http.response.html | 14 ++
6 files changed, 273 insertions(+), 65 deletions(-)
diff --git
a/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/01.jm.org.apache.juneau.http.html
b/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/01.jm.org.apache.juneau.http.html
index b1652ab10..22642239e 100644
---
a/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/01.jm.org.apache.juneau.http.html
+++
b/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/01.jm.org.apache.juneau.http.html
@@ -16,12 +16,41 @@
{title:'org.apache.juneau.http', created:'9.0.0', flags:'todo'}
<div class='topic'>
-
-BasicStatusLine.java
-HttpEntities.java
-HttpHeaders.java
-HttpMethod.java
-HttpParts.java
-HttpResources.java
-HttpResponses.java
+ <p>
+ The {@link oaj.http.header} package contains various
convenience classes for creating
+ standard HTTP components using static imports.
+ </p>
+ <ul class='javatree'>
+ <li class='jc'>{@link oaj.http.HttpHeaders} - Utility class for
standard HTTP headers.
+ <li class='jc'>{@link oaj.http.HttpParts} - Utility class for
standard HTTP parts.
+ <li class='jc'>{@link oaj.http.HttpEntities} - Utility class
for standard HTTP entities.
+ <li class='jc'>{@link oaj.http.HttpResources} - Utility class
for standard HTTP resources.
+ <li class='jc'>{@link oaj.http.HttpResponses} - Utility class
for standard HTTP resources.
+ </ul>
+
+ <h5 class='topic'>HttpHeaders</h5>
+ <p>
+ TODO
+ </p>
+
+ <h5 class='topic'>HttpParts</h5>
+ <p>
+ TODO
+ </p>
+
+ <h5 class='topic'>HttpEntities</h5>
+ <p>
+ TODO
+ </p>
+
+ <h5 class='topic'>HttpResources</h5>
+ <p>
+ TODO
+ </p>
+
+ <h5 class='topic'>HttpResponses</h5>
+ <p>
+ TODO
+ </p>
+
</div>
\ No newline at end of file
diff --git
a/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/03.jm.org.apache.juneau.http.header.html
b/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/03.jm.org.apache.juneau.http.header.html
index d4856192d..ec0a035d6 100644
---
a/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/03.jm.org.apache.juneau.http.header.html
+++
b/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/03.jm.org.apache.juneau.http.header.html
@@ -82,23 +82,29 @@
TODO - Examples
</p>
<p>
- These headers extend from the following classes that provide
data-type specific functionality for each category of header.
+ These headers extend from the following classes that provide
data-type specific functionality:
</p>
<ul class='javatree'>
- <li class='jc'>{@link oaj.http.header.BasicHeader}
+ <li class='jic'>{@code org.apache.http.NameValuePair}
<ul>
- <li class='jc'>{@link
oaj.http.header.BasicBooleanHeader}
- <li class='jc'>{@link oaj.http.header.BasicCsvHeader}
- <li class='jc'>{@link oaj.http.header.BasicDateHeader}
- <li class='jc'>{@link
oaj.http.header.BasicEntityTagHeader}
- <li class='jc'>{@link
oaj.http.header.BasicEntityTagsHeader}
- <li class='jc'>{@link
oaj.http.header.BasicIntegerHeader}
- <li class='jc'>{@link oaj.http.header.BasicLongHeader}
- <li class='jc'>{@link
oaj.http.header.BasicMediaRangesHeader}
- <li class='jc'>{@link
oaj.http.header.BasicMediaTypeHeader}
- <li class='jc'>{@link oaj.http.header.BasicStringHeader}
- <li class='jc'>{@link
oaj.http.header.BasicStringRangesHeader}
- <li class='jc'>{@link oaj.http.header.BasicUriHeader}
+ <li class='jic'>{@code org.apache.http.Header}
+ <ul>
+ <li class='jc'>{@link
oaj.http.header.BasicHeader}
+ <ul class='javatreec'>
+ <li class='jc'>{@link
oaj.http.header.BasicBooleanHeader}
+ <li class='jc'>{@link
oaj.http.header.BasicCsvHeader}
+ <li class='jc'>{@link
oaj.http.header.BasicDateHeader}
+ <li class='jc'>{@link
oaj.http.header.BasicEntityTagHeader}
+ <li class='jc'>{@link
oaj.http.header.BasicEntityTagsHeader}
+ <li class='jc'>{@link
oaj.http.header.BasicIntegerHeader}
+ <li class='jc'>{@link
oaj.http.header.BasicLongHeader}
+ <li class='jc'>{@link
oaj.http.header.BasicMediaRangesHeader}
+ <li class='jc'>{@link
oaj.http.header.BasicMediaTypeHeader}
+ <li class='jc'>{@link
oaj.http.header.BasicStringHeader}
+ <li class='jc'>{@link
oaj.http.header.BasicStringRangesHeader}
+ <li class='jc'>{@link
oaj.http.header.BasicUriHeader}
+ </ul>
+ </ul>
</ul>
</ul>
<p>
@@ -108,19 +114,140 @@
<p class='bjava'>
| <jc>// Validates the response body content is not expired.</jc>
| <jv>restClient</jv>
- | .get(<jsf>URL</jsf>)
- | .run()
- |
.getHeader(<js>"Expires"</js>).asDateHeader().assertZonedDateTime().isLessThan(<jk>new</jk>
Date());
+ | .get(<jsf>URL</jsf>)
+ | .run()
+ |
.getHeader(<js>"Expires"</js>).asDateHeader().assertZonedDateTime().isLessThan(<jk>new</jk>
Date());
</p>
<h5 class='topic'>HeaderList</h5>
<p>
- The {@link HeaderList}
-
+ The {@link oaj.http.header.HeaderList} class is an thread-safe
immutable list of HTTP headers.
+ </p>
+ <h5 class='figure'>Example</h5>
+ <p class='bjava'>
+ | <jc>// Construct using builder.</jc>
+ | HeaderList <jv>headers</jv> = HeaderList
+ | .<jsm>create</jsm>()
+ | .append(Accept.<jsm>of</jsm>(<js>"text/xml"</js>))
+ | .append(<js>"Content-Type"</js>,
()-><jsm>getDynamicContentTypeFromSomewhere</jsm>())
+ | .build();
+ |
+ | <jc>// Construct using convenience creator.</jc>
+ | HeaderList <jv>headers</jv> =
HeaderList.<jsm>of</jsm>(Accept.<jsf>TEXT_XML</jsf>,
ContentType.<jsf>TEXT_XML</jsf>);
+ </p>
+ <p>
+ Header lists are immutable, but can be appended to using the
{@link oaj.http.header.HeaderList#copy() copy()} method:
+ </p>
+ <p class='bjava'>
+ | <jv>headers</jv> = <jv>headers</jv>
+ | .copy()
+ |
.append(AcceptEncoding.<jsm>of</jsm>(<js>"identity"</js>))
+ | .build();
+ </p>
+ <p>
+ Static methods are provided on {@link oaj.http.HttpHeaders} to
further simplify creation of header lists.
+ </p>
+ <p class='bjava'>
+ | <jk>import static</jk> org.apache.juneau.http.HttpHeaders.*;
+ |
+ | HeaderList <jv>headers</jv> =
<jsm>headerList</jsm>(<jsm>accept</jsm>(<js>"text/xml"</js>),
<jsm>contentType</jsm>(<js>"text/xml"</js>));
+ </p>
+ <p>
+ The builder class supports setting default header values (i.e.
add a header to the list if it isn't otherwise in the list).
+ Note that this is different from simply setting a value twice
as using default values will not overwrite existing
+ headers.
+ <br>The following example notes the distinction:
+ </p>
+ <p class='bjava'>
+ | <jv>headers</jv> = HeaderList
+ | .<jsm>create</jsm>()
+ | .set(Accept.<jsf>TEXT_PLAIN</jsf>)
+ | .set(Accept.<jsf>TEXT_XML</jsf>)
+ | .build();
+ |
<jsm>assertObject</jsm>(<jv>headers</jv>).isString(<js>"[Accept:
text/xml]"</js>);
+ |
+ | <jv>headers</jv> = HeaderList
+ | .create()
+ | .set(Accept.<jsf>TEXT_PLAIN</jsf>)
+ | .setDefault(Accept.<jsf>TEXT_XML</jsf>)
+ | .build();
+ |
<jsm>assertObject</jsm>(<jv>headers</jv>).isString(<js>"[Accept:
text/plain]"</js>);
+ </p>
-HeaderList.java
-BasicHeaderIterator.java
-SerializedHeader.java
+ <p>
+ Various methods are provided for iterating over the headers in
this list to avoid array copies.
+ </p>
+ <ul class='javatree'>
+ <li class='jm'>{@link
oaj.http.header.HeaderList#forEach(Consumer) forEach(Consumer)} / {@link
oaj.http.header.HeaderList#forEach(String,Consumer) forEach(String,Consumer)} /
{@link oaj.http.header.HeaderList#forEach(Predicate,Consumer)
forEach(Predicate,Consumer)} - Use consumers to process headers.
+ <li class='jm'>{@link oaj.http.header.HeaderList#iterator()
iterator()} / {@link oaj.http.header.HeaderList#iterator(String)
iterator(String)} - Use an {@link HeaderIterator} to process headers.
+ <li class='jm'>{@link oaj.http.header.HeaderList#stream()
stream()} / {@link oaj.http.header.HeaderList#stream(String) stream(String)} -
Use a stream.
+ </ul>
+ <p>
+ In general, try to use these over the {@link
oaj.http.header.HeaderList#getAll() getAll()} / {@link
oaj.http.header.HeaderList#getAll(String) getAll(String)} methods that require
array copies.
+ </p>
+ <p>
+ The {@link oaj.http.header.HeaderList#get(String) get(String)}
method is special in that it will collapse multiple headers with the same name
into
+ a single comma-delimited list (see <a
href='https://tools.ietf.org/html/rfc2616#section-4.2'>RFC 2616 Section 4.2</a>
for rules).
+ </p>
+ <p>
+ The {@link oaj.http.header.HeaderList#get(Class) get(Class)}
and {@link oaj.http.header.HeaderList#get(String,Class) get(String,Class)}
methods are provided for working with {@link
org.apache.juneau.http.annotation.Header}-annotated
+ beans.
+ </p>
+ <h5 class='figure'>Example</h5>
+ <p class='bjava'>
+ | ContentType <jv>contentType</jv> =
<jv>headers</jv>.get(ContentType.<jk>class</jk>);
+ </p>
+
+ <p>
+ By default, header names are treated as case-insensitive. This
can be changed using the {@link
oaj.http.header.HeaderList.Builder#caseSensitive() caseSensitive()}
+ method.
+ </p>
+ <p>
+ A {@link oaj.svl.VarResolver} can be associated with this
builder to create header values with embedded variables that
+ are resolved at runtime.
+ </p>
+
+ <h5 class='figure'>Example</h5>
+ <p class='bjava'>
+ | <jc>// Create a header list with dynamically-resolving values
pulled from a system property.</jc>
+ |
+ | System.<jsm>setProperty</jsm>(<js>"foo"</js>, <js>"bar"</js>);
+ |
+ | HeaderList <jv>headers</jv> = HeaderList
+ | .<jsm>create</jsm>()
+ | .resolving()
+ | .append(<js>"X1"</js>, <js>"$S{foo}"</js>)
+ | .append(<js>"X2"</js>, ()-><js>"$S{foo}"</js>)
+ | .build();
+ |
+ | <jsm>assertObject</jsm>(<jv>headers</jv>).isString(<js>"[X1:
bar, X2: bar]"</js>);
+ </p>
+
+ <p>
+ The {@link oaj.http.header.HeaderList} object can be extended
to defined pre-packaged lists of headers which can be used in various
+ annotations throughout the framework.
+ </p>
+ <h5 class='figure'>Example</h5>
+ <p class='bjava'>
+ | <jc>// A predefined list of headers.</jc>
+ | <jk>public class</jk> MyHeaderList <jk>extends</jk> HeaderList {
+ | <jk>public</jk> MyHeaderList() {
+ | <jk>super</jk>(Accept.<jsf>TEXT_XML</jsf>,
ContentType.<jsf>TEXT_XML</jsf>);
+ | }
+ | }
+ |
+ | <jc>// Use it on a remote proxy to add headers on all
requests.</jc>
+ | <ja>@Remote</ja>(path=<js>"/petstore"</js>,
headerList=MyHeaderList.<jk>class</jk>)
+ | <jk>public interface</jk> PetStore {
+ |
+ | <ja>@RemotePost</ja>(<js>"/pets"</js>)
+ | Pet addPet(
+ | <ja>@Body</ja> CreatePet <jv>createPet</jv>,
+ | <ja>@Header</ja>(<js>"E-Tag"</js>) UUID
<jv>etag</jv>,
+ | <ja>@Query</ja>(<js>"debug"</js>)
<jk>boolean</jk> <jv>debug</jv>
+ | );
+ | }
+ </p>
</div>
\ No newline at end of file
diff --git
a/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/04.jm.org.apache.juneau.http.part.html
b/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/04.jm.org.apache.juneau.http.part.html
index f847ff082..f5353a84e 100644
---
a/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/04.jm.org.apache.juneau.http.part.html
+++
b/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/04.jm.org.apache.juneau.http.part.html
@@ -16,20 +16,26 @@
{title:'org.apache.juneau.http.part', created:'9.0.0', flags:'todo'}
<div class='topic'>
+ <p>
+ TODO
+ </p>
+ <ul class='javatree'>
+ <li class='jic'>{@code org.apache.http.NameValuePair}
+ <ul>
+ <li class='jc'>{@link oaj.http.part.BasicPart}
+ <ul class='javatreec'>
+ <li class='jc'>{@link
oaj.http.part.BasicBooleanPart}
+ <li class='jc'>{@link
oaj.http.part.BasicCsvArrayPart}
+ <li class='jc'>{@link
oaj.http.part.BasicDatePart}
+ <li class='jc'>{@link
oaj.http.part.BasicIntegerPart}
+ <li class='jc'>{@link
oaj.http.part.BasicLongPart}
+ <li class='jc'>{@link
oaj.http.part.BasicPartIterator}
+ <li class='jc'>{@link
oaj.http.part.BasicStringPart}
+ <li class='jc'>{@link
oaj.http.part.BasicUriPart}
+ </li>
+ </ul>
+ </ul>
+
+ <h5 class='topic'>PartList</h5>
-BasicBooleanPart.java
-BasicCsvArrayPart.java
-BasicDatePart.java
-BasicIntegerPart.java
-BasicLongPart.java
-BasicPart.java
-BasicPartIterator.java
-BasicStringPart.java
-BasicUriPart.java
-NameValuePairable.java
-package-info.java
-PartBeanMeta.java
-PartIterator.java
-PartList.java
-SerializedPart.java
</div>
\ No newline at end of file
diff --git
a/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/05.jm.org.apache.juneau.http.entity.html
b/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/05.jm.org.apache.juneau.http.entity.html
index eb00c3c5c..a55350514 100644
---
a/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/05.jm.org.apache.juneau.http.entity.html
+++
b/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/05.jm.org.apache.juneau.http.entity.html
@@ -16,15 +16,31 @@
{title:'org.apache.juneau.http.entity', created:'9.0.0', flags:'todo'}
<div class='topic'>
-BasicHttpEntity.java
-ByteArrayEntity.java
-FileEntity.java
-HttpEntityBuilder.java
-InputStreamEntity.java
-package-info.java
-ReaderEntity.java
-SerializedEntity.java
-SerializedEntityBuilder.java
-StringEntity.java
-
+ <p>
+ TODO
+ </p>
+ <ul class='javatree'>
+ <li class='jic'>{@code org.apache.http.HttpEntity}
+ <ul>
+ <li class='jc'>{@link oaj.http.entity.BasicHttpEntity}
+ <ul class='javatreec'>
+ <li class='jc'>{@link
oaj.http.entity.ByteArrayEntity}
+ <li class='jc'>{@link
oaj.http.entity.FileEntity}
+ <li class='jc'>{@link
oaj.http.entity.InputStreamEntity}
+ <li class='jc'>{@link
oaj.http.entity.ReaderEntity}
+ <li class='jc'>{@link
oaj.http.entity.SerializedEntity}
+ <li class='jc'>{@link
oaj.http.entity.StringEntity}
+ </ul>
+ </ul>
+ </ul>
+
+ <h5 class='topic'>HttpEntityBuilder</h5>
+ <p>
+ TODO
+ </p>
+
+ <h5 class='topic'>SerializedEntityBuilder</h5>
+ <p>
+ TODO
+ </p>
</div>
\ No newline at end of file
diff --git
a/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/06.jm.org.apache.juneau.http.resource.html
b/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/06.jm.org.apache.juneau.http.resource.html
index 166f51cdb..e551fc94b 100644
---
a/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/06.jm.org.apache.juneau.http.resource.html
+++
b/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/06.jm.org.apache.juneau.http.resource.html
@@ -16,13 +16,29 @@
{title:'org.apache.juneau.http.resource', created:'9.0.0', flags:'todo'}
<div class='topic'>
-BasicResource.java
-ByteArrayResource.java
-FileResource.java
-HttpResource.java
-HttpResourceBuilder.java
-InputStreamResource.java
-package-info.java
-ReaderResource.java
-StringResource.java
+ <p>
+ TODO
+ </p>
+ <ul class='javatree'>
+ <li class='jic'>{@code org.apache.http.HttpEntity}
+ <ul>
+ <li class='jic'>{@link oaj.http.resource.HttpResource}
+ <ul>
+ <li class='jc'>{@link
oaj.http.resource.BasicResource}
+ <ul class='javatreec'>
+ <li class='jc'>{@link
oaj.http.resource.ByteArrayResource}
+ <li class='jc'>{@link
oaj.http.resource.FileResource}
+ <li class='jc'>{@link
oaj.http.resource.InputStreamResource}
+ <li class='jc'>{@link
oaj.http.resource.ReaderResource}
+ <li class='jc'>{@link
oaj.http.resource.StringResource}
+ </ul>
+ </ul>
+ </ul>
+ </ul>
+
+ <h5 class='topic'>HttpResourceBuilder</h5>
+ <p>
+ TODO
+ </p>
+
</div>
\ No newline at end of file
diff --git
a/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/07.jm.org.apache.juneau.http.response.html
b/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/07.jm.org.apache.juneau.http.response.html
index 3ae5fccc3..6b8bf0821 100644
---
a/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/07.jm.org.apache.juneau.http.response.html
+++
b/juneau-doc/docs/Topics/02.juneau-marshall/24.jm.HttpParts/07.jm.org.apache.juneau.http.response.html
@@ -78,6 +78,20 @@
<li class='jc'>{@link oaj.http.response.VariantAlsoNegotiates}
</ul>
+ <p>
+ These are built upon existing HttpComponents APIs:
+ </p>
+ <ul class='javatree'>
+ <li class='jic'>{@code org.apache.http.HttpMessage}
+ <ul>
+ <li class='jic'>{@code org.apache.http.HttpResponse}
+ <ul>
+ <li class='jc'>{@link
oaj.http.response.BasicHttpResponse} - 100-399 response codes
+ <li class='jc'>{@link
oaj.http.response.BasicHttpException} - 400+ response codes
+ </ul>
+ </ul>
+ </ul>
+
<p>
The most common location where these responses are used are in
REST operation methods described later.
<h5 class='figure'>Example:</h5>
