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 ebf8c6a Javadocs.
ebf8c6a is described below
commit ebf8c6ab02625f102b5f8e61227e028d7cfbf70f
Author: JamesBognar <[email protected]>
AuthorDate: Sun Dec 19 12:33:47 2021 -0500
Javadocs.
---
.../04.HttpParts/02.HttpPartAnnotations.html | 2 +-
.../05.RestHandlingFormPosts.html | 10 +-
.../06.juneau-rest-server/06.RestSerializers.html | 133 +++++++++++++++++++--
.../juneau/rest/config/BasicUniversalRest.java | 32 +++++
4 files changed, 164 insertions(+), 13 deletions(-)
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/02.HttpPartAnnotations.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/02.HttpPartAnnotations.html
index df563e0..89111dc 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/02.HttpPartAnnotations.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/02.HttpPartAnnotations.html
@@ -276,7 +276,7 @@
Any {@link java.util.Optional} of anything on this list.
</ol>
<p>
- When used in combincation with the mutable {@link oaj.Value} object,
the {@link oaj.http.annotation.StatusCode @StatusCode} and {@link
oaj.http.annotation.Header @Header} annotations
+ When used in combination with the mutable {@link oaj.Value} object, the
{@link oaj.http.annotation.StatusCode @StatusCode} and {@link
oaj.http.annotation.Header @Header} annotations
can be used on parameters {@link oajr.annotation.RestOp
@RestOp}-annotated methods to
to define to response codes and headers.
</p>
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/05.RestHandlingFormPosts.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/05.RestHandlingFormPosts.html
index c5d13a4..5c7ec12 100644
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/05.RestHandlingFormPosts.html
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/05.RestHandlingFormPosts.html
@@ -88,7 +88,7 @@
path=<js>"/tempDir"</js>
)
<jk>public class</jk> TempDirResource <jk>extends</jk>
DirectoryResource {
-
+
<ja>@RestPost</ja>(path=<js>"/upload"</js>,
matchers=TempDirResource.MultipartFormDataMatcher.<jk>class</jk>)
<jk>public</jk> Redirect uploadFile(RestRequest <jv>req</jv>)
<jk>throws</jk> Exception {
ServletFileUpload <jv>upload</jv> = <jk>new</jk>
ServletFileUpload();
@@ -102,10 +102,10 @@
}
<jk>return new</jk> Redirect(); <jc>// Redirect to the
servlet root.</jc>
}
-
+
<jd>/** Causes a 404 if POST isn't multipart/form-data */</jd>
<jk>public static class</jk> MultipartFormDataMatcher
<jk>extends</jk> RestMatcher {
-
+
<ja>@Override</ja> <jc>/* RestMatcher */</jc>
<jk>public boolean</jk> matches(RestRequest
<jv>req</jv>) {
String <jv>contentType</jv> =
<jv>req</jv>.getContentType();
@@ -120,11 +120,11 @@
<p class='bpcode w800'>
<ja>@RestPost</ja>
<jk>public</jk> SeeOtherRoot uploadFile(RestRequest <jv>req</jv>)
<jk>throws</jk> Exception {
-
+
<jc>// Required for Jetty.</jc>
MultipartConfigElement <jv>mce</jv> = <jk>new</jk>
MultipartConfigElement((String)<jk>null</jk>);
<jv>req</jv>.setAttribute(<js>"org.eclipse.jetty.multipartConfig"</js>,
<jv>mce</jv>);
-
+
String <jv>id</jv> = UUID.<jsm>randomUUID</jsm>().toString();
BufferedImage <jv>img</jv> = <jk>null</jk>;
<jk>for</jk> (Part <jv>part</jv> : <jv>req</jv>.getParts()) {
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/06.RestSerializers.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/06.RestSerializers.html
index e6512e6..5c70408 100644
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/06.RestSerializers.html
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/06.RestSerializers.html
@@ -13,16 +13,14 @@
***************************************************************************************************************************/
-->
-{title:'Serializers', flags:'todo'}
+{title:'Marshalling', updated:'9.0.0'}
<p>
- REST resources use the {@link oaj.serializer.Serializer} API for
defining serializers for
- serializing response POJOs.
-</p>
-<p>
- The servlet will pick which serializer to use by matching the request
<l>Accept</l> header with the
- media types defined through the {@link
oaj.serializer.Serializer#getMediaTypeRanges()} method.
+ Juneau uses {@link oaj.parser.Parser Parsers} and {@link
oaj.serializer.Serializer Serializers} for marshalling
+ HTTP request and response bodies to POJOs. It uses the
<c>Content-Type</c> header to match the best
+ parser and the <c>Accept</c> header to match the best serializer.
</p>
+
<p>
Serializers can be associated with REST servlets in the following ways:
</p>
@@ -37,6 +35,127 @@
{@del oajr.RestContext#REST_serializers}
- Programmatic.
</ul>
+
+<p>
+ The {@link oaj.http.annotation.Body @Body} annotation is used to
identify POJOs to be used as the body of an HTTP request.
+</p>
+<h5 class='figure'>Examples:</h5>
+<p class='bpcode w800'>
+ <jc>// Defined on parameter</jc>
+ <ja>@RestPost</ja>
+ <jk>public void</jk> addPet(<ja>@Body</ja> Pet <jv>pet</jv>) {...}
+</p>
+<p class='bpcode w800'>
+ <jc>// Defined on POJO class</jc>
+ <ja>@RestPost</ja>
+ <jk>public void</jk> addPet(Pet <jv>pet</jv>) {...}
+
+ <ja>@Body</ja>
+ <jk>public class</jk> Pet {...}
+</p>
+
+
+
+
+
+
+
+<p>
+ This is functionally equivalent to the following code:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestPost</ja>
+ <jk>public void</jk> addPet(RestRequest <jv>req</jv>) {
+ Pet <jv>pet</jv> =
<jv>req</jv>.getBody().as(Pet.<jk>class</jk>);
+ ...
+ }
+</p>
+<p>
+ In addition to {@link oaj.http.annotation.Body @Body}-annotated
parameters/types, the body of an HTTP request
+ can be retrieved by passing in parameters of the following types
(matched in the specified order):
+</p>
+<ol class='spaced-list'>
+ <li>
+ {@link java.io.Reader}
+ <br><ja>@Body</ja> annotation is optional.
+ <br><c>Content-Type</c> is ignored.
+ <li>
+ {@link java.io.InputStream}
+ <br><ja>@Body</ja> annotation is optional.
+ <br><c>Content-Type</c> is ignored.
+ <li>
+ Any {@doc PojoCategories Parsable POJO} type.
+ <br><c>Content-Type</c> is required to identify correct parser.
+ <li>
+ Objects convertible from {@link java.io.Reader} by having one
of the following non-deprecated methods:
+ <ul>
+ <li><c><jk>public</jk> T(Reader in) {...}</c>
+ <li><c><jk>public static</jk> T
<jsm>create</jsm>(Reader in) {...}</c>
+ <li><c><jk>public static</jk> T
<jsm>fromReader</jsm>(Reader in) {...}</c>
+ </ul>
+ <c>Content-Type</c> must not be present or match an existing
parser so that it's not parsed as a POJO.
+ <li>
+ Objects convertible from {@link java.io.InputStream} by having
one of the following non-deprecated methods:
+ <ul>
+ <li><c><jk>public</jk> T(InputStream in) {...}</c>
+ <li><c><jk>public static</jk> T
<jsm>create</jsm>(InputStream in) {...}</c>
+ <li><c><jk>public static</jk> T
<jsm>fromInputStream</jsm>(InputStream in) {...}</c>
+ </ul>
+ <c>Content-Type</c> must not be present or match an existing
parser so that it's not parsed as a POJO.
+ <li>
+ Objects convertible from {@link java.lang.String} by having one
of the following non-deprecated methods:
+ <ul>
+ <li><c><jk>public</jk> T(String in) {...}</c>
+ <li><c><jk>public static</jk> T
<jsm>create</jsm>(String in) {...}</c>
+ <li><c><jk>public static</jk> T
<jsm>fromString</jsm>(String in) {...}</c>
+ <li><c><jk>public static</jk> T <jsm>parse</jsm>(String
in) {...}</c>
+ <li><c><jk>public static</jk> T
<jsm>parseString</jsm>(String in) {...}</c>
+ <li><c><jk>public static</jk> T
<jsm>forName</jsm>(String in) {...}</c>
+ <li><c><jk>public static</jk> T
<jsm>forString</jsm>(String in) {...}</c>
+ </ul>
+ Note that this also includes all enums.
+ <li>
+ Any {@link java.util.Optional} of anything on this list.
+</ol>
+<p>
+ When used in combincation with the mutable {@link oaj.Value} object,
the {@link oaj.http.annotation.StatusCode @StatusCode} and {@link
oaj.http.annotation.Header @Header} annotations
+ can be used on parameters {@link oajr.annotation.RestOp
@RestOp}-annotated methods to
+ to define to response codes and headers.
+</p>
+
+ * <p>
+ * Registers the following parsers for request bodies based on matching
<c>Content-Type</c> header:
+ * <ul class='javatreec'>
+ * <li class='jc'>{@link JsonParser}
+ * <li class='jc'>{@link SimpleJsonParser}
+ * <li class='jc'>{@link XmlParser}
+ * <li class='jc'>{@link HtmlParser}
+ * <li class='jc'>{@link UonParser}
+ * <li class='jc'>{@link UrlEncodingParser}
+ * <li class='jc'>{@link OpenApiParser}
+ * <li class='jc'>{@link MsgPackParser}
+ * <li class='jc'>{@link PlainTextParser}
+ * </ul>
+ *
+* <p>
+ * Registers the following serializers for response bodies based on matching
<c>Accept</c> header:
+ * <ul class='javatreec'>
+ * <li class='jc'>{@link HtmlDocSerializer}
+ * <li class='jc'>{@link HtmlStrippedDocSerializer}
+ * <li class='jc'>{@link HtmlSchemaDocSerializer}
+ * <li class='jc'>{@link JsonSerializer}
+ * <li class='jc'>{@link SimpleJsonSerializer}
+ * <li class='jc'>{@link JsonSchemaSerializer}
+ * <li class='jc'>{@link XmlDocSerializer}
+ * <li class='jc'>{@link UonSerializer}
+ * <li class='jc'>{@link UrlEncodingSerializer}
+ * <li class='jc'>{@link OpenApiSerializer}
+ * <li class='jc'>{@link MsgPackSerializer}
+ * <li class='jc'>{@link SoapXmlSerializer}
+ * <li class='jc'>{@link PlainTextSerializer}
+ * </ul>
+
+
<p>
The following are all equivalent ways of defining serializers used by a
resource:
</p>
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/config/BasicUniversalRest.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/config/BasicUniversalRest.java
index 1b49918..a39e837 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/config/BasicUniversalRest.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/config/BasicUniversalRest.java
@@ -31,6 +31,38 @@ import org.apache.juneau.xml.*;
* Basic configuration for a REST resource that supports all languages.
*
* <p>
+ * Registers the following parsers for request bodies based on matching
<c>Content-Type</c> header:
+ * <ul class='javatreec'>
+ * <li class='jc'>{@link JsonParser}
+ * <li class='jc'>{@link SimpleJsonParser}
+ * <li class='jc'>{@link XmlParser}
+ * <li class='jc'>{@link HtmlParser}
+ * <li class='jc'>{@link UonParser}
+ * <li class='jc'>{@link UrlEncodingParser}
+ * <li class='jc'>{@link OpenApiParser}
+ * <li class='jc'>{@link MsgPackParser}
+ * <li class='jc'>{@link PlainTextParser}
+ * </ul>
+ *
+* <p>
+ * Registers the following serializers for response bodies based on matching
<c>Accept</c> header:
+ * <ul class='javatreec'>
+ * <li class='jc'>{@link HtmlDocSerializer}
+ * <li class='jc'>{@link HtmlStrippedDocSerializer}
+ * <li class='jc'>{@link HtmlSchemaDocSerializer}
+ * <li class='jc'>{@link JsonSerializer}
+ * <li class='jc'>{@link SimpleJsonSerializer}
+ * <li class='jc'>{@link JsonSchemaSerializer}
+ * <li class='jc'>{@link XmlDocSerializer}
+ * <li class='jc'>{@link UonSerializer}
+ * <li class='jc'>{@link UrlEncodingSerializer}
+ * <li class='jc'>{@link OpenApiSerializer}
+ * <li class='jc'>{@link MsgPackSerializer}
+ * <li class='jc'>{@link SoapXmlSerializer}
+ * <li class='jc'>{@link PlainTextSerializer}
+ * </ul>
+ *
+ * <p>
* Classes that don't extend from {@link BasicRestServlet} can implement this
interface to
* be configured with the same serializers/parsers/etc... as {@link
BasicRestServlet}.
*/
