You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2022/06/13 12:24:42 UTC
[juneau] 01/02: Javadocs
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 <ja...@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>