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 2021/12/05 15:30:12 UTC
[juneau] branch master updated: 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
The following commit(s) were added to refs/heads/master by this push:
new 22c0d3e Javadocs
22c0d3e is described below
commit 22c0d3eee974dce27a2f15b2eb4f0d2c3864abbb
Author: JamesBognar <ja...@salesforce.com>
AuthorDate: Sun Dec 5 10:29:30 2021 -0500
Javadocs
---
.../03.RestOpAnnotatedMethods.html | 596 ----------
.../01.InferredHttpMethodsAndPaths.html | 75 ++
.../02.JavaMethodParameters.html | 182 +++
.../03.JavaMethodReturnTypes.html | 148 +++
.../04.JavaMethodThrowableTypes.html | 96 ++
.../03.RestOpAnnotatedMethods/05.PathPatterns.html | 104 ++
.../03.RestOpAnnotatedMethods/06.Matchers.html | 70 ++
.../07.AdditionalInformation.html} | 16 +-
.../Topics/06.juneau-rest-server/04.HttpParts.html | 12 +-
...rs_PartParsers.html => 01.PartMarshallers.html} | 4 +-
.../02.Header_Path_Query_FormData.html | 227 ----
.../04.HttpParts/02.HttpPartAnnotations.html | 461 ++++++++
.../04.HttpParts/03.Body.html | 170 ---
.../{04.RequestBeans.html => 03.RequestBeans.html} | 38 +-
.../04.HttpParts/04.ResponseBeans.html | 113 ++
...RequestPathParams.html => 05.HttpPartApis.html} | 13 +-
.../05.ReponseHeader_ResponseStatus.html | 127 ---
.../04.HttpParts/06.ResponseBeans.html | 479 --------
juneau-doc/src/main/javadoc/overview.html | 1201 +++++++-------------
juneau-doc/src/main/javadoc/resources/docs.txt | 19 +-
.../src/main/javadoc/resources/fragments/toc.html | 21 +-
21 files changed, 1729 insertions(+), 2443 deletions(-)
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods.html b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods.html
index f4b02c1..ebf4f50 100644
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods.html
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods.html
@@ -80,599 +80,3 @@
<jk>return</jk> <js>"Hello world!"</js>;
}
</p>
-
-<h5 class='topic'>Inferred HTTP methods and paths</h5>
-<p>
- When the <c>name</c> and/or <c>path</c> values are not specified, their values are inferred
- from the Java method name.
-</p>
-<p>
- The HTTP method can be inferred from the Java method by starting the method name with any of the following:
-</p>
-<ul>
- <li><c>get</c>
- <li><c>put</c>
- <li><c>post</c>
- <li><c>delete</c>
- <li><c>options</c>
- <li><c>head</c>
- <li><c>trace</c>
- <li><c>patch</c>
-</ul>
-<p>
- If <c>path</c> is not defined, it's inferred from the Java method name (minus the prefix above).
-</p>
-
-<h5 class='figure'>Examples:</h5>
-<p class='bpcode w800'>
- <jc>// Method="GET", path="/foo"</jc>
- <ja>@RestOp</ja>
- <jk>public</jk> String getFoo() {...}
-</p>
-<p class='bpcode w800'>
- <jc>// Method="DELETE", path="/foo"</jc>
- <ja>@RestOp</ja>
- <jk>public</jk> String deleteFoo() {...}
-</p>
-<p class='bpcode w800'>
- <jc>// Method="GET", path="/foo"</jc>
- <jc>// "GET" is default</jc>
- <ja>@RestOp</ja>
- <jk>public</jk> String foo() {...}
-</p>
-<p class='bpcode w800'>
- <jc>// Method="GET", path="/"</jc>
- <ja>@RestOp</ja>(path=<js>"/"</js>)
- <jk>public</jk> String foo() {...}
-</p>
-<p class='bpcode w800'>
- <jc>// Method="GET", path="/"</jc>
- <ja>@RestOp</ja>
- <jk>public</jk> String get() {...}
-</p>
-<p class='bpcode w800'>
- <jc>// Method="POST", path="/"</jc>
- <ja>@RestOp</ja>
- <jk>public</jk> String post() {...}
-</p>
-
-<p>
- If <c>name</c> and <c>path</c> are both specified, the Java method name can be anything.
-</p>
-
-<h5 class='topic'>Java Method Parameters</h5>
-<p>
- Java methods can contain any of the following parameters in any order:
-</p>
-<ul class='spaced-list'>
- <li>
- <b>Parameters based on class types:</b>
- <ul class='spaced-list'>
- <li>Request objects:
- <ul class='javatreec'>
- <li class='jic'>{@link javax.servlet.AsyncContext}
- <li class='jc'>{@link oajr.CookieList}
- <li class='je'>{@link javax.servlet.DispatcherType}
- <li class='jc'>{@link oaj.httppart.HttpPartParserSession}
- <li class='jc'>{@link oaj.httppart.HttpPartSerializerSession}
- <li class='jic'>{@link javax.servlet.HttpServletRequest}
- <li class='jc'>{@link java.io.InputStream}
- <li class='jac'>{@link oaj.parser.InputStreamParser}
- <li class='jc'>{@link java.util.Locale}
- <li class='jc'>{@link oaj.cp.Messages}
- <li class='jac'>{@link oaj.parser.Parser}
- <li class='jic'>{@link java.security.Principal}
- <li class='jc'>{@link java.io.Reader}
- <li class='jac'>{@link oaj.parser.ReaderParser}
- <li class='jc'>{@link oajr.RequestAttributes}
- <li class='jc'>{@link oajr.RequestBody}
- <li class='jc'>{@link oajr.RequestFormParams}
- <li class='jc'>{@link oajr.RequestHeaders}
- <li class='jc'>{@link oajr.RequestPathParams}
- <li class='jc'>{@link oajr.RequestQueryParams}
- <li class='jc'>{@link java.util.ResourceBundle}
- <li class='jc'>{@link oajr.RestRequest}
- <li class='jic'>{@link javax.servlet.ServletInputStream}
- <li class='jc'>{@link oaj.dto.swagger.Swagger}
- <li class='jc'>{@link java.util.TimeZone}
- <li class='jc'>{@link oaj.UriContext}
- <li class='jc'>{@link oaj.UriResolver}
- <li class='jc'>{@link oaj.svl.VarResolverSession}
- </ul>
- <li>Response objects:
- <ul class='javatreec'>
- <li class='jic'>{@link javax.servlet.HttpServletResponse}
- <li class='jc'>{@link java.io.OutputStream}
- <li class='jc'>{@link oajr.RestResponse}
- <li class='jic'>{@link javax.servlet.ServletOutputStream}
- <li class='jc'>{@link java.io.Writer}
- </ul>
- <li>Session objects:
- <ul class='javatreec'>
- <li class='jic'>{@link javax.servlet.http.HttpSession}
- <li class='jc'>{@link oajr.RestSession}
- <li class='jc'>{@link oajr.util.UrlPath}
- <li class='jc'>{@link oajr.util.UrlPathMatch}
- <li class='jc'>{@link oaj.cp.BeanStore}
- <li class='jc'>{@link oajr.RestOpSession}
- </ul>
- <li>Parsed request header values:
- <ul class='javatreec'>
- <li class='jc'>{@link oaj.http.header.Accept}
- <li class='jc'>{@link oaj.http.header.AcceptCharset}
- <li class='jc'>{@link oaj.http.header.AcceptEncoding}
- <li class='jc'>{@link oaj.http.header.AcceptLanguage}
- <li class='jc'>{@link oaj.http.header.AcceptRanges}
- <li class='jc'>{@link oaj.http.header.Authorization}
- <li class='jc'>{@link oaj.http.header.CacheControl}
- <li class='jc'>{@link oaj.http.header.ClientVersion}
- <li class='jc'>{@link oaj.http.header.Connection}
- <li class='jc'>{@link oaj.http.header.ContentDisposition}
- <li class='jc'>{@link oaj.http.header.ContentEncoding}
- <li class='jc'>{@link oaj.http.header.ContentLength}
- <li class='jc'>{@link oaj.http.header.ContentType}
- <li class='jc'>{@link oaj.http.header.Date}
- <li class='jc'>{@link oaj.http.header.Debug}
- <li class='jc'>{@link oaj.http.header.Expect}
- <li class='jc'>{@link oaj.http.header.Forwarded}
- <li class='jc'>{@link oaj.http.header.From}
- <li class='jc'>{@link oaj.http.header.Host}
- <li class='jc'>{@link oaj.http.header.IfMatch}
- <li class='jc'>{@link oaj.http.header.IfModifiedSince}
- <li class='jc'>{@link oaj.http.header.IfNoneMatch}
- <li class='jc'>{@link oaj.http.header.IfRange}
- <li class='jc'>{@link oaj.http.header.IfUnmodifiedSince}
- <li class='jc'>{@link oaj.http.header.MaxForwards}
- <li class='jc'>{@link oaj.http.header.NoTrace}
- <li class='jc'>{@link oaj.http.header.Origin}
- <li class='jc'>{@link oaj.http.header.Pragma}
- <li class='jc'>{@link oaj.http.header.ProxyAuthorization}
- <li class='jc'>{@link oaj.http.header.Range}
- <li class='jc'>{@link oaj.http.header.Referer}
- <li class='jc'>{@link oaj.http.header.TE}
- <li class='jc'>{@link oaj.http.header.Thrown}
- <li class='jc'>{@link oaj.http.header.Upgrade}
- <li class='jc'>{@link oaj.http.header.UserAgent}
- <li class='jc'>{@link oaj.http.header.Warning}
- </ul>
- <li>Context values:
- <ul class='javatreec'>
- <li class='jc'>{@link oaj.BeanContext}
- <li class='jc'>{@link oaj.config.Config}
- <li class='jic'>{@link oajr.DebugEnablement}
- <li class='jc'>{@link oaj.encoders.EncoderSet}
- <li class='jic'>{@link oaj.cp.FileFinder}
- <li class='jc'>{@link oaj.jsonschema.JsonSchemaGenerator}
- <li class='jc'>{@link java.util.Logger}
- <li class='jc'>{@link oaj.mstat.MethodExecStore}
- <li class='jc'>{@link oaj.parser.ParserSet}
- <li class='jc'>{@link oajr.RestChildren}
- <li class='jc'>{@link oajr.RestContext}
- <li class='jc'>{@link oajr.RestContextStats}
- <li class='jic'>{@link oajr.logging.RestLogger}
- <li class='jc'>{@link oajr.RestOpContext}
- <li class='jc'>{@link oajr.RestOperations}
- <li class='jc'>{@link oaj.serializer.SerializerSet}
- <li class='jic'>{@link oajr.StaticFiles}
- <li class='jc'>{@link oaj.mstat.ThrownStore}
- </ul>
- </ul>
- <li><b>Annotated parameters (either on the parameter or parameter type):</b>
- <ul class='javatreec'>
- <li class='ja'>{@link oajr.annotation.Attr}
- <li class='ja'>{@link oaj.http.annotation.Body}
- <li class='ja'>{@link oaj.http.annotation.Path}
- <li class='ja'>{@link oaj.http.annotation.FormData}
- <li class='ja'>{@link oaj.http.annotation.HasFormData}
- <li class='ja'>{@link oaj.http.annotation.Query}
- <li class='ja'>{@link oaj.http.annotation.HasQuery}
- <li class='ja'>{@link oaj.http.annotation.Header}
- <li class='ja'>{@link oajr.annotation.Method}
- <li class='ja'>{@link oaj.http.annotation.Request}
- <li class='ja'>{@link oaj.http.annotation.Response}
- <li class='ja'>{@link oaj.http.annotation.ResponseHeader}
- <li class='ja'>{@link oaj.http.annotation.ResponseCode}
- </ul>
-</ul>
-<p>
- In Spring Boot environments, any available Spring Beans can also be passed in as parameters.
-</p>
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/example1/{a1}/{a2}/{a3}/*"</js>)
- <jk>public</jk> String doGetExample1(
- RestRequest <jv>req</jv>,
- RestResponse <jv>res</jv>,
- <ja>@Method</ja> String <jv>method</jv>,
- <ja>@Path</ja>(<js>"a1"</js>) String <jv>a1</jv>,
- <ja>@Path</ja>(<js>"a2"</js>) <jk>int</jk> <jv>a2</jv>,
- <ja>@Path</ja>(<js>"a3"</js>) UUID <jv>a3</jv>,
- <ja>@Query</ja>(<js>"p1"</js>) <jk>int</jk> <jv>p1</jv>,
- <ja>@Query</ja>(<js>"p2"</js>) String <jv>p2</jv>,
- <ja>@Query</ja>(<js>"p3"</js>) UUID <jv>p3</jv>,
- <ja>@HasQuery</ja>(<js>"p3"</js>) boolean <jv>hasP3</jv>,
- <ja>@Path</ja>(<js>"/*"</js>) String <jv>remainder</jv>,
- <ja>@Header</ja>(<js>"Accept-Language"</js>) String <jv>lang</jv>,
- <ja>@Header</ja>(<js>"Accept"</js>) String <jv>accept</jv>,
- <ja>@Header</ja>(<js>"DNT"</js>) <jk>int</jk> <jv>doNotTrack</jv>,
- RequestAttributes <jv>attributes</jv>,
- ResourceBundle <jv>nls</jv>
- ) {
- <jc>// Do something with all of those</jc>
- }
-</p>
-<p>
- Additional parameter types can be defined by overriding {@link oajr.RestContext.Builder#createRestOpArgs(BeanStore,Supplier)} or
- by adding them to the bean store using {@link oajr.RestContext.Builder#createBeanStore(Class,Supplier)}.
-</p>
-
-<h5 class='topic'>Java Method Return Types</h5>
-<p>
- The return type of the Java method can be any serializable POJO as defined in {@doc PojoCategories POJO Categories}.
- It can also be <jk>void</jk> if the method is not sending any output (e.g. a request redirect) or is
- setting the output using the {@link oajr.RestResponse#setOutput(Object)} method.
-</p>
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>
- <jk>public</jk> String doGet() {
- <jk>return</jk> <js>"Hello World!"</js>;
- }
-</p>
-<p>
- In addition to POJOs, the following return types are also supported:
-</p>
-<ul class='spaced-list'>
- <li>
- <b>Parameters based on class types:</b>
- <ul class='spaced-list'>
- <li>Direct streams:
- <ul class='javatreec'>
- <li class='jc'>{@link java.io.InputStream}
- <li class='jc'>{@link java.io.Reader}
- </ul>
- <li>Apache HttpComponent beans:
- <ul class='javatreec'>
- <li class='jic'>{@link org.apache.http.HttpEntity}
- <li class='jic'>{@link oaj.http.resource.HttpResource}
- <li class='jic'>{@link org.apache.http.HttpResponse}
- </ul>
- <li>Standard HTTP response beans:
- <ul class='javatreec'>
- <li class='jc'>{@link oaj.http.response.Accepted}
- <li class='jc'>{@link oaj.http.response.AlreadyReported}
- <li class='jc'>{@link oaj.http.response.BadRequest}
- <li class='jc'>{@link oaj.http.response.Conflict}
- <li class='jc'>{@link oaj.http.response.Continue}
- <li class='jc'>{@link oaj.http.response.Created}
- <li class='jc'>{@link oaj.http.response.EarlyHints}
- <li class='jc'>{@link oaj.http.response.ExpectationFailed}
- <li class='jc'>{@link oaj.http.response.FailedDependency}
- <li class='jc'>{@link oaj.http.response.Forbidden}
- <li class='jc'>{@link oaj.http.response.Found}
- <li class='jc'>{@link oaj.http.response.Gone}
- <li class='jc'>{@link oaj.http.response.HttpVersionNotSupported}
- <li class='jc'>{@link oaj.http.response.IMUsed}
- <li class='jc'>{@link oaj.http.response.InsufficientStorage}
- <li class='jc'>{@link oaj.http.response.InternalServerError}
- <li class='jc'>{@link oaj.http.response.LengthRequired}
- <li class='jc'>{@link oaj.http.response.Locked}
- <li class='jc'>{@link oaj.http.response.LoopDetected}
- <li class='jc'>{@link oaj.http.response.MethodNotAllowed}
- <li class='jc'>{@link oaj.http.response.MisdirectedRequest}
- <li class='jc'>{@link oaj.http.response.MovedPermanently}
- <li class='jc'>{@link oaj.http.response.MultipleChoices}
- <li class='jc'>{@link oaj.http.response.MultiStatus}
- <li class='jc'>{@link oaj.http.response.NetworkAuthenticationRequired}
- <li class='jc'>{@link oaj.http.response.NoContent}
- <li class='jc'>{@link oaj.http.response.NonAuthoritiveInformation}
- <li class='jc'>{@link oaj.http.response.NotAcceptable}
- <li class='jc'>{@link oaj.http.response.NotExtended}
- <li class='jc'>{@link oaj.http.response.NotFound}
- <li class='jc'>{@link oaj.http.response.NotImplemented}
- <li class='jc'>{@link oaj.http.response.NotModified}
- <li class='jc'>{@link oaj.http.response.Ok}
- <li class='jc'>{@link oaj.http.response.PartialContent}
- <li class='jc'>{@link oaj.http.response.PayloadTooLarge}
- <li class='jc'>{@link oaj.http.response.PermanentRedirect}
- <li class='jc'>{@link oaj.http.response.PreconditionFailed}
- <li class='jc'>{@link oaj.http.response.PreconditionRequired}
- <li class='jc'>{@link oaj.http.response.Processing}
- <li class='jc'>{@link oaj.http.response.RangeNotSatisfiable}
- <li class='jc'>{@link oaj.http.response.RequestHeaderFieldsTooLarge}
- <li class='jc'>{@link oaj.http.response.ResetContent}
- <li class='jc'>{@link oaj.http.response.SeeOther}
- <li class='jc'>{@link oaj.http.response.ServiceUnavailable}
- <li class='jc'>{@link oaj.http.response.SwitchingProtocols}
- <li class='jc'>{@link oaj.http.response.TemporaryRedirect}
- <li class='jc'>{@link oaj.http.response.TooManyRequests}
- <li class='jc'>{@link oaj.http.response.Unauthorized}
- <li class='jc'>{@link oaj.http.response.UnavailableForLegalReasons}
- <li class='jc'>{@link oaj.http.response.UnprocessableEntity}
- <li class='jc'>{@link oaj.http.response.UnsupportedMediaType}
- <li class='jc'>{@link oaj.http.response.UpgradeRequired}
- <li class='jc'>{@link oaj.http.response.UriTooLong}
- <li class='jc'>{@link oaj.http.response.UseProxy}
- <li class='jc'>{@link oaj.http.response.VariantAlsoNegotiates}
- </ul>
- <li>Other:
- <ul class='javatreec'>
- <li class='jc'>{@link oajr.beans.ChildResourceDescriptions}
- <li class='jc'>{@link oajr.beans.ResourceDescriptions}
- <li class='jc'>{@link oajr.beans.SeeOtherRoot}
- <li class='jc'>{@link java.lang.Throwable}
- </ul>
- </ul>
- <li><b>Annotated parameters (either on the parameter or parameter type):</b>
- <ul class='javatreec'>
- <li class='ja'>{@link oaj.http.annotation.Response}
- </ul>
-</ul>
-<p>
- REST Java methods can also generate a response via the following:
-</p>
-<ul class='spaced-list'>
- <li>
- By calling {@link oajr.RestResponse#setOutput(Object)} with any of the types above.
- <li>
- By accessing the {@link java.io.Writer} directly by calling
- {@link oajr.RestResponse#getNegotiatedWriter()} and writing the output yourself.
-</ul>
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <jc>// Equivalent method 1</jc>
- <ja>@RestGet</ja>(<js>"/example1/{personId}"</js>)
- <jk>public</jk> Person doGet1(<ja>@Path</ja>(<js>"personId"</js>) UUID <jv>personId</jv>) {
- Person <jv>person</jv> = <jsm>getPersonById</jsm>(<jv>personId</jv>);
- <jk>return</jk> <jv>person</jv>;
- }
-
- <jc>// Equivalent method 2</jc>
- <ja>@RestGet</ja>(<js>"/example2/{personId}"</js>)
- <jk>public void</jk> doGet2(RestResponse <jv>res</jv>, <ja>@Path</ja>(<js>"personId"</js>) UUID personId) {
- Person <jv>person</jv> = <jsm>getPersonById</jsm>(<jv>personId</jv>);
- <jv>res</jv>.setOutput(<jv>person</jv>);
- }
-</p>
-<p>
- Additional parameter types can be defined by overriding {@link oajr.RestContext.Builder#createResponseProcessors(BeanStore,Supplier)}.
-</p>
-
-<h5 class='topic'>Java Method Throwable Types</h5>
-<p>
- Annotated Java methods can throw any of the following:
-</p>
-<ul class='spaced-list'>
- <li>Standard HTTP response beans:
- <ul class='javatreec'>
- <li class='jc'>{@link oaj.http.response.BadRequest}
- <li class='jc'>{@link oaj.http.response.Conflict}
- <li class='jc'>{@link oaj.http.response.ExpectationFailed}
- <li class='jc'>{@link oaj.http.response.FailedDependency}
- <li class='jc'>{@link oaj.http.response.Forbidden}
- <li class='jc'>{@link oaj.http.response.Gone}
- <li class='jc'>{@link oaj.http.response.HttpVersionNotSupported}
- <li class='jc'>{@link oaj.http.response.InsufficientStorage}
- <li class='jc'>{@link oaj.http.response.InternalServerError}
- <li class='jc'>{@link oaj.http.response.LengthRequired}
- <li class='jc'>{@link oaj.http.response.Locked}
- <li class='jc'>{@link oaj.http.response.LoopDetected}
- <li class='jc'>{@link oaj.http.response.MethodNotAllowed}
- <li class='jc'>{@link oaj.http.response.MisdirectedRequest}
- <li class='jc'>{@link oaj.http.response.NetworkAuthenticationRequired}
- <li class='jc'>{@link oaj.http.response.NotAcceptable}
- <li class='jc'>{@link oaj.http.response.NotExtended}
- <li class='jc'>{@link oaj.http.response.NotFound}
- <li class='jc'>{@link oaj.http.response.NotImplemented}
- <li class='jc'>{@link oaj.http.response.PayloadTooLarge}
- <li class='jc'>{@link oaj.http.response.PreconditionFailed}
- <li class='jc'>{@link oaj.http.response.PreconditionRequired}
- <li class='jc'>{@link oaj.http.response.RangeNotSatisfiable}
- <li class='jc'>{@link oaj.http.response.RequestHeaderFieldsTooLarge}
- <li class='jc'>{@link oaj.http.response.ServiceUnavailable}
- <li class='jc'>{@link oaj.http.response.TooManyRequests}
- <li class='jc'>{@link oaj.http.response.Unauthorized}
- <li class='jc'>{@link oaj.http.response.UnavailableForLegalReasons}
- <li class='jc'>{@link oaj.http.response.UnprocessableEntity}
- <li class='jc'>{@link oaj.http.response.UnsupportedMediaType}
- <li class='jc'>{@link oaj.http.response.UpgradeRequired}
- <li class='jc'>{@link oaj.http.response.UriTooLong}
- <li class='jc'>{@link oaj.http.response.VariantAlsoNegotiates}
- </ul>
- <li>Annotated throwables:
- <ul class='javatreec'>
- <li class='ja'>{@link oaj.http.annotation.Response}
- </ul>
-</ul>
-<p>
- All other throwables get processed as follows:
-</p>
-<ul class='spaced-list'>
- <li>Processed as 400/Bad Request:
- <ul class='javatreec'>
- <li class='jc'>{@link oaj.parser.ParseException}
- <li class='jc'>{@link oaj.InvalidDataConversionException}
- </ul>
- <li>Processed as 401/Unauthorized:
- <ul>
- <li>Any class named <js>"*AccessDenied*"</js> or <js>"*Unauthorized*"</js>
- </ul>
- <li>Processed as 404/Not Found:
- <ul>
- <li>Any class named <js>"*Empty*"</js> or <js>"*NotFound*"</js>
- </ul>
- <li>Anything else processed as 500/Internal Server Error.
-</ul>
-
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/user/login"</js>)
- <jk>public</jk> Ok login(
- <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
- <ja>@FormData</ja>(<js>"password"</js>) String <jv>password</jv>
- ) <jk>throws</jk> Unauthorized
- {
- <jk>if</jk> (! <jsm>isOK</jsm>(<jv>username</jv>, <jv>password</jv>))
- <jk>throw new</jk> Unauthorized(<js>"You're not welcome!"</js>);
-
- <jk>return</jk> Ok.<jsf>OK</jsf>;
- }
-</p>
-
-<h5 class='topic'>Path Patterns</h5>
-<p>
- The {@link oajr.annotation.RestOp#path() @RestOp(path)} annotation allows
- you to define URL path patterns to match against.
- These patterns can contain variables of the form <l>"{xxx}"</l> that can be passed in directly to the
- Java methods as extra parameters.
-</p>
-<p>
- In the following example, 3 separate GET request handlers are defined with different path patterns.
- Note how the variables are passed in as additional arguments on the method, and how those arguments are
- automatically converted to the specified class type...
-</p>
-<p class='bpcode w800'>
- <jc>// Default method</jc>
- <ja>@RestGet</ja>(path=<js>"/*"</js>)
- <jk>public void</jk> doGetDefault() {
- ...
- }
-
- <jc>// Method with path pattern</jc>
- <ja>@RestGet</ja>(path=<js>"/xxx"</js>)
- <jk>public void</jk> doGetNoArgs(...) {
- ...
- }
-
- <jc>// Method with path pattern with arguments</jc>
- <ja>@RestGet</ja>(path=<js>"/xxx/{foo}/{bar}/{baz}/{bing}"</js>)
- <jk>public void</jk> doGetWithArgs(
- <ja>@Path</ja>(<js>"foo"</js>) String <jv>foo</jv>,
- <ja>@Path</ja>(<js>"bar"</js>) <jk>int</jk> <jv>bar</jv>,
- <ja>@Path</ja>(<js>"baz"</js>) MyEnum <jv>baz</jv>,
- <ja>@Path</ja>(<js>"bing"</js>) UUID <jv>qux</jv>
- ) {
- ...
- }
-</p>
-<p>
- By default, path patterns are matched using a best-match heuristic.
- When overlaps occur, URLs are matched from most-specific to most-general order:
-</p>
-<p class='bpcode w800'>
- <jc>// Try first </jc>
- <ja>@RestGet</ja>(<js>"/foo/bar"</js>)
- <jk>public void</jk> method1() {
- ...
- }
-
- <jc>// Try second</jc>
- <ja>@RestGet</ja>(<js>"/foo/{bar}"</js>)
- <jk>public void</jk> method2(...) {
- ...
- }
-
- <jc>// Try third</jc>
- <ja>@RestGet</ja>(<js>"/foo/*"</js>)
- <jk>public void</jk> method3(...) {
- ...
- }
-
- <jc>// Try last</jc>
- <ja>@RestGet</ja>(<js>"/*"</js>)
- <jk>public void</jk> method4(...) {
- ...
- }
-</p>
-<p>
- Paths that end with <js>"/*"</js> will do a prefix match on the incoming URL.
- Any remainder after the match can be accessed through
- {@link oajr.RequestPathParams#getRemainder()} or parameters with the
- <c><ja>@Path</ja>(<js>"/*"</js>)</c> annotation.
- On the other hand, paths that don't end with <js>"/*"</js> (e.g. <js>"/"</js> or <js>"/foo"</js>) will
- require an exact URL match, and if any remainder exists, a 404 (not found) error will be thrown.
-</p>
-<p>
- The following example shows the distinction.
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/*"</js>)
- <jk>public void</jk> doGet(<ja>@Path</ja>(<js>"/*"</js>) String <jv>remainder</jv>) {
- <jc>// URL path pattern can have remainder accessible through req.getRemainder().</jc>
- }
-
- <ja>@RestPut</ja>(<js>"/"</js>)
- <jk>public void</jk> doPut() {
- <jc>// URL path pattern must match exactly and will cause a 404 error if a remainder exists.</jc>
- }
-</p>
-
-<h5 class='topic'>Matchers</h5>
-<p>
- {@link oajr.RestMatcher RestMatchers} are used to allow multiple Java methods to be
- tied to the same HTTP method and path, but differentiated by some request attribute such as a specific
- header value.
-</p>
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <jc>// GET method that gets invoked for administrators</jc>
- <ja>@RestGet</ja>(path=<js>"/*"</js>, matchers=IsAdminMatcher.<jk>class</jk>)
- <jk>public</jk> Object doGetForAdmin() {
- ...
- }
-
- <jc>// GET method that gets invoked for everyone else</jc>
- <ja>@RestGet</ja>(<js>"/*"</js>)
- <jk>public</jk> Object doGetForEveryoneElse() {
- ...
- }
-</p>
-<p>
- The interface for matchers is simple:
-</p>
-<p class='bpcode w800'>
- <jk>public class</jk> IsAdminMatcher <jk>extends</jk> RestMatcher {
-
- <ja>@Override</ja> <jc>/* RestMatcher */</jc>
- <jk>public boolean</jk> matches(RestRequest <jv>req</jv>) {
- <jk>return</jk> <jv>req</jv>.isUserInRole(<js>"ADMINS_GROUP"</js>);
- }
- }
-</p>
-
-<ul class='notes'>
- <li class='note'>
- If no methods are found with a matching matcher, a <l>412 Precondition Failed</l> status is returned.
- <li class='note'>
- If multiple matchers are specified on the same method, ONLY ONE matcher needs to match for the
- method to be invoked.
- <li class='note'>
- Note that you CANNOT define identical paths on different methods UNLESS you use matchers.
- <br>That includes paths that are only different in variable names (e.g. <l>"/foo/{bar}"</l> and
- <l>"/foo/{baz}"</l>).
- <br>If you try to do so, a <l>ServletException</l> will be thrown on startup.
- <li class='note'>
- Methods with matchers take precedence over methods without.
- <br>Otherwise, methods are attempted in the order they appear in the class.
-</ul>
-
-<ul class='seealso'>
- <li class='ja'>{@link oajr.annotation.RestOp#matchers RestOp(matchers)}
- <li class='jc'>{@link oajr.matchers.MultipartFormDataMatcher}
- <li class='jc'>{@link oajr.matchers.UrlEncodedFormMatcher}
-</ul>
-
-<h5 class='topic'>More Information</h5>
-<p>
- Refer to the following Javadocs for more information:
-</p>
-<ul class='javatreec w900'>
- <li class='jc'>{@link oajr.RestRequest}
- <li class='jc'>{@link oajr.RestResponse}
- <li class='jc'>{@link oajr.RequestBody}
- <li class='jc'>{@link oajr.RequestHeaders}
- <li class='jc'>{@link oajr.RequestQueryParams}
- <li class='jc'>{@link oajr.RequestFormParams}
- <li class='jc'>{@link oajr.RequestPathParams}
- <li class='jc'>{@link oajr.RequestAttributes}
-</ul>
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/01.InferredHttpMethodsAndPaths.html b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/01.InferredHttpMethodsAndPaths.html
new file mode 100644
index 0000000..41fcd4c
--- /dev/null
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/01.InferredHttpMethodsAndPaths.html
@@ -0,0 +1,75 @@
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ ***************************************************************************************************************************/
+ -->
+
+{title:'Inferred HTTP Methods and Paths', updated:'9.0.0'}
+
+<p>
+ When the <c>name</c> and/or <c>path</c> values are not specified, their values are inferred
+ from the Java method name.
+</p>
+<p>
+ The HTTP method can be inferred from the Java method by starting the method name with any of the following:
+</p>
+<ul>
+ <li><c>get</c>
+ <li><c>put</c>
+ <li><c>post</c>
+ <li><c>delete</c>
+ <li><c>options</c>
+ <li><c>head</c>
+ <li><c>trace</c>
+ <li><c>patch</c>
+</ul>
+<p>
+ If <c>path</c> is not defined, it's inferred from the Java method name (minus the prefix above).
+</p>
+
+<h5 class='figure'>Examples:</h5>
+<p class='bpcode w800'>
+ <jc>// Method="GET", path="/foo"</jc>
+ <ja>@RestOp</ja>
+ <jk>public</jk> String getFoo() {...}
+</p>
+<p class='bpcode w800'>
+ <jc>// Method="DELETE", path="/foo"</jc>
+ <ja>@RestOp</ja>
+ <jk>public</jk> String deleteFoo() {...}
+</p>
+<p class='bpcode w800'>
+ <jc>// Method="GET", path="/foo"</jc>
+ <jc>// "GET" is default</jc>
+ <ja>@RestOp</ja>
+ <jk>public</jk> String foo() {...}
+</p>
+<p class='bpcode w800'>
+ <jc>// Method="GET", path="/"</jc>
+ <ja>@RestOp</ja>(path=<js>"/"</js>)
+ <jk>public</jk> String foo() {...}
+</p>
+<p class='bpcode w800'>
+ <jc>// Method="GET", path="/"</jc>
+ <ja>@RestOp</ja>
+ <jk>public</jk> String get() {...}
+</p>
+<p class='bpcode w800'>
+ <jc>// Method="POST", path="/"</jc>
+ <ja>@RestOp</ja>
+ <jk>public</jk> String post() {...}
+</p>
+
+<p>
+ If <c>name</c> and <c>path</c> are both specified, the Java method name can be anything.
+</p>
+
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/02.JavaMethodParameters.html b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/02.JavaMethodParameters.html
new file mode 100644
index 0000000..664ad8c
--- /dev/null
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/02.JavaMethodParameters.html
@@ -0,0 +1,182 @@
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ ***************************************************************************************************************************/
+ -->
+
+{title:'Java Method Parameters', updated:'9.0.0'}
+
+<p>
+ Java methods can contain any of the following parameters in any order:
+</p>
+<ul class='spaced-list'>
+ <li>
+ <b>Parameters based on class types:</b>
+ <ul class='spaced-list'>
+ <li>Request objects:
+ <ul class='javatreec'>
+ <li class='jic'>{@link javax.servlet.AsyncContext}
+ <li class='jc'>{@link oajr.CookieList}
+ <li class='je'>{@link javax.servlet.DispatcherType}
+ <li class='jc'>{@link oaj.httppart.HttpPartParserSession}
+ <li class='jc'>{@link oaj.httppart.HttpPartSerializerSession}
+ <li class='jic'>{@link javax.servlet.HttpServletRequest}
+ <li class='jc'>{@link java.io.InputStream}
+ <li class='jac'>{@link oaj.parser.InputStreamParser}
+ <li class='jc'>{@link java.util.Locale}
+ <li class='jc'>{@link oaj.cp.Messages}
+ <li class='jac'>{@link oaj.parser.Parser}
+ <li class='jic'>{@link java.security.Principal}
+ <li class='jc'>{@link java.io.Reader}
+ <li class='jac'>{@link oaj.parser.ReaderParser}
+ <li class='jc'>{@link oajr.RequestAttributes}
+ <li class='jc'>{@link oajr.RequestBody}
+ <li class='jc'>{@link oajr.RequestFormParams}
+ <li class='jc'>{@link oajr.RequestHeaders}
+ <li class='jc'>{@link oajr.RequestPathParams}
+ <li class='jc'>{@link oajr.RequestQueryParams}
+ <li class='jc'>{@link java.util.ResourceBundle}
+ <li class='jc'>{@link oajr.RestRequest}
+ <li class='jic'>{@link javax.servlet.ServletInputStream}
+ <li class='jc'>{@link oaj.dto.swagger.Swagger}
+ <li class='jc'>{@link java.util.TimeZone}
+ <li class='jc'>{@link oaj.UriContext}
+ <li class='jc'>{@link oaj.UriResolver}
+ <li class='jc'>{@link oaj.svl.VarResolverSession}
+ </ul>
+ <li>Response objects:
+ <ul class='javatreec'>
+ <li class='jic'>{@link javax.servlet.HttpServletResponse}
+ <li class='jc'>{@link java.io.OutputStream}
+ <li class='jc'>{@link oajr.RestResponse}
+ <li class='jic'>{@link javax.servlet.ServletOutputStream}
+ <li class='jc'>{@link java.io.Writer}
+ </ul>
+ <li>Session objects:
+ <ul class='javatreec'>
+ <li class='jic'>{@link javax.servlet.http.HttpSession}
+ <li class='jc'>{@link oajr.RestSession}
+ <li class='jc'>{@link oajr.util.UrlPath}
+ <li class='jc'>{@link oajr.util.UrlPathMatch}
+ <li class='jc'>{@link oaj.cp.BeanStore}
+ <li class='jc'>{@link oajr.RestOpSession}
+ </ul>
+ <li>Parsed request header values:
+ <ul class='javatreec'>
+ <li class='jc'>{@link oaj.http.header.Accept}
+ <li class='jc'>{@link oaj.http.header.AcceptCharset}
+ <li class='jc'>{@link oaj.http.header.AcceptEncoding}
+ <li class='jc'>{@link oaj.http.header.AcceptLanguage}
+ <li class='jc'>{@link oaj.http.header.AcceptRanges}
+ <li class='jc'>{@link oaj.http.header.Authorization}
+ <li class='jc'>{@link oaj.http.header.CacheControl}
+ <li class='jc'>{@link oaj.http.header.ClientVersion}
+ <li class='jc'>{@link oaj.http.header.Connection}
+ <li class='jc'>{@link oaj.http.header.ContentDisposition}
+ <li class='jc'>{@link oaj.http.header.ContentEncoding}
+ <li class='jc'>{@link oaj.http.header.ContentLength}
+ <li class='jc'>{@link oaj.http.header.ContentType}
+ <li class='jc'>{@link oaj.http.header.Date}
+ <li class='jc'>{@link oaj.http.header.Debug}
+ <li class='jc'>{@link oaj.http.header.Expect}
+ <li class='jc'>{@link oaj.http.header.Forwarded}
+ <li class='jc'>{@link oaj.http.header.From}
+ <li class='jc'>{@link oaj.http.header.Host}
+ <li class='jc'>{@link oaj.http.header.IfMatch}
+ <li class='jc'>{@link oaj.http.header.IfModifiedSince}
+ <li class='jc'>{@link oaj.http.header.IfNoneMatch}
+ <li class='jc'>{@link oaj.http.header.IfRange}
+ <li class='jc'>{@link oaj.http.header.IfUnmodifiedSince}
+ <li class='jc'>{@link oaj.http.header.MaxForwards}
+ <li class='jc'>{@link oaj.http.header.NoTrace}
+ <li class='jc'>{@link oaj.http.header.Origin}
+ <li class='jc'>{@link oaj.http.header.Pragma}
+ <li class='jc'>{@link oaj.http.header.ProxyAuthorization}
+ <li class='jc'>{@link oaj.http.header.Range}
+ <li class='jc'>{@link oaj.http.header.Referer}
+ <li class='jc'>{@link oaj.http.header.TE}
+ <li class='jc'>{@link oaj.http.header.Thrown}
+ <li class='jc'>{@link oaj.http.header.Upgrade}
+ <li class='jc'>{@link oaj.http.header.UserAgent}
+ <li class='jc'>{@link oaj.http.header.Warning}
+ </ul>
+ <li>Context values:
+ <ul class='javatreec'>
+ <li class='jc'>{@link oaj.BeanContext}
+ <li class='jc'>{@link oaj.config.Config}
+ <li class='jic'>{@link oajr.DebugEnablement}
+ <li class='jc'>{@link oaj.encoders.EncoderSet}
+ <li class='jic'>{@link oaj.cp.FileFinder}
+ <li class='jc'>{@link oaj.jsonschema.JsonSchemaGenerator}
+ <li class='jc'>{@link java.util.Logger}
+ <li class='jc'>{@link oaj.mstat.MethodExecStore}
+ <li class='jc'>{@link oaj.parser.ParserSet}
+ <li class='jc'>{@link oajr.RestChildren}
+ <li class='jc'>{@link oajr.RestContext}
+ <li class='jc'>{@link oajr.RestContextStats}
+ <li class='jic'>{@link oajr.logging.RestLogger}
+ <li class='jc'>{@link oajr.RestOpContext}
+ <li class='jc'>{@link oajr.RestOperations}
+ <li class='jc'>{@link oaj.serializer.SerializerSet}
+ <li class='jic'>{@link oajr.StaticFiles}
+ <li class='jc'>{@link oaj.mstat.ThrownStore}
+ </ul>
+ </ul>
+ <li><b>Annotated parameters (either on the parameter or parameter type):</b>
+ <ul class='javatreec'>
+ <li class='ja'>{@link oajr.annotation.Attr}
+ <li class='ja'>{@link oaj.http.annotation.Body}
+ <li class='ja'>{@link oaj.http.annotation.Path}
+ <li class='ja'>{@link oaj.http.annotation.FormData}
+ <li class='ja'>{@link oaj.http.annotation.HasFormData}
+ <li class='ja'>{@link oaj.http.annotation.Query}
+ <li class='ja'>{@link oaj.http.annotation.HasQuery}
+ <li class='ja'>{@link oaj.http.annotation.Header}
+ <li class='ja'>{@link oajr.annotation.Method}
+ <li class='ja'>{@link oaj.http.annotation.Request}
+ <li class='ja'>{@link oaj.http.annotation.Response}
+ <li class='ja'>{@link oaj.http.annotation.ResponseHeader}
+ <li class='ja'>{@link oaj.http.annotation.ResponseCode}
+ </ul>
+</ul>
+<p>
+ In Spring Boot environments, any available Spring Beans can also be passed in as parameters.
+</p>
+<h5 class='figure'>Example:</h5>
+<p class='bpcode w800'>
+ <ja>@RestGet</ja>(<js>"/example1/{a1}/{a2}/{a3}/*"</js>)
+ <jk>public</jk> String doGetExample1(
+ RestRequest <jv>req</jv>,
+ RestResponse <jv>res</jv>,
+ <ja>@Method</ja> String <jv>method</jv>,
+ <ja>@Path</ja>(<js>"a1"</js>) String <jv>a1</jv>,
+ <ja>@Path</ja>(<js>"a2"</js>) <jk>int</jk> <jv>a2</jv>,
+ <ja>@Path</ja>(<js>"a3"</js>) UUID <jv>a3</jv>,
+ <ja>@Query</ja>(<js>"p1"</js>) <jk>int</jk> <jv>p1</jv>,
+ <ja>@Query</ja>(<js>"p2"</js>) String <jv>p2</jv>,
+ <ja>@Query</ja>(<js>"p3"</js>) UUID <jv>p3</jv>,
+ <ja>@HasQuery</ja>(<js>"p3"</js>) boolean <jv>hasP3</jv>,
+ <ja>@Path</ja>(<js>"/*"</js>) String <jv>remainder</jv>,
+ <ja>@Header</ja>(<js>"Accept-Language"</js>) String <jv>lang</jv>,
+ <ja>@Header</ja>(<js>"Accept"</js>) String <jv>accept</jv>,
+ <ja>@Header</ja>(<js>"DNT"</js>) <jk>int</jk> <jv>doNotTrack</jv>,
+ RequestAttributes <jv>attributes</jv>,
+ ResourceBundle <jv>nls</jv>
+ ) {
+ <jc>// Do something with all of those</jc>
+ }
+</p>
+<p>
+ Additional parameter types can be defined by overriding {@link oajr.RestContext.Builder#createRestOpArgs(BeanStore,Supplier)} or
+ by adding them to the bean store using {@link oajr.RestContext.Builder#createBeanStore(Class,Supplier)}.
+</p>
+
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/03.JavaMethodReturnTypes.html b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/03.JavaMethodReturnTypes.html
new file mode 100644
index 0000000..71a2548
--- /dev/null
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/03.JavaMethodReturnTypes.html
@@ -0,0 +1,148 @@
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ ***************************************************************************************************************************/
+ -->
+
+{title:'Java Method Return Types', updated:'9.0.0'}
+
+<p>
+ The return type of the Java method can be any serializable POJO as defined in {@doc PojoCategories POJO Categories}.
+ It can also be <jk>void</jk> if the method is not sending any output (e.g. a request redirect) or is
+ setting the output using the {@link oajr.RestResponse#setOutput(Object)} method.
+</p>
+<h5 class='figure'>Example:</h5>
+<p class='bpcode w800'>
+ <ja>@RestGet</ja>
+ <jk>public</jk> String doGet() {
+ <jk>return</jk> <js>"Hello World!"</js>;
+ }
+</p>
+<p>
+ In addition to POJOs, the following return types are also supported:
+</p>
+<ul class='spaced-list'>
+ <li>
+ <b>Parameters based on class types:</b>
+ <ul class='spaced-list'>
+ <li>Direct streams:
+ <ul class='javatreec'>
+ <li class='jc'>{@link java.io.InputStream}
+ <li class='jc'>{@link java.io.Reader}
+ </ul>
+ <li>Apache HttpComponent beans:
+ <ul class='javatreec'>
+ <li class='jic'>{@link org.apache.http.HttpEntity}
+ <li class='jic'>{@link oaj.http.resource.HttpResource}
+ <li class='jic'>{@link org.apache.http.HttpResponse}
+ </ul>
+ <li>Standard HTTP response beans:
+ <ul class='javatreec'>
+ <li class='jc'>{@link oaj.http.response.Accepted}
+ <li class='jc'>{@link oaj.http.response.AlreadyReported}
+ <li class='jc'>{@link oaj.http.response.BadRequest}
+ <li class='jc'>{@link oaj.http.response.Conflict}
+ <li class='jc'>{@link oaj.http.response.Continue}
+ <li class='jc'>{@link oaj.http.response.Created}
+ <li class='jc'>{@link oaj.http.response.EarlyHints}
+ <li class='jc'>{@link oaj.http.response.ExpectationFailed}
+ <li class='jc'>{@link oaj.http.response.FailedDependency}
+ <li class='jc'>{@link oaj.http.response.Forbidden}
+ <li class='jc'>{@link oaj.http.response.Found}
+ <li class='jc'>{@link oaj.http.response.Gone}
+ <li class='jc'>{@link oaj.http.response.HttpVersionNotSupported}
+ <li class='jc'>{@link oaj.http.response.IMUsed}
+ <li class='jc'>{@link oaj.http.response.InsufficientStorage}
+ <li class='jc'>{@link oaj.http.response.InternalServerError}
+ <li class='jc'>{@link oaj.http.response.LengthRequired}
+ <li class='jc'>{@link oaj.http.response.Locked}
+ <li class='jc'>{@link oaj.http.response.LoopDetected}
+ <li class='jc'>{@link oaj.http.response.MethodNotAllowed}
+ <li class='jc'>{@link oaj.http.response.MisdirectedRequest}
+ <li class='jc'>{@link oaj.http.response.MovedPermanently}
+ <li class='jc'>{@link oaj.http.response.MultipleChoices}
+ <li class='jc'>{@link oaj.http.response.MultiStatus}
+ <li class='jc'>{@link oaj.http.response.NetworkAuthenticationRequired}
+ <li class='jc'>{@link oaj.http.response.NoContent}
+ <li class='jc'>{@link oaj.http.response.NonAuthoritiveInformation}
+ <li class='jc'>{@link oaj.http.response.NotAcceptable}
+ <li class='jc'>{@link oaj.http.response.NotExtended}
+ <li class='jc'>{@link oaj.http.response.NotFound}
+ <li class='jc'>{@link oaj.http.response.NotImplemented}
+ <li class='jc'>{@link oaj.http.response.NotModified}
+ <li class='jc'>{@link oaj.http.response.Ok}
+ <li class='jc'>{@link oaj.http.response.PartialContent}
+ <li class='jc'>{@link oaj.http.response.PayloadTooLarge}
+ <li class='jc'>{@link oaj.http.response.PermanentRedirect}
+ <li class='jc'>{@link oaj.http.response.PreconditionFailed}
+ <li class='jc'>{@link oaj.http.response.PreconditionRequired}
+ <li class='jc'>{@link oaj.http.response.Processing}
+ <li class='jc'>{@link oaj.http.response.RangeNotSatisfiable}
+ <li class='jc'>{@link oaj.http.response.RequestHeaderFieldsTooLarge}
+ <li class='jc'>{@link oaj.http.response.ResetContent}
+ <li class='jc'>{@link oaj.http.response.SeeOther}
+ <li class='jc'>{@link oaj.http.response.ServiceUnavailable}
+ <li class='jc'>{@link oaj.http.response.SwitchingProtocols}
+ <li class='jc'>{@link oaj.http.response.TemporaryRedirect}
+ <li class='jc'>{@link oaj.http.response.TooManyRequests}
+ <li class='jc'>{@link oaj.http.response.Unauthorized}
+ <li class='jc'>{@link oaj.http.response.UnavailableForLegalReasons}
+ <li class='jc'>{@link oaj.http.response.UnprocessableEntity}
+ <li class='jc'>{@link oaj.http.response.UnsupportedMediaType}
+ <li class='jc'>{@link oaj.http.response.UpgradeRequired}
+ <li class='jc'>{@link oaj.http.response.UriTooLong}
+ <li class='jc'>{@link oaj.http.response.UseProxy}
+ <li class='jc'>{@link oaj.http.response.VariantAlsoNegotiates}
+ </ul>
+ <li>Other:
+ <ul class='javatreec'>
+ <li class='jc'>{@link oajr.beans.ChildResourceDescriptions}
+ <li class='jc'>{@link oajr.beans.ResourceDescriptions}
+ <li class='jc'>{@link oajr.beans.SeeOtherRoot}
+ <li class='jc'>{@link java.lang.Throwable}
+ </ul>
+ </ul>
+ <li><b>Annotated parameters (either on the parameter or parameter type):</b>
+ <ul class='javatreec'>
+ <li class='ja'>{@link oaj.http.annotation.Response}
+ </ul>
+</ul>
+<p>
+ REST Java methods can also generate a response via the following:
+</p>
+<ul class='spaced-list'>
+ <li>
+ By calling {@link oajr.RestResponse#setOutput(Object)} with any of the types above.
+ <li>
+ By accessing the {@link java.io.Writer} directly by calling
+ {@link oajr.RestResponse#getNegotiatedWriter()} and writing the output yourself.
+</ul>
+<h5 class='figure'>Example:</h5>
+<p class='bpcode w800'>
+ <jc>// Equivalent method 1</jc>
+ <ja>@RestGet</ja>(<js>"/example1/{personId}"</js>)
+ <jk>public</jk> Person doGet1(<ja>@Path</ja>(<js>"personId"</js>) UUID <jv>personId</jv>) {
+ Person <jv>person</jv> = <jsm>getPersonById</jsm>(<jv>personId</jv>);
+ <jk>return</jk> <jv>person</jv>;
+ }
+
+ <jc>// Equivalent method 2</jc>
+ <ja>@RestGet</ja>(<js>"/example2/{personId}"</js>)
+ <jk>public void</jk> doGet2(RestResponse <jv>res</jv>, <ja>@Path</ja>(<js>"personId"</js>) UUID personId) {
+ Person <jv>person</jv> = <jsm>getPersonById</jsm>(<jv>personId</jv>);
+ <jv>res</jv>.setOutput(<jv>person</jv>);
+ }
+</p>
+<p>
+ Additional parameter types can be defined by overriding {@link oajr.RestContext.Builder#createResponseProcessors(BeanStore,Supplier)}.
+</p>
+
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/04.JavaMethodThrowableTypes.html b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/04.JavaMethodThrowableTypes.html
new file mode 100644
index 0000000..83fb9a7
--- /dev/null
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/04.JavaMethodThrowableTypes.html
@@ -0,0 +1,96 @@
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ ***************************************************************************************************************************/
+ -->
+
+{title:'Java Method Throwable Types', updated:'9.0.0'}
+
+<p>
+ Annotated Java methods can throw any of the following:
+</p>
+<ul class='spaced-list'>
+ <li>Standard HTTP response beans:
+ <ul class='javatreec'>
+ <li class='jc'>{@link oaj.http.response.BadRequest}
+ <li class='jc'>{@link oaj.http.response.Conflict}
+ <li class='jc'>{@link oaj.http.response.ExpectationFailed}
+ <li class='jc'>{@link oaj.http.response.FailedDependency}
+ <li class='jc'>{@link oaj.http.response.Forbidden}
+ <li class='jc'>{@link oaj.http.response.Gone}
+ <li class='jc'>{@link oaj.http.response.HttpVersionNotSupported}
+ <li class='jc'>{@link oaj.http.response.InsufficientStorage}
+ <li class='jc'>{@link oaj.http.response.InternalServerError}
+ <li class='jc'>{@link oaj.http.response.LengthRequired}
+ <li class='jc'>{@link oaj.http.response.Locked}
+ <li class='jc'>{@link oaj.http.response.LoopDetected}
+ <li class='jc'>{@link oaj.http.response.MethodNotAllowed}
+ <li class='jc'>{@link oaj.http.response.MisdirectedRequest}
+ <li class='jc'>{@link oaj.http.response.NetworkAuthenticationRequired}
+ <li class='jc'>{@link oaj.http.response.NotAcceptable}
+ <li class='jc'>{@link oaj.http.response.NotExtended}
+ <li class='jc'>{@link oaj.http.response.NotFound}
+ <li class='jc'>{@link oaj.http.response.NotImplemented}
+ <li class='jc'>{@link oaj.http.response.PayloadTooLarge}
+ <li class='jc'>{@link oaj.http.response.PreconditionFailed}
+ <li class='jc'>{@link oaj.http.response.PreconditionRequired}
+ <li class='jc'>{@link oaj.http.response.RangeNotSatisfiable}
+ <li class='jc'>{@link oaj.http.response.RequestHeaderFieldsTooLarge}
+ <li class='jc'>{@link oaj.http.response.ServiceUnavailable}
+ <li class='jc'>{@link oaj.http.response.TooManyRequests}
+ <li class='jc'>{@link oaj.http.response.Unauthorized}
+ <li class='jc'>{@link oaj.http.response.UnavailableForLegalReasons}
+ <li class='jc'>{@link oaj.http.response.UnprocessableEntity}
+ <li class='jc'>{@link oaj.http.response.UnsupportedMediaType}
+ <li class='jc'>{@link oaj.http.response.UpgradeRequired}
+ <li class='jc'>{@link oaj.http.response.UriTooLong}
+ <li class='jc'>{@link oaj.http.response.VariantAlsoNegotiates}
+ </ul>
+ <li>Annotated throwables:
+ <ul class='javatreec'>
+ <li class='ja'>{@link oaj.http.annotation.Response}
+ </ul>
+</ul>
+<p>
+ All other throwables get processed as follows:
+</p>
+<ul class='spaced-list'>
+ <li>Processed as 400/Bad Request:
+ <ul class='javatreec'>
+ <li class='jc'>{@link oaj.parser.ParseException}
+ <li class='jc'>{@link oaj.InvalidDataConversionException}
+ </ul>
+ <li>Processed as 401/Unauthorized:
+ <ul>
+ <li>Any class named <js>"*AccessDenied*"</js> or <js>"*Unauthorized*"</js>
+ </ul>
+ <li>Processed as 404/Not Found:
+ <ul>
+ <li>Any class named <js>"*Empty*"</js> or <js>"*NotFound*"</js>
+ </ul>
+ <li>Anything else processed as 500/Internal Server Error.
+</ul>
+
+<h5 class='figure'>Example:</h5>
+<p class='bpcode w800'>
+ <ja>@RestGet</ja>(<js>"/user/login"</js>)
+ <jk>public</jk> Ok login(
+ <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
+ <ja>@FormData</ja>(<js>"password"</js>) String <jv>password</jv>
+ ) <jk>throws</jk> Unauthorized
+ {
+ <jk>if</jk> (! <jsm>isOK</jsm>(<jv>username</jv>, <jv>password</jv>))
+ <jk>throw new</jk> Unauthorized(<js>"You're not welcome!"</js>);
+
+ <jk>return</jk> Ok.<jsf>OK</jsf>;
+ }
+</p>
\ No newline at end of file
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/05.PathPatterns.html b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/05.PathPatterns.html
new file mode 100644
index 0000000..fc12322
--- /dev/null
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/05.PathPatterns.html
@@ -0,0 +1,104 @@
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ ***************************************************************************************************************************/
+ -->
+
+{title:'Path Patterns', updated:'9.0.0'}
+
+<p>
+ The {@link oajr.annotation.RestOp#path() @RestOp(path)} annotation allows
+ you to define URL path patterns to match against.
+ These patterns can contain variables of the form <l>"{xxx}"</l> that can be passed in directly to the
+ Java methods as extra parameters.
+</p>
+<p>
+ In the following example, 3 separate GET request handlers are defined with different path patterns.
+ Note how the variables are passed in as additional arguments on the method, and how those arguments are
+ automatically converted to the specified class type...
+</p>
+<p class='bpcode w800'>
+ <jc>// Default method</jc>
+ <ja>@RestGet</ja>(path=<js>"/*"</js>)
+ <jk>public void</jk> doGetDefault() {
+ ...
+ }
+
+ <jc>// Method with path pattern</jc>
+ <ja>@RestGet</ja>(path=<js>"/xxx"</js>)
+ <jk>public void</jk> doGetNoArgs(...) {
+ ...
+ }
+
+ <jc>// Method with path pattern with arguments</jc>
+ <ja>@RestGet</ja>(path=<js>"/xxx/{foo}/{bar}/{baz}/{bing}"</js>)
+ <jk>public void</jk> doGetWithArgs(
+ <ja>@Path</ja>(<js>"foo"</js>) String <jv>foo</jv>,
+ <ja>@Path</ja>(<js>"bar"</js>) <jk>int</jk> <jv>bar</jv>,
+ <ja>@Path</ja>(<js>"baz"</js>) MyEnum <jv>baz</jv>,
+ <ja>@Path</ja>(<js>"bing"</js>) UUID <jv>qux</jv>
+ ) {
+ ...
+ }
+</p>
+<p>
+ By default, path patterns are matched using a best-match heuristic.
+ When overlaps occur, URLs are matched from most-specific to most-general order:
+</p>
+<p class='bpcode w800'>
+ <jc>// Try first </jc>
+ <ja>@RestGet</ja>(<js>"/foo/bar"</js>)
+ <jk>public void</jk> method1() {
+ ...
+ }
+
+ <jc>// Try second</jc>
+ <ja>@RestGet</ja>(<js>"/foo/{bar}"</js>)
+ <jk>public void</jk> method2(...) {
+ ...
+ }
+
+ <jc>// Try third</jc>
+ <ja>@RestGet</ja>(<js>"/foo/*"</js>)
+ <jk>public void</jk> method3(...) {
+ ...
+ }
+
+ <jc>// Try last</jc>
+ <ja>@RestGet</ja>(<js>"/*"</js>)
+ <jk>public void</jk> method4(...) {
+ ...
+ }
+</p>
+<p>
+ Paths that end with <js>"/*"</js> will do a prefix match on the incoming URL.
+ Any remainder after the match can be accessed through
+ {@link oajr.RequestPathParams#getRemainder()} or parameters with the
+ <c><ja>@Path</ja>(<js>"/*"</js>)</c> annotation.
+ On the other hand, paths that don't end with <js>"/*"</js> (e.g. <js>"/"</js> or <js>"/foo"</js>) will
+ require an exact URL match, and if any remainder exists, a 404 (not found) error will be thrown.
+</p>
+<p>
+ The following example shows the distinction.
+</p>
+<p class='bpcode w800'>
+ <ja>@RestGet</ja>(<js>"/*"</js>)
+ <jk>public void</jk> doGet(<ja>@Path</ja>(<js>"/*"</js>) String <jv>remainder</jv>) {
+ <jc>// URL path pattern can have remainder accessible through req.getRemainder().</jc>
+ }
+
+ <ja>@RestPut</ja>(<js>"/"</js>)
+ <jk>public void</jk> doPut() {
+ <jc>// URL path pattern must match exactly and will cause a 404 error if a remainder exists.</jc>
+ }
+</p>
+
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/06.Matchers.html b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/06.Matchers.html
new file mode 100644
index 0000000..8f2ef12
--- /dev/null
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/06.Matchers.html
@@ -0,0 +1,70 @@
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ ***************************************************************************************************************************/
+ -->
+
+{title:'Matchers', updated:'9.0.0'}
+
+<p>
+ {@link oajr.RestMatcher RestMatchers} are used to allow multiple Java methods to be
+ tied to the same HTTP method and path, but differentiated by some request attribute such as a specific
+ header value.
+</p>
+<h5 class='figure'>Example:</h5>
+<p class='bpcode w800'>
+ <jc>// GET method that gets invoked for administrators</jc>
+ <ja>@RestGet</ja>(path=<js>"/*"</js>, matchers=IsAdminMatcher.<jk>class</jk>)
+ <jk>public</jk> Object doGetForAdmin() {
+ ...
+ }
+
+ <jc>// GET method that gets invoked for everyone else</jc>
+ <ja>@RestGet</ja>(<js>"/*"</js>)
+ <jk>public</jk> Object doGetForEveryoneElse() {
+ ...
+ }
+</p>
+<p>
+ The interface for matchers is simple:
+</p>
+<p class='bpcode w800'>
+ <jk>public class</jk> IsAdminMatcher <jk>extends</jk> RestMatcher {
+
+ <ja>@Override</ja> <jc>/* RestMatcher */</jc>
+ <jk>public boolean</jk> matches(RestRequest <jv>req</jv>) {
+ <jk>return</jk> <jv>req</jv>.isUserInRole(<js>"ADMINS_GROUP"</js>);
+ }
+ }
+</p>
+
+<ul class='notes'>
+ <li class='note'>
+ If no methods are found with a matching matcher, a <l>412 Precondition Failed</l> status is returned.
+ <li class='note'>
+ If multiple matchers are specified on the same method, ONLY ONE matcher needs to match for the
+ method to be invoked.
+ <li class='note'>
+ Note that you CANNOT define identical paths on different methods UNLESS you use matchers.
+ <br>That includes paths that are only different in variable names (e.g. <l>"/foo/{bar}"</l> and
+ <l>"/foo/{baz}"</l>).
+ <br>If you try to do so, a <l>ServletException</l> will be thrown on startup.
+ <li class='note'>
+ Methods with matchers take precedence over methods without.
+ <br>Otherwise, methods are attempted in the order they appear in the class.
+</ul>
+
+<ul class='seealso'>
+ <li class='ja'>{@link oajr.annotation.RestOp#matchers RestOp(matchers)}
+ <li class='jc'>{@link oajr.matchers.MultipartFormDataMatcher}
+ <li class='jc'>{@link oajr.matchers.UrlEncodedFormMatcher}
+</ul>
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/07.RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams.html b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/07.AdditionalInformation.html
similarity index 67%
copy from juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/07.RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams.html
copy to juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/07.AdditionalInformation.html
index 75a7f96..03c08b1 100644
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/07.RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams.html
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/03.RestOpAnnotatedMethods/07.AdditionalInformation.html
@@ -13,8 +13,18 @@
***************************************************************************************************************************/
-->
-{title:'RequestHeaders / RequestQueryParams / RequestFormParams / RequestPathParams', created:'9.0.0'}
+{title:'Additional Information', updated:'9.0.0'}
<p>
- TODO
-</p>
\ No newline at end of file
+ Refer to the following Javadocs for more information:
+</p>
+<ul class='javatreec w900'>
+ <li class='jc'>{@link oajr.RestRequest}
+ <li class='jc'>{@link oajr.RestResponse}
+ <li class='jc'>{@link oajr.RequestBody}
+ <li class='jc'>{@link oajr.RequestHeaders}
+ <li class='jc'>{@link oajr.RequestQueryParams}
+ <li class='jc'>{@link oajr.RequestFormParams}
+ <li class='jc'>{@link oajr.RequestPathParams}
+ <li class='jc'>{@link oajr.RequestAttributes}
+</ul>
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts.html b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts.html
index 06541e8..042d6b6 100644
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts.html
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts.html
@@ -25,7 +25,7 @@
<jk>public</jk> String doGetExample1(
<ja>@Path</ja>(<js>"a1"</js>) String <jv>a1</jv>,
<ja>@Query</ja>(<js>"p1"</js>) <jk>int</jk> <jv>p1</jv>,
- <ja>@HasQuery</ja>(<js>"p2"</js>) boolean <jv>hasP3</jv>,
+ <ja>@HasQuery</ja>(<js>"p2"</js>) <jk>boolean</jk> <jv>hasP3</jv>,
<ja>@Path</ja>(<js>"/*"</js>) String <jv>remainder</jv>,
<ja>@Header</ja>(<js>"Accept-Language"</js>) String <jv>lang</jv>
) {
@@ -72,13 +72,3 @@
taking precedence. When defined on both, annotations are aggregated with values on parameters
taking precedence.
</ul>
-<p>
- Request HTTP parts can also be retrieved programmatically through the following classes that
- can be passed in as parameters or access through {@link oajr.RestRequest} bean:
-</p>
-<ul class='javatreec'>
- <li class='jc'>{@link oajr.RequestHeaders}
- <li class='jc'>{@link oajr.RequestQueryParams}
- <li class='jc'>{@link oajr.RequestFormParams}
- <li class='jc'>{@link oajr.RequestPathParams}
-</ul>
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/01.PartSerializers_PartParsers.html b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/01.PartMarshallers.html
similarity index 96%
rename from juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/01.PartSerializers_PartParsers.html
rename to juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/01.PartMarshallers.html
index 6a59151..7d35826 100644
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/01.PartSerializers_PartParsers.html
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/01.PartMarshallers.html
@@ -13,10 +13,10 @@
***************************************************************************************************************************/
-->
-{title:'Part Serializers / Part Parsers', updated:'8.1.0,9.0.0'}
+{title:'Part Marshallers', updated:'8.1.0,9.0.0'}
<p>
- Juneau comes with three basic marshall types for serializing and parsing HTTP parts:
+ Juneau comes with three basic marshall types for serializing and parsing Header, Query, Form, and Path parts:
</p>
<ul class='javatree'>
<li class='jic'>{@link oaj.httppart.HttpPartSerializer}
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/02.Header_Path_Query_FormData.html b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/02.Header_Path_Query_FormData.html
deleted file mode 100644
index 31749b5..0000000
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/02.Header_Path_Query_FormData.html
+++ /dev/null
@@ -1,227 +0,0 @@
-<!--
-/***************************************************************************************************************************
- * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
- * with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- ***************************************************************************************************************************/
- -->
-
-{title:'@Header / @Path / @Query / @FormData', updated:'8.1.0,9.0.0'}
-
-<p>
- The {@link oaj.http.annotation.Header @Header} / {@link oaj.http.annotation.Path @Path} / {@link oaj.http.annotation.Query @Query} / {@link oaj.http.annotation.FormData @FormData}
- annotations allow for defining part schemas based on the OpenAPI standard.
-</p>
-<ul class='javatree'>
- <li class='ja'>{@link oaj.http.annotation.Header}
- <ul class='javatreec'>
- <li class='jm'>{@link oaj.http.annotation.Header#name() name()}
- <li class='jm'>{@link oaj.http.annotation.Header#parser() parser()}
- <li class='jm'>{@link oaj.http.annotation.Header#schema() schema()}
- <li class='jm'>{@link oaj.http.annotation.Header#serializer() serializer()}
- <li class='jm'>{@link oaj.http.annotation.Header#value() value()}
- </ul>
- <li class='ja'>{@link oaj.http.annotation.Query}
- <ul class='javatreec'>
- <li class='jm'>{@link oaj.http.annotation.Query#name() name()}
- <li class='jm'>{@link oaj.http.annotation.Query#parser() parser()}
- <li class='jm'>{@link oaj.http.annotation.Query#schema() schema()}
- <li class='jm'>{@link oaj.http.annotation.Query#serializer() serializer()}
- <li class='jm'>{@link oaj.http.annotation.Query#value() value()}
- </ul>
- <li class='ja'>{@link oaj.http.annotation.FormData}
- <ul class='javatreec'>
- <li class='jm'>{@link oaj.http.annotation.FormData#name() name()}
- <li class='jm'>{@link oaj.http.annotation.FormData#parser() parser()}
- <li class='jm'>{@link oaj.http.annotation.FormData#schema() schema()}
- <li class='jm'>{@link oaj.http.annotation.FormData#serializer() serializer()}
- <li class='jm'>{@link oaj.http.annotation.FormData#value() value()}
- </ul>
- <li class='ja'>{@link oaj.http.annotation.Path}
- <ul class='javatreec'>
- <li class='jm'>{@link oaj.http.annotation.Path#name() name()}
- <li class='jm'>{@link oaj.http.annotation.Path#parser() parser()}
- <li class='jm'>{@link oaj.http.annotation.Path#schema() schema()}
- <li class='jm'>{@link oaj.http.annotation.Path#serializer() serializer()}
- <li class='jm'>{@link oaj.http.annotation.Path#value() value()}
- </ul>
-</ul>
-<p>
- The {@link oaj.http.annotation.Header @Header} annotation is used to retrieve parsed request headers.
- The {@link oaj.http.annotation.Query @Query} annotation is used to retrieve request URL query parameters.
- The {@link oaj.http.annotation.FormData @FormData} annotation is used to retrieve request form post parameters.
- And the {@link oaj.http.annotation.Path @Path} annotation is used to retrieve parsed URL path variables and
- remainders.
-</p>
-<p>
- The most typical scenario is to simply use the <c>value</c> field to define parameter names:
-</p>
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>
- <jk>public void</jk> doGet(
- <ja>@Query</ja>(<js>"p1"</js>) <jk>int</jk> <jv>p1</jv>,
- <ja>@Query</ja>(<js>"p2"</js>) String <jv>p2</jv>,
- <ja>@Query</ja>(<js>"p3"</js>) UUID <jv>p3</jv>) {...}
-</p>
-<p>
- This is functionally equivalent to the following code:
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>
- <jk>public void</jk> doGet(RestRequest <jv>req</jv>) {
- RequestQueryParams <jv>query</jv> = <jv>req</jv>.getQueryParams();
- <jk>int</jk> <jv>p1</jv> = <jv>query</jv>.get(<js>"p1"</js>).asInteger().orElse(0);
- String <jv>p2</jv> = <jv>query</jv>.get(<js>"p2"</js>).orElse(<jk>null</jk>);
- UUID <jv>p3</jv> = <jv>query</jv>.get(<js>"p3"</js>).as(UUID.<jk>class</jk>).orElse(<jk>null</jk>);
- }
-</p>
-<p>
- The special name <js>"*"</js> (or blank) can be used to represent all values.
- When used, the data type must be a <c>Map</c> or bean.
-</p>
-<h5 class='figure'>Examples:</h5>
-<p class='bpcode w800'>
- <jc>// Multiple values passed as a map.</jc>
- <ja>@RestGet</ja>
- <jk>public void</jk> doGet(<ja>@Query</ja>(<js>"*"</js>) Map<String,Object> <jv>map</jv>) {...}
-</p>
-<p class='bpcode w800'>
- <jc>// Same, but name "*" is inferred.</jc>
- <ja>@RestGet</ja>
- <jk>public void</jk> doGet(<ja>@Query</ja> Map<String,Object> <jv>map</jv>) {...}
-</p>
-<p class='bpcode w800'>
- <jc>// Multiple values passed as a bean.</jc>
- <ja>@RestGet</ja>
- <jk>public void</jk> doGet(<ja>@Query</ja> MyQueryBean <jv>bean</jv>) {...}
-</p>
-
-<p>
- The default registered part parser {@link oaj.oapi.OpenApiParser} is used to convert strings
- to POJOs using schemas defined via the {@link oaj.http.annotation.Schema} annotation.
-</p>
-<ul class='javatree'>
- <li class='ja'>{@link oaj.http.annotation.Schema}
- <ul class='javatreec'>
- <li class='jm'>{@link oaj.http.annotation.Schema#_default() _default()}
- <li class='jm'>{@link oaj.http.annotation.Schema#_enum() _enum()}
- <li class='jm'>{@link oaj.http.annotation.Schema#$ref() $ref()}
- <li class='jm'>{@link oaj.http.annotation.Schema#additionalProperties() additionalProperties()}
- <li class='jm'>{@link oaj.http.annotation.Schema#aev() aev()}
- <li class='jm'>{@link oaj.http.annotation.Schema#allOf() allOf()}
- <li class='jm'>{@link oaj.http.annotation.Schema#allowEmptyValue() allowEmptyValue()}
- <li class='jm'>{@link oaj.http.annotation.Schema#cf() cf()}
- <li class='jm'>{@link oaj.http.annotation.Schema#collectionFormat() collectionFormat()}
- <li class='jm'>{@link oaj.http.annotation.Schema#d() d()}
- <li class='jm'>{@link oaj.http.annotation.Schema#description() description()}
- <li class='jm'>{@link oaj.http.annotation.Schema#df() df()}
- <li class='jm'>{@link oaj.http.annotation.Schema#discriminator() discriminator()}
- <li class='jm'>{@link oaj.http.annotation.Schema#e() e()}
- <li class='jm'>{@link oaj.http.annotation.Schema#emax() emax()}
- <li class='jm'>{@link oaj.http.annotation.Schema#emin() emin()}
- <li class='jm'>{@link oaj.http.annotation.Schema#exclusiveMaximum() exclusiveMaximum()}
- <li class='jm'>{@link oaj.http.annotation.Schema#exclusiveMinimum() exclusiveMinimum()}
- <li class='jm'>{@link oaj.http.annotation.Schema#externalDocs() externalDocs()}
- <li class='jm'>{@link oaj.http.annotation.Schema#f() f()}
- <li class='jm'>{@link oaj.http.annotation.Schema#format() format()}
- <li class='jm'>{@link oaj.http.annotation.Schema#ignore() ignore()}
- <li class='jm'>{@link oaj.http.annotation.Schema#items() items()}
- <li class='jm'>{@link oaj.http.annotation.Schema#max() max()}
- <li class='jm'>{@link oaj.http.annotation.Schema#maxi() maxi()}
- <li class='jm'>{@link oaj.http.annotation.Schema#maximum() maximum()}
- <li class='jm'>{@link oaj.http.annotation.Schema#maxItems() maxItems()}
- <li class='jm'>{@link oaj.http.annotation.Schema#maxl() maxl()}
- <li class='jm'>{@link oaj.http.annotation.Schema#maxLength() maxLength()}
- <li class='jm'>{@link oaj.http.annotation.Schema#maxp() maxp()}
- <li class='jm'>{@link oaj.http.annotation.Schema#maxProperties() maxProperties()}
- <li class='jm'>{@link oaj.http.annotation.Schema#min() min()}
- <li class='jm'>{@link oaj.http.annotation.Schema#mini() mini()}
- <li class='jm'>{@link oaj.http.annotation.Schema#minimum() minimum()}
- <li class='jm'>{@link oaj.http.annotation.Schema#minItems() minItems()}
- <li class='jm'>{@link oaj.http.annotation.Schema#minl() minl()}
- <li class='jm'>{@link oaj.http.annotation.Schema#minLength() minLength()}
- <li class='jm'>{@link oaj.http.annotation.Schema#minp() minp()}
- <li class='jm'>{@link oaj.http.annotation.Schema#minProperties() minProperties()}
- <li class='jm'>{@link oaj.http.annotation.Schema#mo() mo()}
- <li class='jm'>{@link oaj.http.annotation.Schema#multipleOf() multipleOf()}
- <li class='jm'>{@link oaj.http.annotation.Schema#on() on()}
- <li class='jm'>{@link oaj.http.annotation.Schema#onClass() onClass()}
- <li class='jm'>{@link oaj.http.annotation.Schema#p() p()}
- <li class='jm'>{@link oaj.http.annotation.Schema#pattern() pattern()}
- <li class='jm'>{@link oaj.http.annotation.Schema#properties() properties()}
- <li class='jm'>{@link oaj.http.annotation.Schema#r() r()}
- <li class='jm'>{@link oaj.http.annotation.Schema#readOnly() readOnly()}
- <li class='jm'>{@link oaj.http.annotation.Schema#required() required()}
- <li class='jm'>{@link oaj.http.annotation.Schema#ro() ro()}
- <li class='jm'>{@link oaj.http.annotation.Schema#sie() sie()}
- <li class='jm'>{@link oaj.http.annotation.Schema#skipIfEmpty() v()}
- <li class='jm'>{@link oaj.http.annotation.Schema#t() t()}
- <li class='jm'>{@link oaj.http.annotation.Schema#title() title()}
- <li class='jm'>{@link oaj.http.annotation.Schema#type() type()}
- <li class='jm'>{@link oaj.http.annotation.Schema#ui() ui()}
- <li class='jm'>{@link oaj.http.annotation.Schema#uniqueItems() uniqueItems()}
- <li class='jm'>{@link oaj.http.annotation.Schema#xml() xml()}
- </ul>
-</ul>
-<p>
- For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. <js>"1,2,3|4,5,6|7,8,9"</js>) can be converted to a 2-dimensional array of <c>Longs</c>:
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/testQuery"</js>)
- <jk>public void</jk> testQuery(
- <ja>@Query</ja>(<js>"queryParamName"</js>)
- <ja>@Schema</ja>(
- collectionFormat=<js>"pipes"</js>,
- items=<ja>@SubItems</ja>(
- collectionFormat=<js>"csv"</js>,
- type=<js>"integer"</js>,
- format=<js>"int64"</js>,
- minimum=<js>"0"</js>,
- maximum=<js>"100"</js>
- minLength=1,
- maxLength=10
- ),
- minLength=1,
- maxLength=10
- )
- Long[][] <jv>queryParameter</jv>
- ) {...}
-</p>
-<p>
- Input will be converted based on the types and formats defined in the schema definition.
- Input validations such as <c>minLength/maxLength</c> that don't match the input will result in automatic <c>400 Bad Request</c> responses.
-</p>
-
-<p>
- The request part annotations are also used for supplying swagger information about the HTTP part.
- This information is used to populate the auto-generated Swagger documentation and UI.
-</p>
-<h5 class='figure'>Examples:</h5>
-<p class='bpcode w800'>
- <jc>// Normal</jc>
- <ja>@Query</ja>(<js>"name"</js>)
- <ja>@Schema</ja>(
- description=<js>"Pet name"</js>,
- required=<jk>true</jk>,
- example=<js>"Doggie"</js>
- )
-</p>
-<p>
- {@doc RestSvlVariables SVL Variables} (e.g. "$L{my.localized.variable}") are supported on annotation fields as well.
- Among other things, this allow for annotation values to be defined externally and the ability to produce localized swagger documents
- based on the <c>Accept-Language</c> on a request.
-</p>
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <ja>@Schema</ja>(
- description=<js>"$L{PetNameDescription}"</js>
- )
-</p>
\ No newline at end of file
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
new file mode 100644
index 0000000..f42e217
--- /dev/null
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/02.HttpPartAnnotations.html
@@ -0,0 +1,461 @@
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ ***************************************************************************************************************************/
+ -->
+
+{title:'HTTP Part Annotations', updated:'8.1.0,9.0.0'}
+
+<p>
+ The following annotations allow for defining part schemas based on the OpenAPI standard.
+</p>
+<ul class='spaced-list'>
+ <li><b>Request annotations:</b>
+ <ul class='javatree'>
+ <li class='ja'>{@link oaj.http.annotation.Request}
+ <ul class='javatreec'>
+ <li class='jm'>{@link oaj.http.annotation.Request#on() on()}
+ <li class='jm'>{@link oaj.http.annotation.Request#onClass() onClass()}
+ <li class='jm'>{@link oaj.http.annotation.Request#parser() parser()}
+ <li class='jm'>{@link oaj.http.annotation.Request#serializer() serializer()}
+ </ul>
+ <li class='ja'>{@link oaj.http.annotation.Header}
+ <ul class='javatreec'>
+ <li class='jm'>{@link oaj.http.annotation.Header#name() name()}
+ <li class='jm'>{@link oaj.http.annotation.Header#parser() parser()}
+ <li class='jm'>{@link oaj.http.annotation.Header#schema() schema()}
+ <li class='jm'>{@link oaj.http.annotation.Header#serializer() serializer()}
+ <li class='jm'>{@link oaj.http.annotation.Header#value() value()}
+ </ul>
+ <li class='ja'>{@link oaj.http.annotation.Query}
+ <ul class='javatreec'>
+ <li class='jm'>{@link oaj.http.annotation.Query#name() name()}
+ <li class='jm'>{@link oaj.http.annotation.Query#parser() parser()}
+ <li class='jm'>{@link oaj.http.annotation.Query#schema() schema()}
+ <li class='jm'>{@link oaj.http.annotation.Query#serializer() serializer()}
+ <li class='jm'>{@link oaj.http.annotation.Query#value() value()}
+ </ul>
+ <li class='ja'>{@link oaj.http.annotation.FormData}
+ <ul class='javatreec'>
+ <li class='jm'>{@link oaj.http.annotation.FormData#name() name()}
+ <li class='jm'>{@link oaj.http.annotation.FormData#parser() parser()}
+ <li class='jm'>{@link oaj.http.annotation.FormData#schema() schema()}
+ <li class='jm'>{@link oaj.http.annotation.FormData#serializer() serializer()}
+ <li class='jm'>{@link oaj.http.annotation.FormData#value() value()}
+ </ul>
+ <li class='ja'>{@link oaj.http.annotation.Path}
+ <ul class='javatreec'>
+ <li class='jm'>{@link oaj.http.annotation.Path#name() name()}
+ <li class='jm'>{@link oaj.http.annotation.Path#parser() parser()}
+ <li class='jm'>{@link oaj.http.annotation.Path#schema() schema()}
+ <li class='jm'>{@link oaj.http.annotation.Path#serializer() serializer()}
+ <li class='jm'>{@link oaj.http.annotation.Path#value() value()}
+ </ul>
+ <li class='ja'>{@link oaj.http.annotation.Body}
+ <ul class='javatreec'>
+ <li class='jm'>{@link oaj.http.annotation.Body#on() on()}
+ <li class='jm'>{@link oaj.http.annotation.Body#onClass() onClass()}
+ <li class='jm'>{@link oaj.http.annotation.Body#schema() schema()}
+ </ul>
+ </ul>
+ <li><b>Response annotations:</b>
+ <ul class='javatree'>
+ <li class='ja'>{@link oaj.http.annotation.Response}
+ <ul class='javatreec'>
+ <li class='jm'>{@link oaj.http.annotation.Response#examples() examples()}
+ <li class='jm'>{@link oaj.http.annotation.Response#headers() headers()}
+ <li class='jm'>{@link oaj.http.annotation.Response#on() on()}
+ <li class='jm'>{@link oaj.http.annotation.Response#onClass() onClass()}
+ <li class='jm'>{@link oaj.http.annotation.Response#parser() parser()}
+ <li class='jm'>{@link oaj.http.annotation.Response#schema() schema()}
+ <li class='jm'>{@link oaj.http.annotation.Response#serializer() serializer()}
+ </ul>
+ <li class='ja'>{@link oaj.http.annotation.ResponseHeader}
+ <ul class='javatreec'>
+ <li class='jm'>{@link oaj.http.annotation.ResponseHeader#name() name()}
+ <li class='jm'>{@link oaj.http.annotation.ResponseHeader#on() on()}
+ <li class='jm'>{@link oaj.http.annotation.ResponseHeader#onClass() onClass()}
+ <li class='jm'>{@link oaj.http.annotation.ResponseHeader#schema() schema()}
+ <li class='jm'>{@link oaj.http.annotation.ResponseHeader#serializer() serializer()}
+ <li class='jm'>{@link oaj.http.annotation.ResponseHeader#value() value()}
+ </ul>
+ <li class='ja'>{@link oaj.http.annotation.ResponseCode}
+ <ul class='javatreec'>
+ <li class='jm'>{@link oaj.http.annotation.ResponseCode#on() on()}
+ <li class='jm'>{@link oaj.http.annotation.ResponseCode#onClass() onClass()}
+ <li class='jm'>{@link oaj.http.annotation.ResponseCode#value() value()}
+ </ul>
+ </ul>
+ <li><b>Common schema annotation:</b>
+ <ul class='javatree'>
+ <li class='ja'>{@link oaj.http.annotation.Schema}
+ <ul class='javatreec'>
+ <li class='jm'>{@link oaj.http.annotation.Schema#_default() _default()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#_enum() _enum()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#$ref() $ref()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#additionalProperties() additionalProperties()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#aev() aev()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#allOf() allOf()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#allowEmptyValue() allowEmptyValue()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#cf() cf()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#collectionFormat() collectionFormat()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#d() d()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#description() description()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#df() df()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#discriminator() discriminator()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#e() e()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#emax() emax()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#emin() emin()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#exclusiveMaximum() exclusiveMaximum()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#exclusiveMinimum() exclusiveMinimum()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#externalDocs() externalDocs()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#f() f()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#format() format()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#ignore() ignore()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#items() items()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#max() max()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#maxi() maxi()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#maximum() maximum()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#maxItems() maxItems()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#maxl() maxl()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#maxLength() maxLength()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#maxp() maxp()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#maxProperties() maxProperties()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#min() min()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#mini() mini()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#minimum() minimum()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#minItems() minItems()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#minl() minl()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#minLength() minLength()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#minp() minp()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#minProperties() minProperties()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#mo() mo()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#multipleOf() multipleOf()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#on() on()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#onClass() onClass()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#p() p()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#pattern() pattern()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#properties() properties()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#r() r()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#readOnly() readOnly()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#required() required()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#ro() ro()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#sie() sie()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#skipIfEmpty() v()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#t() t()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#title() title()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#type() type()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#ui() ui()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#uniqueItems() uniqueItems()}
+ <li class='jm'>{@link oaj.http.annotation.Schema#xml() xml()}
+ </ul>
+ </ul>
+</ul>
+<p>
+ The {@link oaj.http.annotation.Header @Header}/{@link oaj.http.annotation.Query @Query}/
+ {@link oaj.http.annotation.FormData @FormData}/{@link oaj.http.annotation.Path @Path} annotations
+ can be used on parameters of {@link oajr.annotation.RestOp @RestOp}-annotated methods to
+ get access to request headers, query parameters, form-data parameters, and path parts.
+</p>
+<p>
+ The most typical scenario is to simply use the <c>value</c> field to define parameter names:
+</p>
+<h5 class='figure'>Example:</h5>
+<p class='bpcode w800'>
+ <ja>@RestGet</ja>
+ <jk>public void</jk> doGet(
+ <ja>@Query</ja>(<js>"p1"</js>) <jk>int</jk> <jv>p1</jv>,
+ <ja>@Query</ja>(<js>"p2"</js>) String <jv>p2</jv>,
+ <ja>@Query</ja>(<js>"p3"</js>) UUID <jv>p3</jv>) {...}
+</p>
+<p>
+ This is functionally equivalent to the following code:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestGet</ja>
+ <jk>public void</jk> doGet(RestRequest <jv>req</jv>) {
+ RequestQueryParams <jv>query</jv> = <jv>req</jv>.getQueryParams();
+ <jk>int</jk> <jv>p1</jv> = <jv>query</jv>.get(<js>"p1"</js>).asInteger().orElse(0);
+ String <jv>p2</jv> = <jv>query</jv>.get(<js>"p2"</js>).orElse(<jk>null</jk>);
+ UUID <jv>p3</jv> = <jv>query</jv>.get(<js>"p3"</js>).as(UUID.<jk>class</jk>).orElse(<jk>null</jk>);
+ }
+</p>
+<p>
+ The special name <js>"*"</js> (or blank) can be used to represent all values.
+ When used, the data type must be a <c>Map</c> or bean.
+</p>
+<h5 class='figure'>Examples:</h5>
+<p class='bpcode w800'>
+ <jc>// Multiple values passed as a map.</jc>
+ <ja>@RestGet</ja>
+ <jk>public void</jk> doGet(<ja>@Query</ja>(<js>"*"</js>) Map<String,Object> <jv>map</jv>) {...}
+</p>
+<p class='bpcode w800'>
+ <jc>// Same, but name "*" is inferred.</jc>
+ <ja>@RestGet</ja>
+ <jk>public void</jk> doGet(<ja>@Query</ja> Map<String,Object> <jv>map</jv>) {...}
+</p>
+<p class='bpcode w800'>
+ <jc>// Multiple values passed as a bean.</jc>
+ <ja>@RestGet</ja>
+ <jk>public void</jk> doGet(<ja>@Query</ja> MyQueryBean <jv>bean</jv>) {...}
+</p>
+<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>
+ The {@link oaj.http.annotation.ResponseCode @ResponseCode}/{@link oaj.http.annotation.ResponseHeader @ResponseHeader} annotations
+ can be used on parameters and parameter types of {@link oajr.annotation.RestOp @RestOp}-annotated methods to
+ to define to response codes and headers. These are used in combination with the mutable {@link oaj.Value} object.
+</p>
+<h5 class='figure'>Example:</h5>
+<p class='bpcode w800'>
+ <ja>@RestGet</ja>(<js>"/user/login"</js>)
+ <jk>public void</jk> login(
+ <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
+ <ja>@FormData</ja>(<js>"password"</js>) String <jv>password</jv>,
+ <ja>@ResponseCode</ja> Value<Integer> <jv>status</jv>,
+ <ja>@ResponseHeader</ja>(<js>"My-Message"</js>) Value<String> <jv>myMessage</jv>
+ ) {
+ <jk>if</jk> (<jsm>isValid</jsm>(<jv>username</jv>, <jv>password</jv>)) {
+ <jv>status</jv>.set(200);
+ <jv>myMessage</jv>.set(<js>"Welcome "</js> + <jv>username</jv> + <js>"!"</js>);
+ } <jk>else</jk> {
+ <jv>status</jv>.set(401);
+ }
+ }
+</p>
+<p>
+ This is functionally equivalent to the following code:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestGet</ja>(<js>"/user/login"</js>)
+ <jk>public void</jk> doGet(RestRequest <jv>req</jv>, RestResponse <jv>res</jv>) {
+ RequestFormParams <jv>form</jv> = <jv>req</jv>.getFormParams();
+ String <jv>username</jv> = <jv>form</jv>.get(<js>"username"</js>).orElse(<jk>null</jk>);
+ String <jv>password</jv> = <jv>form</jv>.get(<js>"password"</js>).orElse(<jk>null</jk>);
+ <jk>if</jk> (<jsm>isValid</jsm>(<jv>username</jv>, <jv>password</jv>) {
+ <jv>res</jv>.setStatus(200);
+ <jv>res</jv>.setHeader(<js>"My-Message"</js>, <js>"Welcome "</js> + <jv>username</jv> + <js>"!"</js>);
+ } else {
+ <jv>res</jv>.setStatus(401);
+ }
+ }
+</p>
+<p>
+ The default registered part marshallers, {@link oaj.oapi.OpenApiSerializer} and {@link oaj.oapi.OpenApiParser}, are used to
+ marshall POJOs using schemas defined via the {@link oaj.http.annotation.Schema @Schema} annotation.
+</p>
+<ul class='javatree'>
+</ul>
+<p>
+ For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. <js>"1,2,3|4,5,6|7,8,9"</js>) can be converted to a 2-dimensional array of <c>Longs</c>:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestGet</ja>(<js>"/testQuery1"</js>)
+ <jk>public void</jk> testQuery1(
+ <ja>@Query</ja>(<js>"queryParamName"</js>)
+ <ja>@Schema</ja>(
+ collectionFormat=<js>"pipes"</js>,
+ items=<ja>@Items</ja>(
+ collectionFormat=<js>"csv"</js>,
+ type=<js>"integer"</js>,
+ format=<js>"int64"</js>,
+ minimum=<js>"0"</js>,
+ maximum=<js>"100"</js>
+ minLength=1,
+ maxLength=10
+ ),
+ minLength=1,
+ maxLength=10
+ )
+ Long[][] <jv>queryParameter</jv>
+ ) {...}
+
+ <jc>// Same but using condensed notation.</jc>
+ <ja>@RestGet</ja>(<js>"/testQuery2"</js>)
+ <jk>public void</jk> testQuery2(
+ <ja>@Query</ja>(<js>"queryParamName"</js>)
+ <ja>@Schema</ja>(
+ cf=<js>"pipes"</js>, minl=1, maxl=10,
+ i=<ja>@Items</ja>(cf=<js>"csv"</js>, t=<js>"integer"</js>, f=<js>"int64"</js>, min=<js>"0"</js>, max=<js>"100"</js>, minl=1, maxl=10)
+ )
+ Long[][] <jv>queryParameter</jv>
+ ) {...}
+</p>
+<p>
+ Schema-based marshalling works for both request and response parts.
+ Input will be converted based on the types and formats defined in the schema definition.
+ Input validations such as <c>minLength/maxLength</c> that don't match the input will result in automatic <c>400 Bad Request</c> responses.
+</p>
+
+<p>
+ The part and schema annotations are also used for supplying swagger information about the HTTP part.
+ This information is used to populate the auto-generated Swagger documentation and UI.
+</p>
+<h5 class='figure'>Example:</h5>
+<p class='bpcode w800'>
+ <ja>@Query</ja>(<js>"name"</js>)
+ <ja>@Schema</ja>(
+ description=<js>"Pet name"</js>,
+ required=<jk>true</jk>
+ )
+</p>
+<p>
+ {@doc RestSvlVariables SVL Variables} (e.g. "$L{my.localized.variable}") are supported on annotation fields as well.
+ Among other things, this allow for annotation values to be defined externally and the ability to produce localized swagger documents
+ based on the <c>Accept-Language</c> on a request.
+</p>
+<h5 class='figure'>Example:</h5>
+<p class='bpcode w800'>
+ <ja>@Schema</ja>(
+ description=<js>"$L{PetNameDescription}"</js>
+ )
+</p>
+<p>
+ The {@link oaj.http.annotation.Body @Body} annotation can also be used to parse HTTP request bodies using OpenAPI schemas
+ when the body content type matches the {@link oaj.oapi.OpenApiParser} parser via the header <c>Content-Type: text/openapi</c>.
+</p>
+<p>
+ The following shows the same for a request body:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestPost</ja>(<js>"/testBody"</js>)
+ <jk>public void</jk> testBody(
+ <ja>@Body</ja>
+ <ja>@Schema</ja>(
+ items=<ja>@Items</ja>(
+ collectionFormat=<js>"pipes"</js>,
+ items=<ja>@SubItems</ja>(
+ collectionFormat=<js>"csv"</js>,
+ type=<js>"integer"</js>,
+ format=<js>"int64"</js>,
+ minimum=<js>"0"</js>,
+ maximum=<js>"100"</js>
+ minLength=1,
+ maxLength=10
+ )
+ ),
+ minLength=1,
+ maxLength=10
+ )
+ Long[][] <jv>body</jv>
+ ) {...}
+</p>
+<p>
+ The list of valid POJO types for parameters depends on type and format of the value or items/entries of the value.
+ For example, instead of <c>Longs</c> in the example above, we could also define a 2-dimensional array of POJOs convertible from <c>Longs</c>:
+</p>
+<p class='bpcode w800'>
+ <jc>// Body is a 2-dimensional array of POJOs convertible from Longs:</jc>
+ <ja>@RestPost</ja>(<js>"/example1"</js>)
+ <jk>public void</jk> testBody(<ja>@Body</ja>(...) MyPojo1[][] <jv>body</jv>) {...}
+
+ <jk>public class</jk> MyPojo1 {
+ <jk>public</jk> MyPojo1(Long <jv>input</jv>) {...}
+ }
+</p>
+<p class='bpcode w800'>
+ <jc>// Body is a POJO that takes in a Long array:</jc>
+ <ja>@RestPost</ja>(<js>"/example2"</js>)
+ <jk>public void</jk> testBody(<ja>@Body</ja>(...) MyPojo2[] <jv>body</jv>) {...}
+
+ <jk>public class</jk> MyPojo2 {
+ <jk>public</jk> MyPojo2(Long[] <jv>input</jv>) {...}
+ }
+</p>
+<p class='bpcode w800'>
+ <jc>// Body is a POJO that takes in the whole 2-dimensional array:</jc>
+ <ja>@RestPost</ja>(<js>"/example3"</js>)
+ <jk>public void</jk> testBody(<ja>@Body</ja>(...) MyPojo3 <jv>body</jv>) {...}
+
+ <jk>public class</jk> MyPojo3 {
+ <jk>public</jk> MyPojo3(Long[][] <jv>input</jv>) {...}
+ }
+</p>
+<p>
+ As you can see, the complexity of possible input types expands significantly.
+ For more information about valid parameter types, see {@doc OpenApiParsers OpenAPI Parsers}
+</p>
+
+
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/03.Body.html b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/03.Body.html
deleted file mode 100644
index fa8f47e..0000000
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/03.Body.html
+++ /dev/null
@@ -1,170 +0,0 @@
-<!--
-/***************************************************************************************************************************
- * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
- * with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- ***************************************************************************************************************************/
- -->
-
-{title:'@Body and Request Bodies', updated:'8.1.0,9.0.0'}
-
-<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>
-<ul class='javatree'>
- <li class='ja'>{@link oaj.http.annotation.Body}
- <ul class='javatreec'>
- <li class='jm'>{@link oaj.http.annotation.Body#on() on()}
- <li class='jm'>{@link oaj.http.annotation.Body#onClass() onClass()}
- <li class='jm'>{@link oaj.http.annotation.Body#schema() schema()}
- </ul>
-</ul>
-<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>
- The {@link oaj.http.annotation.Body} annotation can also be used to parse HTTP request bodies using OpenAPI schemas
- when the body content type matches the {@link oaj.oapi.OpenApiParser} parser via the header <c>Content-Type: text/openapi</c>.
-</p>
-<p>
- The following shows the same for a request body:
-</p>
-<p class='bpcode w800'>
- <ja>@RestPost</ja>(<js>"/testBody"</js>)
- <jk>public void</jk> testBody(
- <ja>@Body</ja>
- <ja>@Schema</ja>(
- items=<ja>@Items</ja>(
- collectionFormat=<js>"pipes"</js>,
- items=<ja>@SubItems</ja>(
- collectionFormat=<js>"csv"</js>,
- type=<js>"integer"</js>,
- format=<js>"int64"</js>,
- minimum=<js>"0"</js>,
- maximum=<js>"100"</js>
- minLength=1,
- maxLength=10
- )
- ),
- minLength=1,
- maxLength=10
- )
- Long[][] <jv>body</jv>
- ) {...}
-</p>
-<p>
- The list of valid POJO types for parameters depends on type and format of the value or items/entries of the value.
- For example, instead of <c>Longs</c> in the example above, we could also define a 2-dimensional array of POJOs convertible from <c>Longs</c>:
-</p>
-<p class='bpcode w800'>
- <ja>@RestPost</ja>(<js>"/2dLongArray"</js>)
- <jk>public void</jk> testBody(<ja>@Body</ja>(...) MyPojo[][] <jv>body</jv>) {...}
-
- <jc>// POJO convertible from a Long.</jc>
- <jk>public class</jk> MyPojo {
- <jk>public</jk> MyPojo(Long <jv>input</jv>) {...}
- }
-</p>
-<p>
- Or even POJOs that take in arrays of <c>Longs[]</c>:
-</p>
-<p class='bpcode w800'>
- <ja>@RestPost</ja>(<js>"/2dLongArray"</js>)
- <jk>public void</jk> testBody(<ja>@Body</ja>(...) MyPojo[] <jv>body</jv>) {...}
-
- <jc>// POJO convertible from a Long[].</jc>
- <jk>public class</jk> MyPojo {
- <jk>public</jk> MyPojo(Long[] <jv>input</jv>) {...}
- }
-</p>
-<p>
- Or even POJOs that take in the whole 2-dimensional array:
-</p>
-<p class='bpcode w800'>
- <ja>@RestPost</ja>(<js>"/2dLongArray"</js>)
- <jk>public void</jk> testBody(<ja>@Body</ja>(...) MyPojo <jv>body</jv>) {...}
-
- <jc>// POJO convertible from a Long[][].</jc>
- <jk>public class</jk> MyPojo {
- <jk>public</jk> MyPojo(Long[][] <jv>input</jv>) {...}
- }
-</p>
-<p>
- As you can see, the complexity of possible input types expands significantly.
- For more information about valid parameter types, see {@doc OpenApiParsers OpenAPI Parsers}
-</p>
\ No newline at end of file
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/04.RequestBeans.html b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/03.RequestBeans.html
similarity index 76%
rename from juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/04.RequestBeans.html
rename to juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/03.RequestBeans.html
index a2ed053..0b0e52e 100644
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/04.RequestBeans.html
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/03.RequestBeans.html
@@ -13,20 +13,11 @@
***************************************************************************************************************************/
-->
-{title:'@Request beans', updated:'8.1.0,9.0.0'}
+{title:'@Request Beans', updated:'8.1.0,9.0.0'}
<p>
- The {@link oaj.http.annotation.Request @Request} annotation can be applied to a parameter interface type of a <ja>@RestOp</ja>-annotated method
- to identify it as an interface for retrieving HTTP parts through a bean-like interface.
-</p>
-<ul class='javatree'>
- <li class='ja'>{@link oaj.http.annotation.Request}
- <ul>
- <li class='jf'>{@link oaj.http.annotation.Request#parser() parser} - Override the part parser.
- </ul>
-</ul>
-<p>
- It's used in combination with the following annotation to define proxy interfaces against HTTP requests:
+ The {@link oaj.http.annotation.Request @Request} annotation can used to define proxy interfaces against
+ HTTP requests in combination with the following annotations used on methods:
</p>
<ul class='javatreec'>
<li class='ja'>{@link oaj.http.annotation.Header}
@@ -34,17 +25,18 @@
<li class='ja'>{@link oaj.http.annotation.FormData}
<li class='ja'>{@link oaj.http.annotation.Path}
<li class='ja'>{@link oaj.http.annotation.Body}
+ <li class='ja'>{@link oaj.http.annotation.Schema}
</ul>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
<ja>@RestPut</ja>(<js>"/pets/{petId}"</js>)
- <jk>public void</jk> putPet(UpdatePet <jv>updatePet</jv>) {...}
+ <jk>public void</jk> addPet(UpdatePetBean <jv>updatePet</jv>) {...}
<ja>@Request</ja>
- <jk>public interface</jk> UpdatePet {
+ <jk>public interface</jk> UpdatePetBean {
- <ja>@Path</ja>
+ <ja>@Path</ja> <jc>// {petId} inferred.</jc>
<jk>int</jk> getPetId();
<ja>@Query</ja>(<js>"verbose"</js>)
@@ -62,11 +54,11 @@
</p>
<p class='bpcode w800'>
<ja>@RestPut</ja>(<js>"/pets/{petId}"</js>)
- <jk>public void</jk> putPet(
+ <jk>public void</jk> addPet(
<ja>@Path</ja>(<js>"petId"</js>) <jk>int</jk> <jv>petId</jv>,
<ja>@Query</ja>(<js>"verbose"</js>) <jk>boolean</jk> <jv>debug</jv>,
<ja>@Header</ja>(<js>"*"</js>) Map<String,Object> <jv>allHeaders</jv>,
- <ja>@Body</ja> Pet <jv>pet</jv>
+ <ja>@Body</ja> UpdatePetBean <jv>pet</jv>
)
{...}
</p>
@@ -75,13 +67,15 @@
Schema-based serialization and parsing is used just as if used as individual parameter types.
Annotations used are the exact same used on REST parameters and have all the
same feature support including automatic Swagger validation and documentation.
+ Part names can either be explicitly specified or automatically inferred from the getter names.
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
<ja>@Request</ja>
- <jk>public interface</jk> Request {
+ <jk>public interface</jk> MyRequest {
- <jc>// Schema-based query parameter: Pipe-delimited lists of comma-delimited lists of integers.</jc>
+ <jc>// Schema-based query parameter "pipedCdlInts":
+ // Pipe-delimited list of comma-delimited lists of integers.</jc>
<ja>@Query</ja>
<ja>@Schema</ja>(
collectionFormat=<js>"pipes"</js>
@@ -104,8 +98,10 @@
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
<ja>@RestPut</ja>(<js>"/pets/{petId}"</js>)
- <jk>public void</jk> putPet(<ja>@Request</ja> UpdatePet <jv>updatePet</jv>) {...}
+ <jk>public void</jk> addPet(<ja>@Request</ja> UpdatePetBean <jv>updatePet</jv>) {...}
<ja>@Request</ja>
- <jk>public interface</jk> UpdatePet {...}
+ <jk>public interface</jk> UpdatePetBean {...}
</p>
+
+<p>
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/04.ResponseBeans.html b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/04.ResponseBeans.html
new file mode 100644
index 0000000..ee92a8c
--- /dev/null
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/04.ResponseBeans.html
@@ -0,0 +1,113 @@
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ ***************************************************************************************************************************/
+ -->
+
+{title:'@Response Beans', updated:'8.1.0,9.0.0'}
+
+<p>
+ The {@link oaj.http.annotation.Response} annotation can be used to define beans that return HTTP response
+ parts via annotations and methods. They are used in combination with the following annotations:
+</p>
+<ul class='javatreec'>
+ <li class='ja'>{@link oaj.http.annotation.ResponseCode}
+ <li class='ja'>{@link oaj.http.annotation.ResponseHeader}
+ <li class='ja'>{@link oaj.http.annotation.ResponseBody}
+ <li class='ja'>{@link oaj.http.annotation.Schema}
+</ul>
+
+<p>
+ Response beans can either be returned or thrown from {@link oajr.annotation.RestOp @RestOp}-annotated methods.
+</p>
+<ul>
+ <li class='note'>
+ As a general convention, response beans with return codes <c><400</c> should be defined as regular classes and
+ <c>>=400</c> should be defined as exceptions.
+</ul>
+<p>
+ The following example shows the <ja>@Response</ja> annotation used to define an exception for an invalid login attempt:
+</p>
+<p class='bpcode w800'>
+ <jc>// Our annotated normal response.</jc>
+ <ja>@Response</ja>
+ <ja>@ResponseCode</ja>(200)
+ <ja>@Schema</ja>(
+ description=<js>"User was good."</js> <jc>// Description show in Swagger</jc>
+ )
+ <jk>public class</jk> ValidLogin {
+ <jk>public</jk> ValidLogin() {
+ ...
+ }
+
+ <jc>// Response bean converted to output based on Accept header.</jc>
+ <ja>@ResponseBody</ja>
+ <jk>public</jk> WelcomeMessageBean getBody() {
+ <jk>return new </jk> WelcomeMessageBean();
+ }
+ }
+</p>
+<p class='bpcode w800'>
+ <jc>// Our annotated exception.</jc>
+ <ja>@Response</ja>
+ <ja>@ResponseCode</ja>(401)
+ <ja>@Schema</ja>(
+ description=<js>"Invalid username or password provided"</js> <jc>// Description show in Swagger</jc>
+ )
+ <jk>public class</jk> InvalidLogin <jk>extends</jk> Exception {
+ <jk>public</jk> InvalidLogin() {
+ <jk>super</jk>(<js>"Invalid username or password."</js>); <jc>// Message sent in response</jc>
+ }
+
+ <ja>@ResponseHeader</ja>(<js>"My-Message"</js>)
+ <jk>public</jk> String getMyMessage() {
+ <jk>return</jk> <js>"Nope!"</js>;
+ }
+ }
+</p>
+<p class='bpcode w800'>
+ <jc>// Our REST method that throws an annotated exception.</jc>
+ <ja>@RestGet</ja>(<js>"/user/login"</js>)
+ <jk>public</jk> ValidLogin login(
+ <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
+ <ja>@FormData</ja>(<js>"password"</js>) String <jv>password</jv>
+ ) <jk>throws</jk> InvalidLogin
+ {
+ <jk>if</jk> (<jsm>isValid</jsm>(<jv>username</jv>, <jv>password</jv>)) {
+ <jk>return new</jk> ValidLogin();
+ }
+ <jk>throw new</jk> InvalidLogin();
+ }
+</p>
+<p>
+ Custom exceptions can also extend from one of the predefined HTTP exceptions such as the {@link oaj.http.response.Unauthorized} exception:
+</p>
+<p class='bpcode w800'>
+ <jc>// Our annotated exception.</jc>
+ <ja>@Response</ja>
+ <ja>@Schema</ja>(
+ description=<js>"Invalid username or password provided"</js> <jc>// Overridden from parent class</jc>
+ )
+ <jk>public class</jk> InvalidLogin <jk>extends</jk> Unauthorized {
+ <jk>public</jk> InvalidLogin() {
+ <jk>super</jk>(<js>"Invalid username or password."</js>);
+ }
+ }
+
+ <jc>// Parent predefined exception class.</jc>
+ <ja>@Response</ja>
+ <ja>@ResponseCode(401)</ja>
+ <ja>@Schema</ja>(
+ description=<js>"Unauthorized"</js>
+ )
+ <jk>public class</jk> Unauthorized <jk>extends</jk> RestException {...}
+</p>
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/07.RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams.html b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/05.HttpPartApis.html
similarity index 70%
rename from juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/07.RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams.html
rename to juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/05.HttpPartApis.html
index 75a7f96..4c19568 100644
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/07.RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams.html
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/05.HttpPartApis.html
@@ -13,8 +13,15 @@
***************************************************************************************************************************/
-->
-{title:'RequestHeaders / RequestQueryParams / RequestFormParams / RequestPathParams', created:'9.0.0'}
+{title:'HTTP Part APIs', created:'9.0.0'}
<p>
- TODO
-</p>
\ No newline at end of file
+ Request HTTP parts can also be retrieved programmatically through the following classes that
+ can be passed in as parameters or access through {@link oajr.RestRequest} bean:
+</p>
+<ul class='javatreec'>
+ <li class='jc'>{@link oajr.RequestHeaders}
+ <li class='jc'>{@link oajr.RequestQueryParams}
+ <li class='jc'>{@link oajr.RequestFormParams}
+ <li class='jc'>{@link oajr.RequestPathParams}
+</ul>
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/05.ReponseHeader_ResponseStatus.html b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/05.ReponseHeader_ResponseStatus.html
deleted file mode 100644
index 71da889..0000000
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/05.ReponseHeader_ResponseStatus.html
+++ /dev/null
@@ -1,127 +0,0 @@
-<!--
-/***************************************************************************************************************************
- * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
- * with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- ***************************************************************************************************************************/
- -->
-
-{title:'@Response / @ResponseHeader / @ResponseCode', updated:'8.1.0,9.0.0'}
-
-<p>
- The {@link oaj.http.annotation.Response @Response} / {@link oaj.http.annotation.ResponseHeader @ResponseHeader} / {@link oaj.http.annotation.ResponseCode @ResponseCode} annotations
- allow you to define method parameters for setting HTTP response parts:
-</p>
-
-<ul class='javatree'>
- <li class='ja'>{@link oaj.http.annotation.Response}
- <ul class='javatreec'>
- <li class='jm'>{@link oaj.http.annotation.Response#examples() examples()}
- <li class='jm'>{@link oaj.http.annotation.Response#headers() headers()}
- <li class='jm'>{@link oaj.http.annotation.Response#on() on()}
- <li class='jm'>{@link oaj.http.annotation.Response#onClass() onClass()}
- <li class='jm'>{@link oaj.http.annotation.Response#parser() parser()}
- <li class='jm'>{@link oaj.http.annotation.Response#schema() schema()}
- <li class='jm'>{@link oaj.http.annotation.Response#serializer() serializer()}
- </ul>
- <li class='ja'>{@link oaj.http.annotation.ResponseHeader}
- <ul class='javatreec'>
- <li class='jm'>{@link oaj.http.annotation.ResponseHeader#name() name()}
- <li class='jm'>{@link oaj.http.annotation.ResponseHeader#on() on()}
- <li class='jm'>{@link oaj.http.annotation.ResponseHeader#onClass() onClass()}
- <li class='jm'>{@link oaj.http.annotation.ResponseHeader#schema() schema()}
- <li class='jm'>{@link oaj.http.annotation.ResponseHeader#serializer() serializer()}
- <li class='jm'>{@link oaj.http.annotation.ResponseHeader#value() value()}
- </ul>
- <li class='ja'>{@link oaj.http.annotation.ResponseCode}
- <ul class='javatreec'>
- <li class='jm'>{@link oaj.http.annotation.ResponseCode#on() on()}
- <li class='jm'>{@link oaj.http.annotation.ResponseCode#onClass() onClass()}
- <li class='jm'>{@link oaj.http.annotation.ResponseCode#value() value()}
- </ul>
-</ul>
-<p>
- Response part parameters are defined using a settable {@link oaj.Value} object.
-</p>
-<p>
- The {@link oaj.http.annotation.Response @Response} annotation can be used to set
- the response body as a settable parameter:
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/testResponseBody"</js>)
- <jk>public void</jk> testResponseBody(
- <ja>@Response</ja>(
- serializer=OpenApiSerialier.<jk>class</jk>
- )
- <ja>@Schema</ja>(
- items=<ja>@Items</ja>(
- collectionFormat=<js>"pipes"</js>,
- items=<ja>@SubItems</ja>(
- collectionFormat=<js>"csv"</js>,
- type=<js>"integer"</js>,
- format=<js>"int64"</js>,
- minimum=<js>"0"</js>,
- maximum=<js>"100"</js>
- minLength=1,
- maxLength=10
- )
- ),
- minLength=1,
- maxLength=10
- )
- Value<Long[][]> <jv>responseBody</jv>
- ) {...}
-</p>
-<p>
- The {@link oaj.http.annotation.ResponseHeader} annotation can be used to set
- response headers:
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/testResponseHeader"</js>)
- <jk>public void</jk> testResponseHeader(
- <ja>@ResponseHeader</ja>(<js>"My-Header"</js>)
- <ja>@Schema</ja>(
- collectionFormat=<js>"pipes"</js>,
- items=<ja>@SubItems</ja>(
- collectionFormat=<js>"csv"</js>,
- type=<js>"integer"</js>,
- format=<js>"int64"</js>,
- minimum=<js>"0"</js>,
- maximum=<js>"100"</js>
- minLength=1,
- maxLength=10
- ),
- minLength=1,
- maxLength=10
- )
- Value<Long[][]> <jv>header</jv>
- ) {
- <jv>header</jv>.set(<jk>new</jk> Long[][]{...});
- }
-</p>
-<p>
- The {@link oaj.http.annotation.ResponseCode @ResponseCode} annotation annotation can be used to
- set the HTTP response code:
-</p>
-<h5 class='figure'>Examples:</h5>
-<p class='bpcode w800'>
- <jc>// Defined on parameter.</jc>
- <ja>@RestGet</ja>(<js>"/user/login"</js>)
- <jk>public void</jk> login(
- <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
- <ja>@FormData</ja>(<js>"password"</js>) String <jv>password</jv>,
- <ja>@ResponseCode</ja> Value<Integer> <jv>status</jv>
- )
- {
- <jk>if</jk> (! <jsm>isValid</jsm>(<jv>username</jv>, <jv>password</jv>))
- <jv>status</jv>.set(401);
- }
-</p>
-
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/06.ResponseBeans.html b/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/06.ResponseBeans.html
deleted file mode 100644
index 5966521..0000000
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/04.HttpParts/06.ResponseBeans.html
+++ /dev/null
@@ -1,479 +0,0 @@
-<!--
-/***************************************************************************************************************************
- * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
- * with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations under the License.
- ***************************************************************************************************************************/
- -->
-
-{title:'@Response beans', updated:'8.1.0,9.0.0'}
-
-<p>
- The {@link oaj.http.annotation.Response} annotation can also be used in the following locations:
-</p>
-<ul>
- <li>Argument/exception/return types of <ja>@RestOp</ja>-annotated methods.
- <li><ja>@RestOp</ja>-annotated methods themselves.
-</ul>
-
-<p>
- When the <ja>@Response</ja> annotation is applied to classes, the following annotations can be used on
- public non-static methods of the class to identify parts of a response:
-</p>
-<ul class='javatree'>
- <li class='ja'>{@link oaj.http.annotation.ResponseStatus}
- <li class='ja'>{@link oaj.http.annotation.ResponseHeader}
- <li class='ja'>{@link oaj.http.annotation.ResponseBody}
-</ul>
-
-<h5 class='topic'>@Resource on exception classes</h5>
-<p>
- When applied to an exception class, this annotation defines Swagger schema and information on non-200 return types.
-</p>
-<p>
- The following example shows the <ja>@Response</ja> annotation used to define an exception for an invalid login attempt:
-</p>
-<p class='bpcode w800'>
- <jc>// Our annotated exception.</jc>
- <ja>@Response</ja>(
- code=401,
- description=<js>"Invalid username or password provided"</js> <jc>// Description show in Swagger</jc>
- )
- <jk>public class</jk> InvalidLogin <jk>extends</jk> Exception {
- <jk>public</jk> InvalidLogin() {
- <jk>super</jk>(<js>"Invalid username or password."</js>); <jc>// Message sent in response</jc>
- }
- }
-
- <jc>// Our REST method that throws an annotated exception.</jc>
- <ja>@RestGet</ja>(<js>"/user/login"</js>)
- <jk>public</jk> Ok login(
- <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
- <ja>@FormData</ja>(<js>"password"</js>) String <jv>password</jv>
- ) <jk>throws</jk> InvalidLogin
- {
- <jsm>checkCredentials</jsm>(<jv>username</jv>, <jv>password</jv>);
- <jk>return new</jk> Ok();
- }
-</p>
-<p>
- Custom exceptions can also extend from one of the predefined HTTP exceptions such as the {@del oaj.http.exception.Unauthorized} exception:
-</p>
-<p class='bpcode w800'>
- <jc>// Our annotated exception.</jc>
- <ja>@Response</ja>(
- description=<js>"Invalid username or password provided"</js> <jc>// Overridden from parent class</jc>
- )
- <jk>public class</jk> InvalidLogin <jk>extends</jk> Unauthorized {
- <jk>public</jk> InvalidLogin() {
- <jk>super</jk>(<js>"Invalid username or password."</js>);
- }
- }
-
- <jc>// Parent predefined exception class.</jc>
- <ja>@Response</ja>(
- code=401,
- description=<js>"Unauthorized"</js>
- )
- <jk>public class</jk> Unauthorized <jk>extends</jk> RestException {...}
-</p>
-
-<h5 class='topic'>@Resource on return type classes</h5>
-<p>
- When applied type classes returned by a Java method, this annotation defines schema and Swagger information on the body of responses.
-</p>
-<p>
- In the example above, we're using the <c>Ok</c> class which is defined like so:
-</p>
-<p class='bpcode w800'>
- <ja>@Response</ja>(
- code=200,
- description=<js>"OK"</js>
- )
- <jk>public class</jk> Ok {
-
- <ja>@ResponseBody</ja>
- <jk>public</jk> String toString() {
- <jk>return</jk> <js>"OK"</js>;
- }
- }
-</p>
-<p>
- Another example showing how a redirect can be defined:
-</p>
-<p class='bpcode w800'>
- <ja>@Response</ja>(
- code=307,
- description=<js>"Temporary Redirect"</js>
- )
- <jk>public class</jk> Redirect {
- <jk>private final</jk> URI <jf>location</jf>;
-
- <jk>public</jk> Redirect(URI <jv>location</jv>) {
- <jk>this</jk>.<jf>location</jf> = <jv>location</jv>;
- }
-
- <ja>@ResponseHeader</ja>(
- name=<js>"Location"</js>,
- format=<js>"uri"</js>
- )
- <jk>public</jk> URI getLocation() {
- <jk>return</jk> <jf>location</jf>;
- }
-
- <ja>@ResponseBody</ja>
- <jk>public</jk> String toString() {
- <jk>return</jk> <js>"Temporary Redirect"</js>;
- }
- }
-</p>
-<p class='bpcode w800'>
- <jc>// Usage</jc>
- <ja>@RestPost</ja>
- <jk>public</jk> Redirect postPet(Pet pet) {
- <jc>// Redirect to servlet root</jc>
- <jk>return new</jk> Redirect(URI.<jsm>create</jsm>(<js>"servlet:/"</js>));
- }
-</p>
-
-<h5 class='topic'>@Resource on @RestOp-annotated methods</h5>
-<p>
- The <ja>@Response</ja> annotation can also be applied to the Java method itself which is effectively
- the same as applying it to the return type (albeit for this method only).
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/user/login"</js>)
- <ja>@Response</ja>(code=200, description=<js>"OK"</js>)
- <jk>public</jk> Ok login(
- <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
- <ja>@FormData</ja>(<js>"password"</js>) String <jv>password</jv>
- ) <jk>throws</jk> InvalidLogin
- {
- <jsm>checkCredentials</jsm>(<jv>username</jv>, <jv>password</jv>);
- <jk>return new</jk> Ok();
- }
-</p>
-<p>
- The <ja>@Response</ja> annotation can be simultaneously on both the Java method and return type.
- When used in both locations, the annotation values are combined, but values defined on the
- method return annotation take precedence over the values defined on the type.
-</p>
-
-<h5 class='topic'>@Resource on @RestOp-annotated method parameters</h5>
-<p>
- The <ja>@Response</ja> annotation can also be applied to the Java method parameters when the parameter type
- is {@link oaj.Value} (a placeholder for objects).
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/user/login"</js>)
- <jk>public void</jk> login(
- <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
- <ja>@FormData</ja>(<js>"password"</js>) String <jv>password,/,
- <ja>@Response</ja>(code=200, description=<js>"Login succeeded"</js>) Value<String> <jv>body</jv>
- ) <jk>throws</jk> InvalidLogin
- {
- <jsm>checkCredentials</jsm>(<jv>username</jv>, <jv>password</jv>);
- <jv>body</jv>.set(<js>"OK"</js>);
- }
-</p>
-<p>
- <ja>@Response</ja>-annotated types can also be used as value parameters:
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(...)
- <jk>public void</jk> login(
- ...
- <ja>@Response</ja> Value<Ok> <jv>res</jv>
- ) <jk>throws</jk> InvalidLogin
- {
- ...
- <jv>res</jv>.set(<jk>new</jk> Ok());
- }
-</p>
-<p>
- In the above example, the <ja>@Response</ja> annotation is optional since it is inferred from the class
- that it's a <ja>@Response</ja> bean.
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/user/login"</js>)
- <jk>public void</jk> login(
- ...
- Value<Ok> <jv>res</jv> <jc>// @Response annotation not needed.</jc>
- ) <jk>throws</jk> InvalidLogin
- {
- ...
- <jv>res</jv>.set(<jk>new</jk> Ok());
- }
-</p>
-
-<h5 class='topic'>@ResponseStatus on methods of @Response-annotated types</h5>
-<p>
- The {@link oaj.http.annotation.ResponseStatus @ResponseStatus} annotation can be used on
- the method of a <ja>@Response</ja>-annotated class to identify HTTP response
- statuses other than <c>200</c> (the default).
-</p>
-
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <ja>@Response</ja>
- <jk>public class</jk> AddPetSuccess {
-
- <ja>@ResponseStatus</ja>
- <jk>public int</jk> getStatus() {
- <jk>return</jk> 201;
- }
-
- <ja>@Override</ja>
- <jk>public</jk> String toString() {
- <jk>return</jk> <js>"Pet was successfully added"</js>;
- }
- }
-</p>
-
-
-<h5 class='topic'>@ResponseHeader on methods of @Response-annotated types</h5>
-<p>
- The {@link oaj.http.annotation.ResponseHeader @ResponseHeader} annotation can be used on
- the method of a <ja>@Response</ja>-annotated class to identify a header
- to add to the response.
-</p>
-
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <ja>@Response</ja>
- <jk>public class</jk> AddPetSuccess {
-
- <ja>@ResponseHeader</ja>(
- name=<js>"X-PetId"</js>,
- type=<js>"integer"</js>,
- format=<js>"int32"</js>,
- description=<js>"ID of added pet."</js>,
- example=<js>"123"</js>
- )
- <jk>public int</jk> getPetId() {...}
- }
-</p>
-
-<h5 class='topic'>@ResponseBody on methods of @Response-annotated types</h5>
-<p>
- The {@link oaj.http.annotation.ResponseBody @ResponseBody} annotation can be used on
- the method of a <ja>@Response</ja>-annotated class to identify a POJO
- as the body of the HTTP response.
-</p>
-
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <ja>@Response</ja>
- <jk>public class</jk> AddPetSuccess {
-
- <ja>@ResponseBody</ja>
- <jk>public</jk> Pet getPet() {...}
- }
-</p>
-
-<p>
- If a <ja>@Response</ja> class does not have a <ja>@ResponseBody</ja>-annotated method, then the response
- object itself is serialized in the response (typically using <c>toString()</c>).
-</p>
-
-<h5 class='topic'>Notes about OpenAPI part serialization</h5>
-<p>
- By default, POJOs representing the body of the request are serialized using the Juneau serializer
- matching the requesting <c>Accept</c> header.
- The {@link oaj.oapi.OpenApiSerializer} class can be used to serialize response bodies using OpenAPI rules.
-</p>
-<p>
- The following examples show part-schema-based serialization of response bodies:
-</p>
-<p class='bpcode w800'>
- <ja>@Rest</ja>
- <jk>public class</jk> ExampleResource {
-
- <jc>// Example 1 - String[] should be serialized using part serializer.</jc>
- <ja>@Response</ja>(
- serializers=OpenApiSerializer.<jk>class</jk>,
- defaultAccept=<js>"text/openapi"</js>
- )
- <ja>@RestGet</ja>
- <jk>public</jk> String[] example1() {
- <jk>return new</jk> String[]{<js>"foo"</js>,<js>"bar"</js>};
- }
-
- <jc>// Example 2 - Same as above. Annotation on parameter.</jc>
- <ja>@RestGet</ja>
- <jk>public void</jk> example2(
- <ja>@Response</ja>(
- serializers=OpenApiSerializer.<jk>class</jk>,
- defaultAccept=<js>"text/openapi"</js>
- )
- Value<String[]> <jv>body</jv>
- )
- {
- <jv>body</jv>.set(<jk>new</jk> String[]{<js>"foo"</js>,<js>"bar"</js>});
- }
- }
-</p>
-<p>
- The <c><ja>@Response</ja>(schema)</c> annotation can be used to define the format of the output using OpenAPI-based rules.
-</p>
-<p class='bpcode w800'>
- <ja>@Rest</ja>
- <jk>public class</jk> ExampleResource {
-
- <ja>@Response</ja>(
- serializers=OpenApiSerializer.<jk>class</jk>,
- defaultAccept=<js>"text/openapi"</js>,
- schema=<ja>@Schema</ja>(collectionFormat=<js>"pipes"</js>)
- )
- <ja>@RestGet</ja>
- <jk>public</jk> String[] example1() {
- <jk>return new</jk> String[]{<js>"foo"</js>,<js>"bar"</js>};
- }
- }
-</p>
-
-<h5 class='topic'>Swagger documentation</h5>
-<p>
- The attributes on this annotation are also used to populate the generated Swagger for the method.
- For example, in the case of the <c>InvalidLogin</c> example above, the following Swagger is generated:
-</p>
-<p class='bpcode w800'>
- <jok>'/user/login'</jok>: {
- <jok>get</jok>: {
- <jok>responses</jok>: {
- <jok>401</jok>: {
- <jok>description</jok>: <jov>'Invalid username or password provided'</jov>
- }
- }
- }
- }
-</p>
-
-<h5 class='topic'>Automatic HTTP status</h5>
-<p>
- When the {@link oaj.http.annotation.ResponseCode#value() @Response(value)} value is specified,
- the HTTP status is automatically set to that value on the response regardless of how it's used.
-</p>
-<p>
- The following two examples are equivalent:
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/ok"</js>)
- <jk>public void</jk> sendContinue(
- <ja>@ResponseCode</ja>(code=100) Value<String> <jv>body</jv>
- )
- {
- <jv>body</jv>.set(<js>"OK"</js>);
- }
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/ok"</js>)
- <jk>public void</jk> sendContinue(RestResponse <jv>res</jv>) {
- <jv>res</jv>.setStatus(100);
- <jv>res</jv>.setOutput(<js>"OK"</js>);
- }
-</p>
-
-<ul class='seealso'>
- <li class='link'>{@doc RestOpenApiSchemaPartSerializing}
-</ul>
-
-<p>
- The {@link oaj.http.annotation.ResponseHeader @ResponseHeader} annotation can be applied to <ja>@RestOp</ja>-annotated parameters to denote them as an HTTP response headers.
-</p>
-<ul class='javatree'>
- <li class='ja'>{@link oaj.http.annotation.ResponseHeader}
- <ul>
- <li class='jf'>{@link oaj.http.annotation.ResponseHeader#name() name}
- <li class='jf'>{@link oaj.http.annotation.ResponseHeader#on() on}
- <li class='jf'>{@link oaj.http.annotation.ResponseHeader#onClass() onClass}
- <li class='jf'>{@link oaj.http.annotation.ResponseHeader#serializer() serializer}
- <li class='jf'>{@link oaj.http.annotation.ResponseHeader#value() value}
- </ul>
-</ul>
-<p>
- This annotation can only be applied to parameters of type {@link oaj.Value}.
-</p>
-<p>
- The following examples show 3 different ways of accomplishing the same task of setting an HTTP header
- on a response:
-</p>
-<p class='bpcode w800'>
- <jc>// Example #1 - Setting header directly on RestResponse object.</jc>
- <ja>@RestGet</ja>(...)
- <jk>public void</jk> login(RestResponse res) {
- res.setHeader(<js>"X-Rate-Limit"</js>, 1000);
- ...
- }
-
- <jc>// Example #2 - Use on parameter.</jc>
- <ja>@RestGet</ja>(...)
- <jk>public void</jk> login(
- <ja>@ResponseHeader</ja>(
- name=<js>"X-Rate-Limit"</js>,
- type=<js>"integer"</js>,
- format=<js>"int32"</js>,
- description=<js>"Calls per hour allowed by the user."</js>,
- example=<js>"123"</js>
- )
- Value<Integer> <jv>rateLimit</jv>
- )
- {
- <jv>rateLimit</jv>.set(1000);
- ...
- }
-
- <jc>// Example #3 - Use on type.</jc>
- <ja>@RestGet</ja>(...)
- <jk>public void</jk> login(Value<RateLimit> <jv>rateLimit</jv>) {
- <jv>rateLimit</jv>.set(<jk>new</jk> RateLimit());
- ...
- }
-
- <ja>@ResponseHeader</ja>(
- name=<js>"X-Rate-Limit"</js>,
- type=<js>"integer"</js>,
- format=<js>"int32"</js>,
- description=<js>"Calls per hour allowed by the user."</js>,
- example=<js>"123"</js>
- )
- <jk>public class</jk> RateLimit {
- <jc>// OpenApiSerializer knows to look for this method based on format/type.</jc>
- <jk>public</jk> Integer toInteger() {
- <jk>return</jk> 1000;
- }
- }
-</p>
-
-<p>
- The {@link oaj.http.annotation.ResponseStatus @ResponseStatus} annotation annotation can be applied to <ja>@RestOp</ja>-annotated parameters to denote them as an HTTP response status codes.
-</p>
-<ul class='javatree'>
- <li class='ja'>{@link oaj.http.annotation.ResponseStatus}
-</ul>
-<p>
- This can only be applied to parameters of the {@link oaj.Value} class with an {@link java.lang.Integer} type.
-</p>
-
-<h5 class='figure'>Examples:</h5>
-<p class='bpcode w800'>
- <jc>// Defined on parameter.</jc>
- <ja>@RestGet</ja>(<js>"/user/login"</js>)
- <jk>public void</jk> login(
- <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
- <ja>@FormData</ja>(<js>"password"</js>) String <jv>password</jv>,
- <ja>@ResponseStatus</ja> Value<Integer> <jv>status</jv>
- )
- {
- <jk>if</jk> (! <jsm>isValid</jsm>(<jv>username</jv>, <jv>password</jv>))
- <jv>status</jv>.set(401);
- }
-</p>
-
diff --git a/juneau-doc/src/main/javadoc/overview.html b/juneau-doc/src/main/javadoc/overview.html
index d87beae..053d812 100644
--- a/juneau-doc/src/main/javadoc/overview.html
+++ b/juneau-doc/src/main/javadoc/overview.html
@@ -348,15 +348,22 @@
<li><p><a class='doclink' href='#juneau-rest-server.RestAnnotatedClasses.RestLifecycleHooks'>Lifecycle Hooks</a><span class='update'>updated: <b>9.0.0</b></span></p>
</ol>
<li><p><a class='doclink' href='#juneau-rest-server.RestOpAnnotatedMethods'>@RestOp-Annotated Methods</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <ol>
+ <li><p><a class='doclink' href='#juneau-rest-server.RestOpAnnotatedMethods.InferredHttpMethodsAndPaths'>Inferred HTTP Methods and Paths</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='#juneau-rest-server.RestOpAnnotatedMethods.JavaMethodParameters'>Java Method Parameters</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='#juneau-rest-server.RestOpAnnotatedMethods.JavaMethodReturnTypes'>Java Method Return Types</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='#juneau-rest-server.RestOpAnnotatedMethods.JavaMethodThrowableTypes'>Java Method Throwable Types</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='#juneau-rest-server.RestOpAnnotatedMethods.PathPatterns'>Path Patterns</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='#juneau-rest-server.RestOpAnnotatedMethods.Matchers'>Matchers</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='#juneau-rest-server.RestOpAnnotatedMethods.AdditionalInformation'>Additional Information</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ </ol>
<li><p><a class='doclink' href='#juneau-rest-server.HttpParts'>HTTP Parts</a><span class='update'>updated: <b>9.0.0</b></span></p>
<ol>
- <li><p><a class='doclink' href='#juneau-rest-server.HttpParts.PartSerializers_PartParsers'>Part Serializers / Part Parsers</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
- <li><p><a class='doclink' href='#juneau-rest-server.HttpParts.Header_Path_Query_FormData'>@Header / @Path / @Query / @FormData</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
- <li><p><a class='doclink' href='#juneau-rest-server.HttpParts.Body'>@Body and Request Bodies</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
- <li><p><a class='doclink' href='#juneau-rest-server.HttpParts.RequestBeans'>@Request beans</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
- <li><p><a class='doclink' href='#juneau-rest-server.HttpParts.ReponseHeader_ResponseStatus'>@Response / @ResponseHeader / @ResponseCode</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
- <li><p><a class='doclink' href='#juneau-rest-server.HttpParts.ResponseBeans'>@Response beans</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
- <li><p><a class='doclink' href='#juneau-rest-server.HttpParts.RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams'>RequestHeaders / RequestQueryParams / RequestFormParams / RequestPathParams</a><span class='update'>created: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='#juneau-rest-server.HttpParts.PartMarshallers'>Part Marshallers</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='#juneau-rest-server.HttpParts.HttpPartAnnotations'>HTTP Part Annotations</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='#juneau-rest-server.HttpParts.RequestBeans'>@Request Beans</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='#juneau-rest-server.HttpParts.ResponseBeans'>@Response Beans</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='#juneau-rest-server.HttpParts.HttpPartApis'>HTTP Part APIs</a><span class='update'>created: <b>9.0.0</b></span></p>
</ol>
<li><p><a class='doclink' href='#juneau-rest-server.RestHandlingFormPosts'>Handling Form Posts</a><span class='update'><b><red>todo</red></b></span></p>
<li><p><a class='doclink' href='#juneau-rest-server.RestHandlingMultiPartFormPosts'>Handling Multi-Part Form Posts</a><span class='update'>updated: 8.0.0, <b><red>todo</red></b></span></p>
@@ -14934,7 +14941,10 @@
}
</p>
-<h5 class='topic'>Inferred HTTP methods and paths</h5>
+<!-- ==================================================================================================== -->
+
+<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.RestOpAnnotatedMethods.InferredHttpMethodsAndPaths' id='juneau-rest-server.RestOpAnnotatedMethods.InferredHttpMethodsAndPaths'>6.3.1 - Inferred HTTP Methods and Paths</a><span class='update'>updated: <b>9.0.0</b></span></h4>
+<div class='topic'><!-- START: 6.3.1 - juneau-rest-server.RestOpAnnotatedMethods.InferredHttpMethodsAndPaths -->
<p>
When the <c>name</c> and/or <c>path</c> values are not specified, their values are inferred
from the Java method name.
@@ -14992,8 +15002,12 @@
<p>
If <c>name</c> and <c>path</c> are both specified, the Java method name can be anything.
</p>
+</div><!-- END: 6.3.1 - juneau-rest-server.RestOpAnnotatedMethods.InferredHttpMethodsAndPaths -->
-<h5 class='topic'>Java Method Parameters</h5>
+<!-- ==================================================================================================== -->
+
+<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.RestOpAnnotatedMethods.JavaMethodParameters' id='juneau-rest-server.RestOpAnnotatedMethods.JavaMethodParameters'>6.3.2 - Java Method Parameters</a><span class='update'>updated: <b>9.0.0</b></span></h4>
+<div class='topic'><!-- START: 6.3.2 - juneau-rest-server.RestOpAnnotatedMethods.JavaMethodParameters -->
<p>
Java methods can contain any of the following parameters in any order:
</p>
@@ -15158,8 +15172,12 @@
Additional parameter types can be defined by overriding {@link org.apache.juneau.rest.RestContext.Builder#createRestOpArgs(BeanStore,Supplier)} or
by adding them to the bean store using {@link org.apache.juneau.rest.RestContext.Builder#createBeanStore(Class,Supplier)}.
</p>
+</div><!-- END: 6.3.2 - juneau-rest-server.RestOpAnnotatedMethods.JavaMethodParameters -->
+
+<!-- ==================================================================================================== -->
-<h5 class='topic'>Java Method Return Types</h5>
+<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.RestOpAnnotatedMethods.JavaMethodReturnTypes' id='juneau-rest-server.RestOpAnnotatedMethods.JavaMethodReturnTypes'>6.3.3 - Java Method Return Types</a><span class='update'>updated: <b>9.0.0</b></span></h4>
+<div class='topic'><!-- START: 6.3.3 - juneau-rest-server.RestOpAnnotatedMethods.JavaMethodReturnTypes -->
<p>
The return type of the Java method can be any serializable POJO as defined in {@doc PojoCategories POJO Categories}.
It can also be <jk>void</jk> if the method is not sending any output (e.g. a request redirect) or is
@@ -15290,8 +15308,12 @@
<p>
Additional parameter types can be defined by overriding {@link org.apache.juneau.rest.RestContext.Builder#createResponseProcessors(BeanStore,Supplier)}.
</p>
+</div><!-- END: 6.3.3 - juneau-rest-server.RestOpAnnotatedMethods.JavaMethodReturnTypes -->
-<h5 class='topic'>Java Method Throwable Types</h5>
+<!-- ==================================================================================================== -->
+
+<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.RestOpAnnotatedMethods.JavaMethodThrowableTypes' id='juneau-rest-server.RestOpAnnotatedMethods.JavaMethodThrowableTypes'>6.3.4 - Java Method Throwable Types</a><span class='update'>updated: <b>9.0.0</b></span></h4>
+<div class='topic'><!-- START: 6.3.4 - juneau-rest-server.RestOpAnnotatedMethods.JavaMethodThrowableTypes -->
<p>
Annotated Java methods can throw any of the following:
</p>
@@ -15371,8 +15393,12 @@
<jk>return</jk> Ok.<jsf>OK</jsf>;
}
</p>
+</div><!-- END: 6.3.4 - juneau-rest-server.RestOpAnnotatedMethods.JavaMethodThrowableTypes -->
+
+<!-- ==================================================================================================== -->
-<h5 class='topic'>Path Patterns</h5>
+<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.RestOpAnnotatedMethods.PathPatterns' id='juneau-rest-server.RestOpAnnotatedMethods.PathPatterns'>6.3.5 - Path Patterns</a><span class='update'>updated: <b>9.0.0</b></span></h4>
+<div class='topic'><!-- START: 6.3.5 - juneau-rest-server.RestOpAnnotatedMethods.PathPatterns -->
<p>
The {@link org.apache.juneau.rest.annotation.RestOp#path() @RestOp(path)} annotation allows
you to define URL path patterns to match against.
@@ -15459,8 +15485,12 @@
<jc>// URL path pattern must match exactly and will cause a 404 error if a remainder exists.</jc>
}
</p>
+</div><!-- END: 6.3.5 - juneau-rest-server.RestOpAnnotatedMethods.PathPatterns -->
-<h5 class='topic'>Matchers</h5>
+<!-- ==================================================================================================== -->
+
+<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.RestOpAnnotatedMethods.Matchers' id='juneau-rest-server.RestOpAnnotatedMethods.Matchers'>6.3.6 - Matchers</a><span class='update'>updated: <b>9.0.0</b></span></h4>
+<div class='topic'><!-- START: 6.3.6 - juneau-rest-server.RestOpAnnotatedMethods.Matchers -->
<p>
{@link org.apache.juneau.rest.RestMatcher RestMatchers} are used to allow multiple Java methods to be
tied to the same HTTP method and path, but differentiated by some request attribute such as a specific
@@ -15514,8 +15544,12 @@
<li class='jc'>{@link org.apache.juneau.rest.matchers.MultipartFormDataMatcher}
<li class='jc'>{@link org.apache.juneau.rest.matchers.UrlEncodedFormMatcher}
</ul>
+</div><!-- END: 6.3.6 - juneau-rest-server.RestOpAnnotatedMethods.Matchers -->
+
+<!-- ==================================================================================================== -->
-<h5 class='topic'>More Information</h5>
+<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.RestOpAnnotatedMethods.AdditionalInformation' id='juneau-rest-server.RestOpAnnotatedMethods.AdditionalInformation'>6.3.7 - Additional Information</a><span class='update'>updated: <b>9.0.0</b></span></h4>
+<div class='topic'><!-- START: 6.3.7 - juneau-rest-server.RestOpAnnotatedMethods.AdditionalInformation -->
<p>
Refer to the following Javadocs for more information:
</p>
@@ -15529,6 +15563,7 @@
<li class='jc'>{@link org.apache.juneau.rest.RequestPathParams}
<li class='jc'>{@link org.apache.juneau.rest.RequestAttributes}
</ul>
+</div><!-- END: 6.3.7 - juneau-rest-server.RestOpAnnotatedMethods.AdditionalInformation -->
</div><!-- END: 6.3 - juneau-rest-server.RestOpAnnotatedMethods -->
<!-- ==================================================================================================== -->
@@ -15545,7 +15580,7 @@
<jk>public</jk> String doGetExample1(
<ja>@Path</ja>(<js>"a1"</js>) String <jv>a1</jv>,
<ja>@Query</ja>(<js>"p1"</js>) <jk>int</jk> <jv>p1</jv>,
- <ja>@HasQuery</ja>(<js>"p2"</js>) boolean <jv>hasP3</jv>,
+ <ja>@HasQuery</ja>(<js>"p2"</js>) <jk>boolean</jk> <jv>hasP3</jv>,
<ja>@Path</ja>(<js>"/*"</js>) String <jv>remainder</jv>,
<ja>@Header</ja>(<js>"Accept-Language"</js>) String <jv>lang</jv>
) {
@@ -15592,23 +15627,13 @@
taking precedence. When defined on both, annotations are aggregated with values on parameters
taking precedence.
</ul>
-<p>
- Request HTTP parts can also be retrieved programmatically through the following classes that
- can be passed in as parameters or access through {@link org.apache.juneau.rest.RestRequest} bean:
-</p>
-<ul class='javatreec'>
- <li class='jc'>{@link org.apache.juneau.rest.RequestHeaders}
- <li class='jc'>{@link org.apache.juneau.rest.RequestQueryParams}
- <li class='jc'>{@link org.apache.juneau.rest.RequestFormParams}
- <li class='jc'>{@link org.apache.juneau.rest.RequestPathParams}
-</ul>
<!-- ==================================================================================================== -->
-<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.HttpParts.PartSerializers_PartParsers' id='juneau-rest-server.HttpParts.PartSerializers_PartParsers'>6.4.1 - Part Serializers / Part Parsers</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></h4>
-<div class='topic'><!-- START: 6.4.1 - juneau-rest-server.HttpParts.PartSerializers_PartParsers -->
+<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.HttpParts.PartMarshallers' id='juneau-rest-server.HttpParts.PartMarshallers'>6.4.1 - Part Marshallers</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></h4>
+<div class='topic'><!-- START: 6.4.1 - juneau-rest-server.HttpParts.PartMarshallers -->
<p>
- Juneau comes with three basic marshall types for serializing and parsing HTTP parts:
+ Juneau comes with three basic marshall types for serializing and parsing Header, Query, Form, and Path parts:
</p>
<ul class='javatree'>
<li class='jic'>{@link org.apache.juneau.httppart.HttpPartSerializer}
@@ -15653,56 +15678,162 @@
<p class='bpcode w800'>
<ja>@Query</ja>(..., schema=<ja>@Schema</ja>(format=<js>"uon"</js>)) Map<Integer,MyBean> <jv>myMap</jv>
</p>
-</div><!-- END: 6.4.1 - juneau-rest-server.HttpParts.PartSerializers_PartParsers -->
+</div><!-- END: 6.4.1 - juneau-rest-server.HttpParts.PartMarshallers -->
<!-- ==================================================================================================== -->
-<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.HttpParts.Header_Path_Query_FormData' id='juneau-rest-server.HttpParts.Header_Path_Query_FormData'>6.4.2 - @Header / @Path / @Query / @FormData</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></h4>
-<div class='topic'><!-- START: 6.4.2 - juneau-rest-server.HttpParts.Header_Path_Query_FormData -->
+<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.HttpParts.HttpPartAnnotations' id='juneau-rest-server.HttpParts.HttpPartAnnotations'>6.4.2 - HTTP Part Annotations</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></h4>
+<div class='topic'><!-- START: 6.4.2 - juneau-rest-server.HttpParts.HttpPartAnnotations -->
<p>
- The {@link org.apache.juneau.http.annotation.Header @Header} / {@link org.apache.juneau.http.annotation.Path @Path} / {@link org.apache.juneau.http.annotation.Query @Query} / {@link org.apache.juneau.http.annotation.FormData @FormData}
- annotations allow for defining part schemas based on the OpenAPI standard.
+ The following annotations allow for defining part schemas based on the OpenAPI standard.
</p>
-<ul class='javatree'>
- <li class='ja'>{@link org.apache.juneau.http.annotation.Header}
- <ul class='javatreec'>
- <li class='jm'>{@link org.apache.juneau.http.annotation.Header#name() name()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Header#parser() parser()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Header#schema() schema()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Header#serializer() serializer()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Header#value() value()}
- </ul>
- <li class='ja'>{@link org.apache.juneau.http.annotation.Query}
- <ul class='javatreec'>
- <li class='jm'>{@link org.apache.juneau.http.annotation.Query#name() name()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Query#parser() parser()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Query#schema() schema()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Query#serializer() serializer()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Query#value() value()}
- </ul>
- <li class='ja'>{@link org.apache.juneau.http.annotation.FormData}
- <ul class='javatreec'>
- <li class='jm'>{@link org.apache.juneau.http.annotation.FormData#name() name()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.FormData#parser() parser()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.FormData#schema() schema()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.FormData#serializer() serializer()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.FormData#value() value()}
+<ul class='spaced-list'>
+ <li><b>Request annotations:</b>
+ <ul class='javatree'>
+ <li class='ja'>{@link org.apache.juneau.http.annotation.Request}
+ <ul class='javatreec'>
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Request#on() on()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Request#onClass() onClass()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Request#parser() parser()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Request#serializer() serializer()}
+ </ul>
+ <li class='ja'>{@link org.apache.juneau.http.annotation.Header}
+ <ul class='javatreec'>
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Header#name() name()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Header#parser() parser()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Header#schema() schema()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Header#serializer() serializer()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Header#value() value()}
+ </ul>
+ <li class='ja'>{@link org.apache.juneau.http.annotation.Query}
+ <ul class='javatreec'>
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Query#name() name()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Query#parser() parser()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Query#schema() schema()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Query#serializer() serializer()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Query#value() value()}
+ </ul>
+ <li class='ja'>{@link org.apache.juneau.http.annotation.FormData}
+ <ul class='javatreec'>
+ <li class='jm'>{@link org.apache.juneau.http.annotation.FormData#name() name()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.FormData#parser() parser()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.FormData#schema() schema()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.FormData#serializer() serializer()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.FormData#value() value()}
+ </ul>
+ <li class='ja'>{@link org.apache.juneau.http.annotation.Path}
+ <ul class='javatreec'>
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Path#name() name()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Path#parser() parser()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Path#schema() schema()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Path#serializer() serializer()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Path#value() value()}
+ </ul>
+ <li class='ja'>{@link org.apache.juneau.http.annotation.Body}
+ <ul class='javatreec'>
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Body#on() on()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Body#onClass() onClass()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Body#schema() schema()}
+ </ul>
</ul>
- <li class='ja'>{@link org.apache.juneau.http.annotation.Path}
- <ul class='javatreec'>
- <li class='jm'>{@link org.apache.juneau.http.annotation.Path#name() name()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Path#parser() parser()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Path#schema() schema()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Path#serializer() serializer()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Path#value() value()}
+ <li><b>Response annotations:</b>
+ <ul class='javatree'>
+ <li class='ja'>{@link org.apache.juneau.http.annotation.Response}
+ <ul class='javatreec'>
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Response#examples() examples()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Response#headers() headers()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Response#on() on()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Response#onClass() onClass()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Response#parser() parser()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Response#schema() schema()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Response#serializer() serializer()}
+ </ul>
+ <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseHeader}
+ <ul class='javatreec'>
+ <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseHeader#name() name()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseHeader#on() on()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseHeader#onClass() onClass()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseHeader#schema() schema()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseHeader#serializer() serializer()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseHeader#value() value()}
+ </ul>
+ <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseCode}
+ <ul class='javatreec'>
+ <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseCode#on() on()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseCode#onClass() onClass()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseCode#value() value()}
+ </ul>
</ul>
+ <li><b>Common schema annotation:</b>
+ <ul class='javatree'>
+ <li class='ja'>{@link org.apache.juneau.http.annotation.Schema}
+ <ul class='javatreec'>
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#_default() _default()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#_enum() _enum()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#$ref() $ref()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#additionalProperties() additionalProperties()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#aev() aev()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#allOf() allOf()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#allowEmptyValue() allowEmptyValue()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#cf() cf()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#collectionFormat() collectionFormat()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#d() d()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#description() description()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#df() df()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#discriminator() discriminator()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#e() e()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#emax() emax()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#emin() emin()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#exclusiveMaximum() exclusiveMaximum()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#exclusiveMinimum() exclusiveMinimum()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#externalDocs() externalDocs()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#f() f()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#format() format()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#ignore() ignore()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#items() items()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#max() max()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maxi() maxi()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maximum() maximum()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maxItems() maxItems()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maxl() maxl()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maxLength() maxLength()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maxp() maxp()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maxProperties() maxProperties()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#min() min()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#mini() mini()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#minimum() minimum()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#minItems() minItems()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#minl() minl()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#minLength() minLength()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#minp() minp()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#minProperties() minProperties()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#mo() mo()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#multipleOf() multipleOf()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#on() on()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#onClass() onClass()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#p() p()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#pattern() pattern()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#properties() properties()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#r() r()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#readOnly() readOnly()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#required() required()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#ro() ro()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#sie() sie()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#skipIfEmpty() v()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#t() t()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#title() title()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#type() type()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#ui() ui()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#uniqueItems() uniqueItems()}
+ <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#xml() xml()}
+ </ul>
+ </ul>
</ul>
<p>
- The {@link org.apache.juneau.http.annotation.Header @Header} annotation is used to retrieve parsed request headers.
- The {@link org.apache.juneau.http.annotation.Query @Query} annotation is used to retrieve request URL query parameters.
- The {@link org.apache.juneau.http.annotation.FormData @FormData} annotation is used to retrieve request form post parameters.
- And the {@link org.apache.juneau.http.annotation.Path @Path} annotation is used to retrieve parsed URL path variables and
- remainders.
+ The {@link org.apache.juneau.http.annotation.Header @Header}/{@link org.apache.juneau.http.annotation.Query @Query}/
+ {@link org.apache.juneau.http.annotation.FormData @FormData}/{@link org.apache.juneau.http.annotation.Path @Path} annotations
+ can be used on parameters of {@link org.apache.juneau.rest.annotation.RestOp @RestOp}-annotated methods to
+ get access to request headers, query parameters, form-data parameters, and path parts.
</p>
<p>
The most typical scenario is to simply use the <c>value</c> field to define parameter names:
@@ -15747,145 +15878,9 @@
<ja>@RestGet</ja>
<jk>public void</jk> doGet(<ja>@Query</ja> MyQueryBean <jv>bean</jv>) {...}
</p>
-
-<p>
- The default registered part parser {@link org.apache.juneau.oapi.OpenApiParser} is used to convert strings
- to POJOs using schemas defined via the {@link org.apache.juneau.http.annotation.Schema} annotation.
-</p>
-<ul class='javatree'>
- <li class='ja'>{@link org.apache.juneau.http.annotation.Schema}
- <ul class='javatreec'>
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#_default() _default()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#_enum() _enum()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#$ref() $ref()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#additionalProperties() additionalProperties()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#aev() aev()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#allOf() allOf()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#allowEmptyValue() allowEmptyValue()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#cf() cf()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#collectionFormat() collectionFormat()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#d() d()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#description() description()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#df() df()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#discriminator() discriminator()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#e() e()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#emax() emax()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#emin() emin()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#exclusiveMaximum() exclusiveMaximum()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#exclusiveMinimum() exclusiveMinimum()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#externalDocs() externalDocs()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#f() f()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#format() format()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#ignore() ignore()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#items() items()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#max() max()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maxi() maxi()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maximum() maximum()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maxItems() maxItems()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maxl() maxl()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maxLength() maxLength()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maxp() maxp()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#maxProperties() maxProperties()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#min() min()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#mini() mini()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#minimum() minimum()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#minItems() minItems()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#minl() minl()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#minLength() minLength()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#minp() minp()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#minProperties() minProperties()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#mo() mo()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#multipleOf() multipleOf()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#on() on()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#onClass() onClass()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#p() p()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#pattern() pattern()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#properties() properties()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#r() r()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#readOnly() readOnly()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#required() required()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#ro() ro()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#sie() sie()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#skipIfEmpty() v()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#t() t()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#title() title()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#type() type()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#ui() ui()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#uniqueItems() uniqueItems()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Schema#xml() xml()}
- </ul>
-</ul>
-<p>
- For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. <js>"1,2,3|4,5,6|7,8,9"</js>) can be converted to a 2-dimensional array of <c>Longs</c>:
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/testQuery"</js>)
- <jk>public void</jk> testQuery(
- <ja>@Query</ja>(<js>"queryParamName"</js>)
- <ja>@Schema</ja>(
- collectionFormat=<js>"pipes"</js>,
- items=<ja>@SubItems</ja>(
- collectionFormat=<js>"csv"</js>,
- type=<js>"integer"</js>,
- format=<js>"int64"</js>,
- minimum=<js>"0"</js>,
- maximum=<js>"100"</js>
- minLength=1,
- maxLength=10
- ),
- minLength=1,
- maxLength=10
- )
- Long[][] <jv>queryParameter</jv>
- ) {...}
-</p>
-<p>
- Input will be converted based on the types and formats defined in the schema definition.
- Input validations such as <c>minLength/maxLength</c> that don't match the input will result in automatic <c>400 Bad Request</c> responses.
-</p>
-
-<p>
- The request part annotations are also used for supplying swagger information about the HTTP part.
- This information is used to populate the auto-generated Swagger documentation and UI.
-</p>
-<h5 class='figure'>Examples:</h5>
-<p class='bpcode w800'>
- <jc>// Normal</jc>
- <ja>@Query</ja>(<js>"name"</js>)
- <ja>@Schema</ja>(
- description=<js>"Pet name"</js>,
- required=<jk>true</jk>,
- example=<js>"Doggie"</js>
- )
-</p>
-<p>
- {@doc RestSvlVariables SVL Variables} (e.g. "$L{my.localized.variable}") are supported on annotation fields as well.
- Among other things, this allow for annotation values to be defined externally and the ability to produce localized swagger documents
- based on the <c>Accept-Language</c> on a request.
-</p>
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <ja>@Schema</ja>(
- description=<js>"$L{PetNameDescription}"</js>
- )
-</p>
-</div><!-- END: 6.4.2 - juneau-rest-server.HttpParts.Header_Path_Query_FormData -->
-
-<!-- ==================================================================================================== -->
-
-<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.HttpParts.Body' id='juneau-rest-server.HttpParts.Body'>6.4.3 - @Body and Request Bodies</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></h4>
-<div class='topic'><!-- START: 6.4.3 - juneau-rest-server.HttpParts.Body -->
<p>
The {@link org.apache.juneau.http.annotation.Body @Body} annotation is used to identify POJOs to be used as the body of an HTTP request.
</p>
-<ul class='javatree'>
- <li class='ja'>{@link org.apache.juneau.http.annotation.Body}
- <ul class='javatreec'>
- <li class='jm'>{@link org.apache.juneau.http.annotation.Body#on() on()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Body#onClass() onClass()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Body#schema() schema()}
- </ul>
-</ul>
<h5 class='figure'>Examples:</h5>
<p class='bpcode w800'>
<jc>// Defined on parameter</jc>
@@ -15958,7 +15953,116 @@
Any {@link java.util.Optional} of anything on this list.
</ol>
<p>
- The {@link org.apache.juneau.http.annotation.Body} annotation can also be used to parse HTTP request bodies using OpenAPI schemas
+ The {@link org.apache.juneau.http.annotation.ResponseCode @ResponseCode}/{@link org.apache.juneau.http.annotation.ResponseHeader @ResponseHeader} annotations
+ can be used on parameters and parameter types of {@link org.apache.juneau.rest.annotation.RestOp @RestOp}-annotated methods to
+ to define to response codes and headers. These are used in combination with the mutable {@link org.apache.juneau.Value} object.
+</p>
+<h5 class='figure'>Example:</h5>
+<p class='bpcode w800'>
+ <ja>@RestGet</ja>(<js>"/user/login"</js>)
+ <jk>public void</jk> login(
+ <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
+ <ja>@FormData</ja>(<js>"password"</js>) String <jv>password</jv>,
+ <ja>@ResponseCode</ja> Value<Integer> <jv>status</jv>,
+ <ja>@ResponseHeader</ja>(<js>"My-Message"</js>) Value<String> <jv>myMessage</jv>
+ ) {
+ <jk>if</jk> (<jsm>isValid</jsm>(<jv>username</jv>, <jv>password</jv>)) {
+ <jv>status</jv>.set(200);
+ <jv>myMessage</jv>.set(<js>"Welcome "</js> + <jv>username</jv> + <js>"!"</js>);
+ } <jk>else</jk> {
+ <jv>status</jv>.set(401);
+ }
+ }
+</p>
+<p>
+ This is functionally equivalent to the following code:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestGet</ja>(<js>"/user/login"</js>)
+ <jk>public void</jk> doGet(RestRequest <jv>req</jv>, RestResponse <jv>res</jv>) {
+ RequestFormParams <jv>form</jv> = <jv>req</jv>.getFormParams();
+ String <jv>username</jv> = <jv>form</jv>.get(<js>"username"</js>).orElse(<jk>null</jk>);
+ String <jv>password</jv> = <jv>form</jv>.get(<js>"password"</js>).orElse(<jk>null</jk>);
+ <jk>if</jk> (<jsm>isValid</jsm>(<jv>username</jv>, <jv>password</jv>) {
+ <jv>res</jv>.setStatus(200);
+ <jv>res</jv>.setHeader(<js>"My-Message"</js>, <js>"Welcome "</js> + <jv>username</jv> + <js>"!"</js>);
+ } else {
+ <jv>res</jv>.setStatus(401);
+ }
+ }
+</p>
+<p>
+ The default registered part marshallers, {@link org.apache.juneau.oapi.OpenApiSerializer} and {@link org.apache.juneau.oapi.OpenApiParser}, are used to
+ marshall POJOs using schemas defined via the {@link org.apache.juneau.http.annotation.Schema @Schema} annotation.
+</p>
+<ul class='javatree'>
+</ul>
+<p>
+ For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. <js>"1,2,3|4,5,6|7,8,9"</js>) can be converted to a 2-dimensional array of <c>Longs</c>:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestGet</ja>(<js>"/testQuery1"</js>)
+ <jk>public void</jk> testQuery1(
+ <ja>@Query</ja>(<js>"queryParamName"</js>)
+ <ja>@Schema</ja>(
+ collectionFormat=<js>"pipes"</js>,
+ items=<ja>@Items</ja>(
+ collectionFormat=<js>"csv"</js>,
+ type=<js>"integer"</js>,
+ format=<js>"int64"</js>,
+ minimum=<js>"0"</js>,
+ maximum=<js>"100"</js>
+ minLength=1,
+ maxLength=10
+ ),
+ minLength=1,
+ maxLength=10
+ )
+ Long[][] <jv>queryParameter</jv>
+ ) {...}
+
+ <jc>// Same but using condensed notation.</jc>
+ <ja>@RestGet</ja>(<js>"/testQuery2"</js>)
+ <jk>public void</jk> testQuery2(
+ <ja>@Query</ja>(<js>"queryParamName"</js>)
+ <ja>@Schema</ja>(
+ cf=<js>"pipes"</js>, minl=1, maxl=10,
+ i=<ja>@Items</ja>(cf=<js>"csv"</js>, t=<js>"integer"</js>, f=<js>"int64"</js>, min=<js>"0"</js>, max=<js>"100"</js>, minl=1, maxl=10)
+ )
+ Long[][] <jv>queryParameter</jv>
+ ) {...}
+</p>
+<p>
+ Schema-based marshalling works for both request and response parts.
+ Input will be converted based on the types and formats defined in the schema definition.
+ Input validations such as <c>minLength/maxLength</c> that don't match the input will result in automatic <c>400 Bad Request</c> responses.
+</p>
+
+<p>
+ The part and schema annotations are also used for supplying swagger information about the HTTP part.
+ This information is used to populate the auto-generated Swagger documentation and UI.
+</p>
+<h5 class='figure'>Example:</h5>
+<p class='bpcode w800'>
+ <ja>@Query</ja>(<js>"name"</js>)
+ <ja>@Schema</ja>(
+ description=<js>"Pet name"</js>,
+ required=<jk>true</jk>
+ )
+</p>
+<p>
+ {@doc RestSvlVariables SVL Variables} (e.g. "$L{my.localized.variable}") are supported on annotation fields as well.
+ Among other things, this allow for annotation values to be defined externally and the ability to produce localized swagger documents
+ based on the <c>Accept-Language</c> on a request.
+</p>
+<h5 class='figure'>Example:</h5>
+<p class='bpcode w800'>
+ <ja>@Schema</ja>(
+ description=<js>"$L{PetNameDescription}"</js>
+ )
+</p>
+<p>
+ The {@link org.apache.juneau.http.annotation.Body @Body} annotation can also be used to parse HTTP request bodies using OpenAPI schemas
when the body content type matches the {@link org.apache.juneau.oapi.OpenApiParser} parser via the header <c>Content-Type: text/openapi</c>.
</p>
<p>
@@ -15992,60 +16096,45 @@
For example, instead of <c>Longs</c> in the example above, we could also define a 2-dimensional array of POJOs convertible from <c>Longs</c>:
</p>
<p class='bpcode w800'>
- <ja>@RestPost</ja>(<js>"/2dLongArray"</js>)
- <jk>public void</jk> testBody(<ja>@Body</ja>(...) MyPojo[][] <jv>body</jv>) {...}
+ <jc>// Body is a 2-dimensional array of POJOs convertible from Longs:</jc>
+ <ja>@RestPost</ja>(<js>"/example1"</js>)
+ <jk>public void</jk> testBody(<ja>@Body</ja>(...) MyPojo1[][] <jv>body</jv>) {...}
- <jc>// POJO convertible from a Long.</jc>
- <jk>public class</jk> MyPojo {
- <jk>public</jk> MyPojo(Long <jv>input</jv>) {...}
+ <jk>public class</jk> MyPojo1 {
+ <jk>public</jk> MyPojo1(Long <jv>input</jv>) {...}
}
</p>
-<p>
- Or even POJOs that take in arrays of <c>Longs[]</c>:
-</p>
<p class='bpcode w800'>
- <ja>@RestPost</ja>(<js>"/2dLongArray"</js>)
- <jk>public void</jk> testBody(<ja>@Body</ja>(...) MyPojo[] <jv>body</jv>) {...}
+ <jc>// Body is a POJO that takes in a Long array:</jc>
+ <ja>@RestPost</ja>(<js>"/example2"</js>)
+ <jk>public void</jk> testBody(<ja>@Body</ja>(...) MyPojo2[] <jv>body</jv>) {...}
- <jc>// POJO convertible from a Long[].</jc>
- <jk>public class</jk> MyPojo {
- <jk>public</jk> MyPojo(Long[] <jv>input</jv>) {...}
+ <jk>public class</jk> MyPojo2 {
+ <jk>public</jk> MyPojo2(Long[] <jv>input</jv>) {...}
}
</p>
-<p>
- Or even POJOs that take in the whole 2-dimensional array:
-</p>
<p class='bpcode w800'>
- <ja>@RestPost</ja>(<js>"/2dLongArray"</js>)
- <jk>public void</jk> testBody(<ja>@Body</ja>(...) MyPojo <jv>body</jv>) {...}
+ <jc>// Body is a POJO that takes in the whole 2-dimensional array:</jc>
+ <ja>@RestPost</ja>(<js>"/example3"</js>)
+ <jk>public void</jk> testBody(<ja>@Body</ja>(...) MyPojo3 <jv>body</jv>) {...}
- <jc>// POJO convertible from a Long[][].</jc>
- <jk>public class</jk> MyPojo {
- <jk>public</jk> MyPojo(Long[][] <jv>input</jv>) {...}
+ <jk>public class</jk> MyPojo3 {
+ <jk>public</jk> MyPojo3(Long[][] <jv>input</jv>) {...}
}
</p>
<p>
As you can see, the complexity of possible input types expands significantly.
For more information about valid parameter types, see {@doc OpenApiParsers OpenAPI Parsers}
</p>
-</div><!-- END: 6.4.3 - juneau-rest-server.HttpParts.Body -->
+</div><!-- END: 6.4.2 - juneau-rest-server.HttpParts.HttpPartAnnotations -->
<!-- ==================================================================================================== -->
-<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.HttpParts.RequestBeans' id='juneau-rest-server.HttpParts.RequestBeans'>6.4.4 - @Request beans</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></h4>
-<div class='topic'><!-- START: 6.4.4 - juneau-rest-server.HttpParts.RequestBeans -->
-<p>
- The {@link org.apache.juneau.http.annotation.Request @Request} annotation can be applied to a parameter interface type of a <ja>@RestOp</ja>-annotated method
- to identify it as an interface for retrieving HTTP parts through a bean-like interface.
-</p>
-<ul class='javatree'>
- <li class='ja'>{@link org.apache.juneau.http.annotation.Request}
- <ul>
- <li class='jf'>{@link org.apache.juneau.http.annotation.Request#parser() parser} - Override the part parser.
- </ul>
-</ul>
+<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.HttpParts.RequestBeans' id='juneau-rest-server.HttpParts.RequestBeans'>6.4.3 - @Request Beans</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></h4>
+<div class='topic'><!-- START: 6.4.3 - juneau-rest-server.HttpParts.RequestBeans -->
<p>
- It's used in combination with the following annotation to define proxy interfaces against HTTP requests:
+ The {@link org.apache.juneau.http.annotation.Request @Request} annotation can used to define proxy interfaces against
+ HTTP requests in combination with the following annotations used on methods:
</p>
<ul class='javatreec'>
<li class='ja'>{@link org.apache.juneau.http.annotation.Header}
@@ -16053,17 +16142,18 @@
<li class='ja'>{@link org.apache.juneau.http.annotation.FormData}
<li class='ja'>{@link org.apache.juneau.http.annotation.Path}
<li class='ja'>{@link org.apache.juneau.http.annotation.Body}
+ <li class='ja'>{@link org.apache.juneau.http.annotation.Schema}
</ul>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
<ja>@RestPut</ja>(<js>"/pets/{petId}"</js>)
- <jk>public void</jk> putPet(UpdatePet <jv>updatePet</jv>) {...}
+ <jk>public void</jk> addPet(UpdatePetBean <jv>updatePet</jv>) {...}
<ja>@Request</ja>
- <jk>public interface</jk> UpdatePet {
+ <jk>public interface</jk> UpdatePetBean {
- <ja>@Path</ja>
+ <ja>@Path</ja> <jc>// {petId} inferred.</jc>
<jk>int</jk> getPetId();
<ja>@Query</ja>(<js>"verbose"</js>)
@@ -16081,11 +16171,11 @@
</p>
<p class='bpcode w800'>
<ja>@RestPut</ja>(<js>"/pets/{petId}"</js>)
- <jk>public void</jk> putPet(
+ <jk>public void</jk> addPet(
<ja>@Path</ja>(<js>"petId"</js>) <jk>int</jk> <jv>petId</jv>,
<ja>@Query</ja>(<js>"verbose"</js>) <jk>boolean</jk> <jv>debug</jv>,
<ja>@Header</ja>(<js>"*"</js>) Map<String,Object> <jv>allHeaders</jv>,
- <ja>@Body</ja> Pet <jv>pet</jv>
+ <ja>@Body</ja> UpdatePetBean <jv>pet</jv>
)
{...}
</p>
@@ -16094,13 +16184,15 @@
Schema-based serialization and parsing is used just as if used as individual parameter types.
Annotations used are the exact same used on REST parameters and have all the
same feature support including automatic Swagger validation and documentation.
+ Part names can either be explicitly specified or automatically inferred from the getter names.
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
<ja>@Request</ja>
- <jk>public interface</jk> Request {
+ <jk>public interface</jk> MyRequest {
- <jc>// Schema-based query parameter: Pipe-delimited lists of comma-delimited lists of integers.</jc>
+ <jc>// Schema-based query parameter "pipedCdlInts":
+ // Pipe-delimited list of comma-delimited lists of integers.</jc>
<ja>@Query</ja>
<ja>@Schema</ja>(
collectionFormat=<js>"pipes"</js>
@@ -16123,186 +16215,99 @@
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
<ja>@RestPut</ja>(<js>"/pets/{petId}"</js>)
- <jk>public void</jk> putPet(<ja>@Request</ja> UpdatePet <jv>updatePet</jv>) {...}
+ <jk>public void</jk> addPet(<ja>@Request</ja> UpdatePetBean <jv>updatePet</jv>) {...}
<ja>@Request</ja>
- <jk>public interface</jk> UpdatePet {...}
+ <jk>public interface</jk> UpdatePetBean {...}
</p>
-</div><!-- END: 6.4.4 - juneau-rest-server.HttpParts.RequestBeans -->
+
+<p>
+</div><!-- END: 6.4.3 - juneau-rest-server.HttpParts.RequestBeans -->
<!-- ==================================================================================================== -->
-<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.HttpParts.ReponseHeader_ResponseStatus' id='juneau-rest-server.HttpParts.ReponseHeader_ResponseStatus'>6.4.5 - @Response / @ResponseHeader / @ResponseCode</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></h4>
-<div class='topic'><!-- START: 6.4.5 - juneau-rest-server.HttpParts.ReponseHeader_ResponseStatus -->
+<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.HttpParts.ResponseBeans' id='juneau-rest-server.HttpParts.ResponseBeans'>6.4.4 - @Response Beans</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></h4>
+<div class='topic'><!-- START: 6.4.4 - juneau-rest-server.HttpParts.ResponseBeans -->
<p>
- The {@link org.apache.juneau.http.annotation.Response @Response} / {@link org.apache.juneau.http.annotation.ResponseHeader @ResponseHeader} / {@link org.apache.juneau.http.annotation.ResponseCode @ResponseCode} annotations
- allow you to define method parameters for setting HTTP response parts:
+ The {@link org.apache.juneau.http.annotation.Response} annotation can be used to define beans that return HTTP response
+ parts via annotations and methods. They are used in combination with the following annotations:
</p>
+<ul class='javatreec'>
+ <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseCode}
+ <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseHeader}
+ <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseBody}
+ <li class='ja'>{@link org.apache.juneau.http.annotation.Schema}
+</ul>
-<ul class='javatree'>
- <li class='ja'>{@link org.apache.juneau.http.annotation.Response}
- <ul class='javatreec'>
- <li class='jm'>{@link org.apache.juneau.http.annotation.Response#examples() examples()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Response#headers() headers()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Response#on() on()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Response#onClass() onClass()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Response#parser() parser()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Response#schema() schema()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.Response#serializer() serializer()}
- </ul>
- <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseHeader}
- <ul class='javatreec'>
- <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseHeader#name() name()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseHeader#on() on()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseHeader#onClass() onClass()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseHeader#schema() schema()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseHeader#serializer() serializer()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseHeader#value() value()}
- </ul>
- <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseCode}
- <ul class='javatreec'>
- <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseCode#on() on()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseCode#onClass() onClass()}
- <li class='jm'>{@link org.apache.juneau.http.annotation.ResponseCode#value() value()}
- </ul>
-</ul>
<p>
- Response part parameters are defined using a settable {@link org.apache.juneau.Value} object.
+ Response beans can either be returned or thrown from {@link org.apache.juneau.rest.annotation.RestOp @RestOp}-annotated methods.
</p>
+<ul>
+ <li class='note'>
+ As a general convention, response beans with return codes <c><400</c> should be defined as regular classes and
+ <c>>=400</c> should be defined as exceptions.
+</ul>
<p>
- The {@link org.apache.juneau.http.annotation.Response @Response} annotation can be used to set
- the response body as a settable parameter:
+ The following example shows the <ja>@Response</ja> annotation used to define an exception for an invalid login attempt:
</p>
<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/testResponseBody"</js>)
- <jk>public void</jk> testResponseBody(
- <ja>@Response</ja>(
- serializer=OpenApiSerialier.<jk>class</jk>
- )
- <ja>@Schema</ja>(
- items=<ja>@Items</ja>(
- collectionFormat=<js>"pipes"</js>,
- items=<ja>@SubItems</ja>(
- collectionFormat=<js>"csv"</js>,
- type=<js>"integer"</js>,
- format=<js>"int64"</js>,
- minimum=<js>"0"</js>,
- maximum=<js>"100"</js>
- minLength=1,
- maxLength=10
- )
- ),
- minLength=1,
- maxLength=10
- )
- Value<Long[][]> <jv>responseBody</jv>
- ) {...}
-</p>
-<p>
- The {@link org.apache.juneau.http.annotation.ResponseHeader} annotation can be used to set
- response headers:
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/testResponseHeader"</js>)
- <jk>public void</jk> testResponseHeader(
- <ja>@ResponseHeader</ja>(<js>"My-Header"</js>)
- <ja>@Schema</ja>(
- collectionFormat=<js>"pipes"</js>,
- items=<ja>@SubItems</ja>(
- collectionFormat=<js>"csv"</js>,
- type=<js>"integer"</js>,
- format=<js>"int64"</js>,
- minimum=<js>"0"</js>,
- maximum=<js>"100"</js>
- minLength=1,
- maxLength=10
- ),
- minLength=1,
- maxLength=10
- )
- Value<Long[][]> <jv>header</jv>
- ) {
- <jv>header</jv>.set(<jk>new</jk> Long[][]{...});
- }
-</p>
-<p>
- The {@link org.apache.juneau.http.annotation.ResponseCode @ResponseCode} annotation annotation can be used to
- set the HTTP response code:
-</p>
-<h5 class='figure'>Examples:</h5>
-<p class='bpcode w800'>
- <jc>// Defined on parameter.</jc>
- <ja>@RestGet</ja>(<js>"/user/login"</js>)
- <jk>public void</jk> login(
- <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
- <ja>@FormData</ja>(<js>"password"</js>) String <jv>password</jv>,
- <ja>@ResponseCode</ja> Value<Integer> <jv>status</jv>
- )
- {
- <jk>if</jk> (! <jsm>isValid</jsm>(<jv>username</jv>, <jv>password</jv>))
- <jv>status</jv>.set(401);
+ <jc>// Our annotated normal response.</jc>
+ <ja>@Response</ja>
+ <ja>@ResponseCode</ja>(200)
+ <ja>@Schema</ja>(
+ description=<js>"User was good."</js> <jc>// Description show in Swagger</jc>
+ )
+ <jk>public class</jk> ValidLogin {
+ <jk>public</jk> ValidLogin() {
+ ...
+ }
+
+ <jc>// Response bean converted to output based on Accept header.</jc>
+ <ja>@ResponseBody</ja>
+ <jk>public</jk> WelcomeMessageBean getBody() {
+ <jk>return new </jk> WelcomeMessageBean();
+ }
}
</p>
-</div><!-- END: 6.4.5 - juneau-rest-server.HttpParts.ReponseHeader_ResponseStatus -->
-
-<!-- ==================================================================================================== -->
-
-<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.HttpParts.ResponseBeans' id='juneau-rest-server.HttpParts.ResponseBeans'>6.4.6 - @Response beans</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></h4>
-<div class='topic'><!-- START: 6.4.6 - juneau-rest-server.HttpParts.ResponseBeans -->
-<p>
- The {@link org.apache.juneau.http.annotation.Response} annotation can also be used in the following locations:
-</p>
-<ul>
- <li>Argument/exception/return types of <ja>@RestOp</ja>-annotated methods.
- <li><ja>@RestOp</ja>-annotated methods themselves.
-</ul>
-
-<p>
- When the <ja>@Response</ja> annotation is applied to classes, the following annotations can be used on
- public non-static methods of the class to identify parts of a response:
-</p>
-<ul class='javatree'>
- <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseStatus}
- <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseHeader}
- <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseBody}
-</ul>
-
-<h5 class='topic'>@Resource on exception classes</h5>
-<p>
- When applied to an exception class, this annotation defines Swagger schema and information on non-200 return types.
-</p>
-<p>
- The following example shows the <ja>@Response</ja> annotation used to define an exception for an invalid login attempt:
-</p>
<p class='bpcode w800'>
<jc>// Our annotated exception.</jc>
- <ja>@Response</ja>(
- code=401,
+ <ja>@Response</ja>
+ <ja>@ResponseCode</ja>(401)
+ <ja>@Schema</ja>(
description=<js>"Invalid username or password provided"</js> <jc>// Description show in Swagger</jc>
)
<jk>public class</jk> InvalidLogin <jk>extends</jk> Exception {
<jk>public</jk> InvalidLogin() {
<jk>super</jk>(<js>"Invalid username or password."</js>); <jc>// Message sent in response</jc>
}
+
+ <ja>@ResponseHeader</ja>(<js>"My-Message"</js>)
+ <jk>public</jk> String getMyMessage() {
+ <jk>return</jk> <js>"Nope!"</js>;
+ }
}
-
+</p>
+<p class='bpcode w800'>
<jc>// Our REST method that throws an annotated exception.</jc>
<ja>@RestGet</ja>(<js>"/user/login"</js>)
- <jk>public</jk> Ok login(
+ <jk>public</jk> ValidLogin login(
<ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
<ja>@FormData</ja>(<js>"password"</js>) String <jv>password</jv>
) <jk>throws</jk> InvalidLogin
{
- <jsm>checkCredentials</jsm>(<jv>username</jv>, <jv>password</jv>);
- <jk>return new</jk> Ok();
+ <jk>if</jk> (<jsm>isValid</jsm>(<jv>username</jv>, <jv>password</jv>)) {
+ <jk>return new</jk> ValidLogin();
+ }
+ <jk>throw new</jk> InvalidLogin();
}
</p>
<p>
- Custom exceptions can also extend from one of the predefined HTTP exceptions such as the {@del org.apache.juneau.http.exception.Unauthorized} exception:
+ Custom exceptions can also extend from one of the predefined HTTP exceptions such as the {@link org.apache.juneau.http.response.Unauthorized} exception:
</p>
<p class='bpcode w800'>
<jc>// Our annotated exception.</jc>
- <ja>@Response</ja>(
+ <ja>@Response</ja>
+ <ja>@Schema</ja>(
description=<js>"Invalid username or password provided"</js> <jc>// Overridden from parent class</jc>
)
<jk>public class</jk> InvalidLogin <jk>extends</jk> Unauthorized {
@@ -16312,414 +16317,30 @@
}
<jc>// Parent predefined exception class.</jc>
- <ja>@Response</ja>(
- code=401,
+ <ja>@Response</ja>
+ <ja>@ResponseCode(401)</ja>
+ <ja>@Schema</ja>(
description=<js>"Unauthorized"</js>
)
<jk>public class</jk> Unauthorized <jk>extends</jk> RestException {...}
</p>
-
-<h5 class='topic'>@Resource on return type classes</h5>
-<p>
- When applied type classes returned by a Java method, this annotation defines schema and Swagger information on the body of responses.
-</p>
-<p>
- In the example above, we're using the <c>Ok</c> class which is defined like so:
-</p>
-<p class='bpcode w800'>
- <ja>@Response</ja>(
- code=200,
- description=<js>"OK"</js>
- )
- <jk>public class</jk> Ok {
-
- <ja>@ResponseBody</ja>
- <jk>public</jk> String toString() {
- <jk>return</jk> <js>"OK"</js>;
- }
- }
-</p>
-<p>
- Another example showing how a redirect can be defined:
-</p>
-<p class='bpcode w800'>
- <ja>@Response</ja>(
- code=307,
- description=<js>"Temporary Redirect"</js>
- )
- <jk>public class</jk> Redirect {
- <jk>private final</jk> URI <jf>location</jf>;
-
- <jk>public</jk> Redirect(URI <jv>location</jv>) {
- <jk>this</jk>.<jf>location</jf> = <jv>location</jv>;
- }
-
- <ja>@ResponseHeader</ja>(
- name=<js>"Location"</js>,
- format=<js>"uri"</js>
- )
- <jk>public</jk> URI getLocation() {
- <jk>return</jk> <jf>location</jf>;
- }
-
- <ja>@ResponseBody</ja>
- <jk>public</jk> String toString() {
- <jk>return</jk> <js>"Temporary Redirect"</js>;
- }
- }
-</p>
-<p class='bpcode w800'>
- <jc>// Usage</jc>
- <ja>@RestPost</ja>
- <jk>public</jk> Redirect postPet(Pet pet) {
- <jc>// Redirect to servlet root</jc>
- <jk>return new</jk> Redirect(URI.<jsm>create</jsm>(<js>"servlet:/"</js>));
- }
-</p>
-
-<h5 class='topic'>@Resource on @RestOp-annotated methods</h5>
-<p>
- The <ja>@Response</ja> annotation can also be applied to the Java method itself which is effectively
- the same as applying it to the return type (albeit for this method only).
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/user/login"</js>)
- <ja>@Response</ja>(code=200, description=<js>"OK"</js>)
- <jk>public</jk> Ok login(
- <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
- <ja>@FormData</ja>(<js>"password"</js>) String <jv>password</jv>
- ) <jk>throws</jk> InvalidLogin
- {
- <jsm>checkCredentials</jsm>(<jv>username</jv>, <jv>password</jv>);
- <jk>return new</jk> Ok();
- }
-</p>
-<p>
- The <ja>@Response</ja> annotation can be simultaneously on both the Java method and return type.
- When used in both locations, the annotation values are combined, but values defined on the
- method return annotation take precedence over the values defined on the type.
-</p>
-
-<h5 class='topic'>@Resource on @RestOp-annotated method parameters</h5>
-<p>
- The <ja>@Response</ja> annotation can also be applied to the Java method parameters when the parameter type
- is {@link org.apache.juneau.Value} (a placeholder for objects).
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/user/login"</js>)
- <jk>public void</jk> login(
- <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
- <ja>@FormData</ja>(<js>"password"</js>) String <jv>password,/,
- <ja>@Response</ja>(code=200, description=<js>"Login succeeded"</js>) Value<String> <jv>body</jv>
- ) <jk>throws</jk> InvalidLogin
- {
- <jsm>checkCredentials</jsm>(<jv>username</jv>, <jv>password</jv>);
- <jv>body</jv>.set(<js>"OK"</js>);
- }
-</p>
-<p>
- <ja>@Response</ja>-annotated types can also be used as value parameters:
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(...)
- <jk>public void</jk> login(
- ...
- <ja>@Response</ja> Value<Ok> <jv>res</jv>
- ) <jk>throws</jk> InvalidLogin
- {
- ...
- <jv>res</jv>.set(<jk>new</jk> Ok());
- }
-</p>
-<p>
- In the above example, the <ja>@Response</ja> annotation is optional since it is inferred from the class
- that it's a <ja>@Response</ja> bean.
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/user/login"</js>)
- <jk>public void</jk> login(
- ...
- Value<Ok> <jv>res</jv> <jc>// @Response annotation not needed.</jc>
- ) <jk>throws</jk> InvalidLogin
- {
- ...
- <jv>res</jv>.set(<jk>new</jk> Ok());
- }
-</p>
-
-<h5 class='topic'>@ResponseStatus on methods of @Response-annotated types</h5>
-<p>
- The {@link org.apache.juneau.http.annotation.ResponseStatus @ResponseStatus} annotation can be used on
- the method of a <ja>@Response</ja>-annotated class to identify HTTP response
- statuses other than <c>200</c> (the default).
-</p>
-
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <ja>@Response</ja>
- <jk>public class</jk> AddPetSuccess {
-
- <ja>@ResponseStatus</ja>
- <jk>public int</jk> getStatus() {
- <jk>return</jk> 201;
- }
-
- <ja>@Override</ja>
- <jk>public</jk> String toString() {
- <jk>return</jk> <js>"Pet was successfully added"</js>;
- }
- }
-</p>
-
-
-<h5 class='topic'>@ResponseHeader on methods of @Response-annotated types</h5>
-<p>
- The {@link org.apache.juneau.http.annotation.ResponseHeader @ResponseHeader} annotation can be used on
- the method of a <ja>@Response</ja>-annotated class to identify a header
- to add to the response.
-</p>
-
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <ja>@Response</ja>
- <jk>public class</jk> AddPetSuccess {
-
- <ja>@ResponseHeader</ja>(
- name=<js>"X-PetId"</js>,
- type=<js>"integer"</js>,
- format=<js>"int32"</js>,
- description=<js>"ID of added pet."</js>,
- example=<js>"123"</js>
- )
- <jk>public int</jk> getPetId() {...}
- }
-</p>
-
-<h5 class='topic'>@ResponseBody on methods of @Response-annotated types</h5>
-<p>
- The {@link org.apache.juneau.http.annotation.ResponseBody @ResponseBody} annotation can be used on
- the method of a <ja>@Response</ja>-annotated class to identify a POJO
- as the body of the HTTP response.
-</p>
-
-<h5 class='figure'>Example:</h5>
-<p class='bpcode w800'>
- <ja>@Response</ja>
- <jk>public class</jk> AddPetSuccess {
-
- <ja>@ResponseBody</ja>
- <jk>public</jk> Pet getPet() {...}
- }
-</p>
-
-<p>
- If a <ja>@Response</ja> class does not have a <ja>@ResponseBody</ja>-annotated method, then the response
- object itself is serialized in the response (typically using <c>toString()</c>).
-</p>
-
-<h5 class='topic'>Notes about OpenAPI part serialization</h5>
-<p>
- By default, POJOs representing the body of the request are serialized using the Juneau serializer
- matching the requesting <c>Accept</c> header.
- The {@link org.apache.juneau.oapi.OpenApiSerializer} class can be used to serialize response bodies using OpenAPI rules.
-</p>
-<p>
- The following examples show part-schema-based serialization of response bodies:
-</p>
-<p class='bpcode w800'>
- <ja>@Rest</ja>
- <jk>public class</jk> ExampleResource {
-
- <jc>// Example 1 - String[] should be serialized using part serializer.</jc>
- <ja>@Response</ja>(
- serializers=OpenApiSerializer.<jk>class</jk>,
- defaultAccept=<js>"text/openapi"</js>
- )
- <ja>@RestGet</ja>
- <jk>public</jk> String[] example1() {
- <jk>return new</jk> String[]{<js>"foo"</js>,<js>"bar"</js>};
- }
-
- <jc>// Example 2 - Same as above. Annotation on parameter.</jc>
- <ja>@RestGet</ja>
- <jk>public void</jk> example2(
- <ja>@Response</ja>(
- serializers=OpenApiSerializer.<jk>class</jk>,
- defaultAccept=<js>"text/openapi"</js>
- )
- Value<String[]> <jv>body</jv>
- )
- {
- <jv>body</jv>.set(<jk>new</jk> String[]{<js>"foo"</js>,<js>"bar"</js>});
- }
- }
-</p>
-<p>
- The <c><ja>@Response</ja>(schema)</c> annotation can be used to define the format of the output using OpenAPI-based rules.
-</p>
-<p class='bpcode w800'>
- <ja>@Rest</ja>
- <jk>public class</jk> ExampleResource {
-
- <ja>@Response</ja>(
- serializers=OpenApiSerializer.<jk>class</jk>,
- defaultAccept=<js>"text/openapi"</js>,
- schema=<ja>@Schema</ja>(collectionFormat=<js>"pipes"</js>)
- )
- <ja>@RestGet</ja>
- <jk>public</jk> String[] example1() {
- <jk>return new</jk> String[]{<js>"foo"</js>,<js>"bar"</js>};
- }
- }
-</p>
-
-<h5 class='topic'>Swagger documentation</h5>
-<p>
- The attributes on this annotation are also used to populate the generated Swagger for the method.
- For example, in the case of the <c>InvalidLogin</c> example above, the following Swagger is generated:
-</p>
-<p class='bpcode w800'>
- <jok>'/user/login'</jok>: {
- <jok>get</jok>: {
- <jok>responses</jok>: {
- <jok>401</jok>: {
- <jok>description</jok>: <jov>'Invalid username or password provided'</jov>
- }
- }
- }
- }
-</p>
-
-<h5 class='topic'>Automatic HTTP status</h5>
-<p>
- When the {@link org.apache.juneau.http.annotation.ResponseCode#value() @Response(value)} value is specified,
- the HTTP status is automatically set to that value on the response regardless of how it's used.
-</p>
-<p>
- The following two examples are equivalent:
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/ok"</js>)
- <jk>public void</jk> sendContinue(
- <ja>@ResponseCode</ja>(code=100) Value<String> <jv>body</jv>
- )
- {
- <jv>body</jv>.set(<js>"OK"</js>);
- }
-</p>
-<p class='bpcode w800'>
- <ja>@RestGet</ja>(<js>"/ok"</js>)
- <jk>public void</jk> sendContinue(RestResponse <jv>res</jv>) {
- <jv>res</jv>.setStatus(100);
- <jv>res</jv>.setOutput(<js>"OK"</js>);
- }
-</p>
-
-<ul class='seealso'>
- <li class='link'>{@doc RestOpenApiSchemaPartSerializing}
-</ul>
-
-<p>
- The {@link org.apache.juneau.http.annotation.ResponseHeader @ResponseHeader} annotation can be applied to <ja>@RestOp</ja>-annotated parameters to denote them as an HTTP response headers.
-</p>
-<ul class='javatree'>
- <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseHeader}
- <ul>
- <li class='jf'>{@link org.apache.juneau.http.annotation.ResponseHeader#name() name}
- <li class='jf'>{@link org.apache.juneau.http.annotation.ResponseHeader#on() on}
- <li class='jf'>{@link org.apache.juneau.http.annotation.ResponseHeader#onClass() onClass}
- <li class='jf'>{@link org.apache.juneau.http.annotation.ResponseHeader#serializer() serializer}
- <li class='jf'>{@link org.apache.juneau.http.annotation.ResponseHeader#value() value}
- </ul>
-</ul>
-<p>
- This annotation can only be applied to parameters of type {@link org.apache.juneau.Value}.
-</p>
-<p>
- The following examples show 3 different ways of accomplishing the same task of setting an HTTP header
- on a response:
-</p>
-<p class='bpcode w800'>
- <jc>// Example #1 - Setting header directly on RestResponse object.</jc>
- <ja>@RestGet</ja>(...)
- <jk>public void</jk> login(RestResponse res) {
- res.setHeader(<js>"X-Rate-Limit"</js>, 1000);
- ...
- }
-
- <jc>// Example #2 - Use on parameter.</jc>
- <ja>@RestGet</ja>(...)
- <jk>public void</jk> login(
- <ja>@ResponseHeader</ja>(
- name=<js>"X-Rate-Limit"</js>,
- type=<js>"integer"</js>,
- format=<js>"int32"</js>,
- description=<js>"Calls per hour allowed by the user."</js>,
- example=<js>"123"</js>
- )
- Value<Integer> <jv>rateLimit</jv>
- )
- {
- <jv>rateLimit</jv>.set(1000);
- ...
- }
-
- <jc>// Example #3 - Use on type.</jc>
- <ja>@RestGet</ja>(...)
- <jk>public void</jk> login(Value<RateLimit> <jv>rateLimit</jv>) {
- <jv>rateLimit</jv>.set(<jk>new</jk> RateLimit());
- ...
- }
-
- <ja>@ResponseHeader</ja>(
- name=<js>"X-Rate-Limit"</js>,
- type=<js>"integer"</js>,
- format=<js>"int32"</js>,
- description=<js>"Calls per hour allowed by the user."</js>,
- example=<js>"123"</js>
- )
- <jk>public class</jk> RateLimit {
- <jc>// OpenApiSerializer knows to look for this method based on format/type.</jc>
- <jk>public</jk> Integer toInteger() {
- <jk>return</jk> 1000;
- }
- }
-</p>
-
-<p>
- The {@link org.apache.juneau.http.annotation.ResponseStatus @ResponseStatus} annotation annotation can be applied to <ja>@RestOp</ja>-annotated parameters to denote them as an HTTP response status codes.
-</p>
-<ul class='javatree'>
- <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseStatus}
-</ul>
-<p>
- This can only be applied to parameters of the {@link org.apache.juneau.Value} class with an {@link java.lang.Integer} type.
-</p>
-
-<h5 class='figure'>Examples:</h5>
-<p class='bpcode w800'>
- <jc>// Defined on parameter.</jc>
- <ja>@RestGet</ja>(<js>"/user/login"</js>)
- <jk>public void</jk> login(
- <ja>@FormData</ja>(<js>"username"</js>) String <jv>username</jv>,
- <ja>@FormData</ja>(<js>"password"</js>) String <jv>password</jv>,
- <ja>@ResponseStatus</ja> Value<Integer> <jv>status</jv>
- )
- {
- <jk>if</jk> (! <jsm>isValid</jsm>(<jv>username</jv>, <jv>password</jv>))
- <jv>status</jv>.set(401);
- }
-</p>
-</div><!-- END: 6.4.6 - juneau-rest-server.HttpParts.ResponseBeans -->
+</div><!-- END: 6.4.4 - juneau-rest-server.HttpParts.ResponseBeans -->
<!-- ==================================================================================================== -->
-<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.HttpParts.RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams' id='juneau-rest-server.HttpParts.RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams'>6.4.7 - RequestHeaders / RequestQueryParams / RequestFormParams / RequestPathParams</a><span class='update'>created: <b>9.0.0</b></span></h4>
-<div class='topic'><!-- START: 6.4.7 - juneau-rest-server.HttpParts.RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams -->
+<h5 class='topic' onclick='toggle(this)'><a href='#juneau-rest-server.HttpParts.HttpPartApis' id='juneau-rest-server.HttpParts.HttpPartApis'>6.4.5 - HTTP Part APIs</a><span class='update'>created: <b>9.0.0</b></span></h4>
+<div class='topic'><!-- START: 6.4.5 - juneau-rest-server.HttpParts.HttpPartApis -->
<p>
- TODO
+ Request HTTP parts can also be retrieved programmatically through the following classes that
+ can be passed in as parameters or access through {@link org.apache.juneau.rest.RestRequest} bean:
</p>
-</div><!-- END: 6.4.7 - juneau-rest-server.HttpParts.RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams -->
+<ul class='javatreec'>
+ <li class='jc'>{@link org.apache.juneau.rest.RequestHeaders}
+ <li class='jc'>{@link org.apache.juneau.rest.RequestQueryParams}
+ <li class='jc'>{@link org.apache.juneau.rest.RequestFormParams}
+ <li class='jc'>{@link org.apache.juneau.rest.RequestPathParams}
+</ul>
+</div><!-- END: 6.4.5 - juneau-rest-server.HttpParts.HttpPartApis -->
</div><!-- END: 6.4 - juneau-rest-server.HttpParts -->
<!-- ==================================================================================================== -->
diff --git a/juneau-doc/src/main/javadoc/resources/docs.txt b/juneau-doc/src/main/javadoc/resources/docs.txt
index 46c5fa0..008a92a 100644
--- a/juneau-doc/src/main/javadoc/resources/docs.txt
+++ b/juneau-doc/src/main/javadoc/resources/docs.txt
@@ -1,3 +1,4 @@
+AdditionalInformation = #juneau-rest-server.RestOpAnnotatedMethods.AdditionalInformation, Overview > juneau-rest-server > @RestOp-Annotated Methods > Additional Information
AutoSwaps = #juneau-marshall.Swaps.AutoSwaps, Overview > juneau-marshall > Swaps > Auto-detected swaps
BasicHtmlDocTemplate = #juneau-marshall.HtmlDetails.BasicHtmlDocTemplate, Overview > juneau-marshall > HTML Details > BasicHtmlDocTemplate
BasicRestInfoProvider = #juneau-rest-server.RestInfoProvider.BasicRestInfoProvider, Overview > juneau-rest-server > RestInfoProvider > BasicRestInfoProvider
@@ -12,7 +13,6 @@ BeanSubTypes = #juneau-marshall.BeanDictionaries.BeanSubTypes, Overview > juneau
BeancAnnotation = #juneau-marshall.JavaBeansSupport.BeancAnnotation, Overview > juneau-marshall > Java Beans Support > @Beanc Annotation
BeanpAnnotation = #juneau-marshall.JavaBeansSupport.BeanpAnnotation, Overview > juneau-marshall > Java Beans Support > @Beanp Annotation
BestPractices = #juneau-marshall.BestPractices, Overview > juneau-marshall > Best Practices
-Body = #juneau-rest-server.HttpParts.Body, Overview > juneau-rest-server > HTTP Parts > @Body and Request Bodies
BypassSerialization = #juneau-marshall.JavaBeansSupport.BypassSerialization, Overview > juneau-marshall > Java Beans Support > Bypass Serialization using Readers and InputStreams
ClosingConfigs = #juneau-config.ClosingConfigs, Overview > juneau-config > Closing Configs
ComplexDataTypes = #juneau-marshall.ComplexDataTypes, Overview > juneau-marshall > Complex Data Types
@@ -103,7 +103,6 @@ GeneralDesign = #Overview.GeneralDesign, Overview > Overview > General Design
Glossaries = #Glossaries, Overview > Glossaries
GlossaryAnnotations = #Glossaries.GlossaryAnnotations, Overview > Glossaries > Annotations
GlossaryLanguageSupport = #Glossaries.GlossaryLanguageSupport, Overview > Glossaries > Language Support
-Header_Path_Query_FormData = #juneau-rest-server.HttpParts.Header_Path_Query_FormData, Overview > juneau-rest-server > HTTP Parts > @Header / @Path / @Query / @FormData
HtmlAnnotation = #juneau-marshall.HtmlDetails.HtmlAnnotation, Overview > juneau-marshall > HTML Details > @Html Annotation
HtmlCustomTemplates = #juneau-marshall.HtmlDetails.HtmlCustomTemplates, Overview > juneau-marshall > HTML Details > Custom Templates
HtmlDetails = #juneau-marshall.HtmlDetails, Overview > juneau-marshall > HTML Details
@@ -113,10 +112,16 @@ HtmlParsers = #juneau-marshall.HtmlDetails.HtmlParsers, Overview > juneau-marsha
HtmlRenderAnnotation = #juneau-marshall.HtmlDetails.HtmlRenderAnnotation, Overview > juneau-marshall > HTML Details > @Html(render) Annotation
HtmlSchema = #juneau-marshall.HtmlDetails.HtmlSchema, Overview > juneau-marshall > HTML Details > HTML-Schema Support
HtmlSerializers = #juneau-marshall.HtmlDetails.HtmlSerializers, Overview > juneau-marshall > HTML Details > HTML Serializers
+HttpPartAnnotations = #juneau-rest-server.HttpParts.HttpPartAnnotations, Overview > juneau-rest-server > HTTP Parts > HTTP Part Annotations
+HttpPartApis = #juneau-rest-server.HttpParts.HttpPartApis, Overview > juneau-rest-server > HTTP Parts > HTTP Part APIs
HttpPartSerializersParsers = #juneau-marshall.HttpPartSerializersParsers, Overview > juneau-marshall > HTTP Part Serializers and Parsers
HttpParts = #juneau-rest-server.HttpParts, Overview > juneau-rest-server > HTTP Parts
+InferredHttpMethodsAndPaths = #juneau-rest-server.RestOpAnnotatedMethods.InferredHttpMethodsAndPaths, Overview > juneau-rest-server > @RestOp-Annotated Methods > Inferred HTTP Methods and Paths
JacksonComparison = #juneau-marshall.JacksonComparison, Overview > juneau-marshall > Comparison with Jackson
JavaBeansSupport = #juneau-marshall.JavaBeansSupport, Overview > juneau-marshall > Java Beans Support
+JavaMethodParameters = #juneau-rest-server.RestOpAnnotatedMethods.JavaMethodParameters, Overview > juneau-rest-server > @RestOp-Annotated Methods > Java Method Parameters
+JavaMethodReturnTypes = #juneau-rest-server.RestOpAnnotatedMethods.JavaMethodReturnTypes, Overview > juneau-rest-server > @RestOp-Annotated Methods > Java Method Return Types
+JavaMethodThrowableTypes = #juneau-rest-server.RestOpAnnotatedMethods.JavaMethodThrowableTypes, Overview > juneau-rest-server > @RestOp-Annotated Methods > Java Method Throwable Types
JaxrsBaseProvider = #juneau-rest-server-jaxrs.JaxrsBaseProvider, Overview > juneau-rest-server-jaxrs > Juneau JAX-RS Provider
JsonAnnotation = #juneau-marshall.JsonDetails.JsonAnnotation, Overview > juneau-marshall > JSON Details > @Json Annotation
JsonDetails = #juneau-marshall.JsonDetails, Overview > juneau-marshall > JSON Details
@@ -126,6 +131,7 @@ JsonSchema = #juneau-marshall.JsonDetails.JsonSchema, Overview > juneau-marshall
JsonSerializers = #juneau-marshall.JsonDetails.JsonSerializers, Overview > juneau-marshall > JSON Details > JSON Serializers
MarshallingUris = #juneau-marshall.MarshallingUris, Overview > juneau-marshall > URIs
Marshalls = #juneau-marshall.Marshalls, Overview > juneau-marshall > Marshalls
+Matchers = #juneau-rest-server.RestOpAnnotatedMethods.Matchers, Overview > juneau-rest-server > @RestOp-Annotated Methods > Matchers
MicroserviceArgs = #juneau-microservice-core.MicroserviceArgs, Overview > juneau-microservice-core > Args
MicroserviceConfig = #juneau-microservice-core.MicroserviceConfig, Overview > juneau-microservice-core > Config
MicroserviceConsoleCommands = #juneau-microservice-core.MicroserviceConsoleCommands, Overview > juneau-microservice-core > Console Commands
@@ -164,7 +170,8 @@ OpenApiSerializers = #juneau-marshall.OpenApiDetails.OpenApiSerializers, Overvie
Overview = #Overview, Overview > Overview
ParentPropertyAnnotation = #juneau-marshall.JavaBeansSupport.ParentPropertyAnnotation, Overview > juneau-marshall > Java Beans Support > @ParentProperty Annotation
ParsingIntoGenericModels = #juneau-marshall.ParsingIntoGenericModels, Overview > juneau-marshall > Parsing into Generic Models
-PartSerializers_PartParsers = #juneau-rest-server.HttpParts.PartSerializers_PartParsers, Overview > juneau-rest-server > HTTP Parts > Part Serializers / Part Parsers
+PartMarshallers = #juneau-rest-server.HttpParts.PartMarshallers, Overview > juneau-rest-server > HTTP Parts > Part Marshallers
+PathPatterns = #juneau-rest-server.RestOpAnnotatedMethods.PathPatterns, Overview > juneau-rest-server > @RestOp-Annotated Methods > Path Patterns
PerMediaTypeSwaps = #juneau-marshall.Swaps.PerMediaTypeSwaps, Overview > juneau-marshall > Swaps > Per-media-type Swaps
PetStoreBuilding = #juneau-petstore.PetStoreBuilding, Overview > juneau-pestore > Building and Running from Command-Line (Using Dockerfiles)
PetStoreInstalling = #juneau-petstore.PetStoreInstalling, Overview > juneau-pestore > Installing in Eclipse
@@ -183,10 +190,8 @@ RdfUriProperties = #juneau-marshall-rdf.RdfDetails.RdfUriProperties, Overview >
ReadOnlyConfigs = #juneau-config.ReadOnlyConfigs, Overview > juneau-config > Read-only Configs
ReadingContinuousStreams = #juneau-marshall.ReadingContinuousStreams, Overview > juneau-marshall > Reading Continuous Streams
Recursion = #juneau-marshall.Recursion, Overview > juneau-marshall > Non-Tree Models and Recursion Detection
-ReponseHeader_ResponseStatus = #juneau-rest-server.HttpParts.ReponseHeader_ResponseStatus, Overview > juneau-rest-server > HTTP Parts > @Response / @ResponseHeader / @ResponseCode
-RequestBeans = #juneau-rest-server.HttpParts.RequestBeans, Overview > juneau-rest-server > HTTP Parts > @Request beans
-RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams = #juneau-rest-server.HttpParts.RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams, Overview > juneau-rest-server > HTTP Parts > RequestHeaders / RequestQueryParams / RequestFormParams / RequestPathParams
-ResponseBeans = #juneau-rest-server.HttpParts.ResponseBeans, Overview > juneau-rest-server > HTTP Parts > @Response beans
+RequestBeans = #juneau-rest-server.HttpParts.RequestBeans, Overview > juneau-rest-server > HTTP Parts > @Request Beans
+ResponseBeans = #juneau-rest-server.HttpParts.ResponseBeans, Overview > juneau-rest-server > HTTP Parts > @Response Beans
RestAnnotatedClasses = #juneau-rest-server.RestAnnotatedClasses, Overview > juneau-rest-server > @Rest-Annotated Classes
RestAuthentication = #juneau-rest-client.RestAuthentication, Overview > juneau-rest-client > Authentication
RestBuiltInParameters = #juneau-rest-server.RestBuiltInParameters, Overview > juneau-rest-server > Built-in Parameters
diff --git a/juneau-doc/src/main/javadoc/resources/fragments/toc.html b/juneau-doc/src/main/javadoc/resources/fragments/toc.html
index 342c7c6..050d239 100644
--- a/juneau-doc/src/main/javadoc/resources/fragments/toc.html
+++ b/juneau-doc/src/main/javadoc/resources/fragments/toc.html
@@ -202,15 +202,22 @@
<li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.RestAnnotatedClasses.RestLifecycleHooks'>Lifecycle Hooks</a><span class='update'>updated: <b>9.0.0</b></span></p>
</ol>
<li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.RestOpAnnotatedMethods'>@RestOp-Annotated Methods</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <ol>
+ <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.RestOpAnnotatedMethods.InferredHttpMethodsAndPaths'>Inferred HTTP Methods and Paths</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.RestOpAnnotatedMethods.JavaMethodParameters'>Java Method Parameters</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.RestOpAnnotatedMethods.JavaMethodReturnTypes'>Java Method Return Types</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.RestOpAnnotatedMethods.JavaMethodThrowableTypes'>Java Method Throwable Types</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.RestOpAnnotatedMethods.PathPatterns'>Path Patterns</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.RestOpAnnotatedMethods.Matchers'>Matchers</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.RestOpAnnotatedMethods.AdditionalInformation'>Additional Information</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ </ol>
<li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.HttpParts'>HTTP Parts</a><span class='update'>updated: <b>9.0.0</b></span></p>
<ol>
- <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.HttpParts.PartSerializers_PartParsers'>Part Serializers / Part Parsers</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
- <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.HttpParts.Header_Path_Query_FormData'>@Header / @Path / @Query / @FormData</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
- <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.HttpParts.Body'>@Body and Request Bodies</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
- <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.HttpParts.RequestBeans'>@Request beans</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
- <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.HttpParts.ReponseHeader_ResponseStatus'>@Response / @ResponseHeader / @ResponseCode</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
- <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.HttpParts.ResponseBeans'>@Response beans</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
- <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.HttpParts.RequestHeader_RequestQueryParams_RequestFormParams_RequestPathParams'>RequestHeaders / RequestQueryParams / RequestFormParams / RequestPathParams</a><span class='update'>created: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.HttpParts.PartMarshallers'>Part Marshallers</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.HttpParts.HttpPartAnnotations'>HTTP Part Annotations</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.HttpParts.RequestBeans'>@Request Beans</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.HttpParts.ResponseBeans'>@Response Beans</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
+ <li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.HttpParts.HttpPartApis'>HTTP Part APIs</a><span class='update'>created: <b>9.0.0</b></span></p>
</ol>
<li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.RestHandlingFormPosts'>Handling Form Posts</a><span class='update'><b><red>todo</red></b></span></p>
<li><p><a class='doclink' href='{OVERVIEW_URL}#juneau-rest-server.RestHandlingMultiPartFormPosts'>Handling Multi-Part Form Posts</a><span class='update'>updated: 8.0.0, <b><red>todo</red></b></span></p>