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 10fc0037 Javadocs.
10fc0037 is described below
commit 10fc00370e05614dd8e51ee9018d86816fb8dd15
Author: JamesBognar <[email protected]>
AuthorDate: Fri Aug 3 08:23:56 2018 -0400
Javadocs.
---
juneau-doc/src/main/javadoc/overview.html | 308 ++++++++++++++++++---
.../src/main/resources/ReleaseNotes/7.2.0.html | 4 +-
.../06.RestMethod/14.PredefinedResponses.html | 109 +++++++-
.../06.RestMethod/15.PredefinedExceptions.html | 22 +-
.../06.RestMethod/16.PredefinedHelperBeans.html | 170 ++++++++++--
...{SeeOtherServletRoot.java => SeeOtherRoot.java} | 0
6 files changed, 538 insertions(+), 75 deletions(-)
diff --git a/juneau-doc/src/main/javadoc/overview.html
b/juneau-doc/src/main/javadoc/overview.html
index 586eee3..455ed03 100644
--- a/juneau-doc/src/main/javadoc/overview.html
+++ b/juneau-doc/src/main/javadoc/overview.html
@@ -297,8 +297,8 @@
<li><p class=''><a class='doclink'
href='#juneau-rest-server.RestMethod.ReaderResource'>ReaderResource</a></p>
<li><p class=''><a class='doclink'
href='#juneau-rest-server.RestMethod.StreamResource'>StreamResource</a></p>
<li><p class=''><a class='doclink'
href='#juneau-rest-server.RestMethod.RestMethodMatchers'>@RestMethod.matchers()</a></p>
- <li><p class='todo'><a class='doclink'
href='#juneau-rest-server.RestMethod.PredefinedResponses'>Predefined
Responses</a></p>
- <li><p class='todo'><a class='doclink'
href='#juneau-rest-server.RestMethod.PredefinedExceptions'>Predefined
Exceptions</a></p>
+ <li><p class='new'><a class='doclink'
href='#juneau-rest-server.RestMethod.PredefinedResponses'>Predefined
Responses</a></p>
+ <li><p class='new'><a class='doclink'
href='#juneau-rest-server.RestMethod.PredefinedExceptions'>Predefined
Exceptions</a></p>
<li><p class='todo'><a class='doclink'
href='#juneau-rest-server.RestMethod.PredefinedHelperBeans'>Predefined Helper
Beans</a></p>
</ol>
<li><p class='new'><a class='doclink'
href='#juneau-rest-server.OpenApiSchemaPartParsing'>OpenAPI Schema Part
Parsing</a></p>
@@ -13963,32 +13963,143 @@ TODO(7.2.0)
<!--
====================================================================================================
-->
-<h4 class='topic todo' onclick='toggle(this)'><a
href='#juneau-rest-server.RestMethod.PredefinedResponses'
id='juneau-rest-server.RestMethod.PredefinedResponses'>7.6.14 - Predefined
Responses</a></h4>
+<h4 class='topic new' onclick='toggle(this)'><a
href='#juneau-rest-server.RestMethod.PredefinedResponses'
id='juneau-rest-server.RestMethod.PredefinedResponses'>7.6.14 - Predefined
Responses</a></h4>
<div class='topic'><!-- START: 7.6.14 -
juneau-rest-server.RestMethod.PredefinedResponses -->
<p>
+ Predefined response beans are provided for all standard HTTP responses.
+ <br>These can be used as-is or extended to provide customized HTTP
responses.
+</p>
+<h5 class='figure'>Examples:</h5>
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>)
+ <jk>public</jk> Ok addPet(<ja>@Body</ja> Pet pet) {
+ <jsm>addPet</jsm>(Pet);
+
+ <jc>// Predefined "200 OK" response bean.</jc>
+ <jk>return new</jk> Ok(); <jc>// Could also use Ok.OK
instance</jc>
+ }
+</p>
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>)
+ <jk>public</jk> SeeOther addPet(<ja>@Body</ja> Pet pet) {
+ <jsm>addPet</jsm>(Pet);
+
+ <jc>// Predefined "302 See Other" response bean with redirect
to /pets.</jc>
+ <jk>return new</jk> SeeOther(<js>"servlet:/pets"</js>);
+ }
+</p>
+<ul class='doctree'>
+ <li class='jp'>{@link org.apache.juneau.rest.response}
+ <ul>
+ <li class='jc'>{@link org.apache.juneau.rest.response.Accepted}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.AlreadyReported}
+ <li class='jc'>{@link org.apache.juneau.rest.response.Continue}
+ <li class='jc'>{@link org.apache.juneau.rest.response.Created}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.EarlyHints}
+ <li class='jc'>{@link org.apache.juneau.rest.response.Found}
+ <li class='jc'>{@link org.apache.juneau.rest.response.IMUsed}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.MovedPermanently}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.MultipleChoices}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.MultiStatus}
+ <li class='jc'>{@link org.apache.juneau.rest.response.NoContent}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.NonAuthoritiveInformation}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.NotModified}
+ <li class='jc'>{@link org.apache.juneau.rest.response.Ok}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.PartialContent}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.PermanentRedirect}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.Processing}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.ResetContent}
+ <li class='jc'>{@link org.apache.juneau.rest.response.SeeOther}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.SwitchingProtocols}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.TemporaryRedirect}
+ <li class='jc'>{@link org.apache.juneau.rest.response.UseProxy}
+ </ul>
+</ul>
+<p>
+ These predefined response beans are an example of {@link
org.apache.juneau.http.annotation.Response @Response}-annotated
+ objects that are describe in detail later.
+ <br>Without going into details, this is how the {@link
org.apache.juneau.rest.response.SeeOther} is defined:
+</p>
+<p class='bpcode w800'>
+ <ja>@Response</ja>(
+ code=303 <jc>// Set automatically on response</jc>,
+ description=<js>"See Other"</js> <jc>// Used in generated
Swagger</jc>
+ )
+ <jk>public class</jk> SeeOther {
+
+ <jk>private final</jk> String <jf>message</jf>;
+ <jk>private final</jk> URI <jf>location</jf>;
+
+ <jc>// Constructors omitted.</jc>
+
+ <jc>// Used to populate Location response header.</jc>
+ <ja>@ResponseHeader</ja>(name=<js>"Location"</js>)
+ <jk>public</jk> URI getLocation() {
+ <jk>return</jk> <jf>location</jf>;
+ }
+
+ <jc>// Used during serialization.</jc>
+ <ja>@ResponseBody</ja>
+ <jk>public</jk> String toString() {
+ <jk>return</jk> <jf>message</jf>;
+ }
+ }
+</p>
+<p>
+ The {@link org.apache.juneau.rest.helper.SeeOtherRoot} class shows how
these predefined beans can be extended.
+</p>
+<p class='bpcode w800'>
+ <ja>@Response</ja>(
+ description=<js>"Redirect to servlet root"</js> <jc>// Override
description in generated Swagger.</jc>
+ )
+ <jk>public class</jk> SeeOtherServletRoot <jk>extends</jk> SeeOther {
+
+ <jk>public</jk> SeeOtherServletRoot() {
+ <jk>super</jk>(URI.create("servlet:/"));
+ }
+ }
+</p>
+<p>
+ Note that the runtime behavior of the following code is identical to
the example above.
+ <br>However, the important distinction is that in the previous example,
the 302 response would show in
+ the generated Swagger (since we can see the response through
reflection), whereas it will NOT show up
+ in the following example (since all we see is an Object response).
+</p>
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>)
+ <jk>public</jk> Object addPet(<ja>@Body</ja> Pet pet) {
+ <jsm>addPet</jsm>(Pet);
+
+ <jc>// Note the Object return type.</jc>
+ <jk>return new</jk> SeeOther(<js>"servlet:/pets"</js>);
+ }
</p>
</div><!-- END: 7.6.14 - juneau-rest-server.RestMethod.PredefinedResponses -->
<!--
====================================================================================================
-->
-<h4 class='topic todo' onclick='toggle(this)'><a
href='#juneau-rest-server.RestMethod.PredefinedExceptions'
id='juneau-rest-server.RestMethod.PredefinedExceptions'>7.6.15 - Predefined
Exceptions</a></h4>
+<h4 class='topic new' onclick='toggle(this)'><a
href='#juneau-rest-server.RestMethod.PredefinedExceptions'
id='juneau-rest-server.RestMethod.PredefinedExceptions'>7.6.15 - Predefined
Exceptions</a></h4>
<div class='topic'><!-- START: 7.6.15 -
juneau-rest-server.RestMethod.PredefinedExceptions -->
<p>
Exceptions are defined for all standardized HTTP responses.
These can be used to trigger HTTP errors simply by throwing an
exception.
</p>
+<p>
+ These are identical in behavior to the Predefined Responses in the
previous section, except these are meant
+ to be thrown instead of returned.
+</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
<ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
- <jk>public</jk> String login(
+ <jk>public</jk> Ok login(
<ja>@FormData</ja>(<js>"username"</js>) String username,
<ja>@FormData</ja>(<js>"password"</js>) String password,
) <jk>throws</jk> Unauthorized
{
- <jk>if</jk> (! isOK(username, password))
- <jk>throw new</jk> Unauthorized();
+ <jk>if</jk> (! <jsm>isOK</jsm>(username, password))
+ <jk>throw new</jk> Unauthorized(<js>"You're not
welcome!"</js>);
- <jk>return</jk> <js>"OK"</js>;
+ <jk>return</jk> Ok.<jsf>OK</jsf>;
}
</p>
<ul class='doctree'>
@@ -14029,6 +14140,12 @@ TODO(7.2.0)
<li class='jc'>{@link
org.apache.juneau.rest.exception.VariantAlsoNegotiates}
</ul>
</ul>
+<p>
+ These exception extend from {@link java.lang.RuntimeException}, so they
can optionally be specified in the thrown
+ declaration of the method.
+ <br>The important distinction is that when part of the thrown
declaration, they show up in the generated Swagger
+ documentation, whereas they don't if not. This behavior can be used to
define what error conditions show in your Swagger doc.
+</p>
</div><!-- END: 7.6.15 - juneau-rest-server.RestMethod.PredefinedExceptions -->
<!--
====================================================================================================
-->
@@ -14046,21 +14163,23 @@ TODO(7.2.0)
<li class='jc'>{@link
org.apache.juneau.rest.helper.ChildResourceDescriptions}
<li class='jc'>{@link
org.apache.juneau.rest.helper.ReaderResource}
<li class='jc'>{@link
org.apache.juneau.rest.helper.ReaderResourceBuilder}
- <li class='jc'>{@link
org.apache.juneau.rest.helper.SeeOtherServletRoot}
+ <li class='jc'>{@link
org.apache.juneau.rest.helper.SeeOtherRoot}
<li class='jc'>{@link
org.apache.juneau.rest.helper.ResourceDescription}
+ <li class='jc'>{@link
org.apache.juneau.rest.helper.ResourceDescriptions}
<li class='jc'>{@link
org.apache.juneau.rest.helper.StreamResource}
<li class='jc'>{@link
org.apache.juneau.rest.helper.StreamResourceBuilder}
</ul>
</ul>
-<h5 class='topic'>ResourceDescription, BeanDescription,
ChildResourceDescriptions</h5>
+<h5 class='topic'>ResourceDescription, ResourceDescrptions</h5>
<p>
The {@link org.apache.juneau.rest.helper.ResourceDescription} class is
a bean with name/description
properties for labeling and linking to child resources.
<br>The following examples is pulled from the REST examples:
</p>
<p class='bpcode w800'>
- <jk>public class</jk> PredefinedLabelsResource <jk>extends</jk>
BasicRestServlet {
+ <ja>@Resource</ja>
+ <jk>public class</jk> PredefinedLabelsResource {
<ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>)
<jk>public</jk> ResourceDescription[] getChildMethods() {
@@ -14082,45 +14201,53 @@ TODO(7.2.0)
<p class='bpcode w800'>
<jk>public class</jk> ResourceDescription {
+ <jc>// Renders as hyperlink when serialized as HTML.</jc>
<ja>@Html</ja>(link=<js>"servlet:/{name}"</js>)
- <jk>public</jk> Object getName() {...}
+ <jk>public</jk> String getName() {...}
- <jk>public</jk> Object getDescription() {...}
+ <jk>public</jk> String getDescription() {...}
}
</p>
<p>
- The {@link org.apache.juneau.rest.helper.BeanDescription} class
provides a simple view
- of a bean and it's properties.
+ {@link org.apache.juneau.rest.helper.ResourceDescriptions} is a
convenience class for doing the same.
+ <br>The example above can also be written as follows (which you'll
notice is more concise):
</p>
<p class='bpcode w800'>
- <ja>@RestMethod</ja>(name=<jsf>GET</jsf>,
path=<js>"/beanDescription"</js>)
- <jk>public</jk> BeanDescription getBeanDescription() {
- <jk>return new</jk> BeanDescription(Person.<jk>class</jk>);
- }
-</p>
-<p>
- This example renders the following:
+ <ja>@Resource</ja>
+ <jk>public class</jk> PredefinedLabelsResource {
+
+ <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>)
+ <jk>public</jk> ResourceDescriptions getChildMethods() {
+ <jk>return new</jk> ResourceDescriptions()
+ .append(<js>"beanDescription"</js>,
<js>"BeanDescription"</js>)
+ .append(<js>"htmlLinks"</js>,
<js>"HtmlLink"</js>);
+ }
+ }
</p>
-<img class='bordered'
src='doc-files/juneau-rest-server.PredefinedLabelBeans.2.png'
style='width:584px'/>
+<h5 class='topic'>@HtmlLink, LinkString</h5>
<p>
The {@link org.apache.juneau.html.annotation.HtmlLink @HtmlLink}
annotation can also be useful
for rendering custom hyperlinks:
</p>
<p class='bpcode w800'>
- <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/htmlLinks"</js>)
- <jk>public</jk> ALink[] htmlLinks() {
- <jk>return new</jk> ALink[] {
- <jk>new</jk> ALink(<js>"apache"</js>,
<js>"http://apache.org";</js>),
- <jk>new</jk> ALink(<js>"juneau"</js>,
<js>"http://juneau.apache.org";</js>)
+ <ja>@RestMethod</ja>
+ <jk>public</jk> MyLink[] htmlLinks() {
+ <jk>return new</jk> MyLink[] {
+ <jk>new</jk> MyLink(<js>"apache"</js>,
<js>"http://apache.org";</js>),
+ <jk>new</jk> MyLink(<js>"juneau"</js>,
<js>"http://juneau.apache.org";</js>)
};
}
+</p>
+<p class='bpcode w800'>
+ <ja>@HtmlLink</ja>(nameProperty=<js>"name"</js>,
hrefProperty=<js>"href"</js>)
+ <jk>public class</jk> MyLink {
- <ja>@HtmlLink</ja>(nameProperty=<js>"n"</js>, hrefProperty=<js>"l"</js>)
- <jk>public static class</jk> ALink {
- <jk>public</jk> String <jf>n</jf>, <jf>l</jf>;
- <jk>public</jk> ALink(String n, String l) {
- <jk>this</jk>.<jf>n</jf> = n;
- <jk>this</jk>.<jf>l</jf> = l;
+ <jc>// Simple bean properties.</jc>
+ <jk>public</jk> String <jf>name</jf>, <jf>href</jf>;
+
+ <jk>public</jk> MyLink(String name, String href) {
+ <jk>this</jk>.<jf>name</jf> = name;
+ <jk>this</jk>.<jf>href</jf> = href;
}
}
</p>
@@ -14130,7 +14257,7 @@ TODO(7.2.0)
<br>The following is equivalent to above.
</p>
<p class='bpcode w800'>
- <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/htmlLinks"</js>)
+ <ja>@RestMethod</ja>
<jk>public</jk> LinkString[] htmlLinks() {
<jk>return new</jk> LinkString[] {
<jk>new</jk> LinkString(<js>"apache"</js>,
<js>"http://apache.org";</js>),
@@ -14142,8 +14269,113 @@ TODO(7.2.0)
Both examples render the following consisting of a list of hyperlinks:
</p>
<img class='bordered'
src='doc-files/juneau-rest-server.PredefinedLabelBeans.3.png'
style='width:92px'/>
+<p>
+ In all other languages, it gets serialized as a simple bean with two
properties.
+</p>
+
+<h5 class='topic'>BeanDescription</h5>
+<p>
+ The {@link org.apache.juneau.rest.helper.BeanDescription} class
provides a simple view
+ of a bean and it's properties.
+</p>
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<jsf>GET</jsf>,
path=<js>"/beanDescription"</js>)
+ <jk>public</jk> BeanDescription getBeanDescription() {
+ <jk>return new</jk> BeanDescription(Person.<jk>class</jk>);
+ }
+</p>
+<p>
+ This example renders the following:
+</p>
+<img class='bordered'
src='doc-files/juneau-rest-server.PredefinedLabelBeans.2.png'
style='width:584px'/>
+
+<h5 class='topic'>ChildResourceDescriptions</h5>
+<p>
+ The {@link org.apache.juneau.rest.helper.ChildResourceDescriptions} is
a convenience bean for generating
+ a table of child resources.
+</p>
+<p>
+ The {@link org.apache.juneau.rest.BasicRestServletGroup} class uses
this to generate router pages:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestResource</ja>
+ <jk>public abstract class</jk> BasicRestServletGroup <jk>extends</jk>
BasicRestServlet {
+
+ <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>,
summary=<js>"Navigation page"</js>)
+ <jk>public</jk> ChildResourceDescriptions
getChildren(RestRequest req) <jk>throws</jk> Exception {
+ <jk>return new</jk> ChildResourceDescriptions(req);
+ }
+ }
+</p>
+<p>
+ Note that all it requires is a {@link
org.apache.juneau.rest.RestRequest} object and it will generate a router
+ page using reflection against the resource class.
+</p>
+<p>
+ For example, the <code>RootResources</code> page in the REST examples
renders the child resources attached to the root resource:
+</p>
+<img class='bordered'
src='doc-files/juneau-rest-server.PredefinedLabelBeans.4.png'
style='width:800px'/>
+<p>
+ The <code>RootResources</code> page consists of the following and
extends from the {@link org.apache.juneau.rest.BasicRestServletGroup} class:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestResource</ja>(
+ ...
+ children={
+ HelloWorldResource.<jk>class</jk>,
+ PetStoreResource.<jk>class</jk>,
+ SystemPropertiesResource.<jk>class</jk>,
+ MethodExampleResource.<jk>class</jk>,
+ RequestEchoResource.<jk>class</jk>,
+ AddressBookResource.<jk>class</jk>,
+ SampleRemoteableServlet.<jk>class</jk>,
+ DtoExamples.<jk>class</jk>,
+ PhotosResource.<jk>class</jk>,
+ SqlQueryResource.<jk>class</jk>,
+ CodeFormatterResource.<jk>class</jk>,
+ UrlEncodedFormResource.<jk>class</jk>,
+ TempDirResource.<jk>class</jk>,
+ ConfigResource.<jk>class</jk>,
+ LogsResource.<jk>class</jk>,
+ DockerRegistryResource.<jk>class</jk>,
+ DebugResource.<jk>class</jk>,
+ ShutdownResource.<jk>class</jk>
+ }
+ )
+ <jk>public class</jk> RootResources <jk>extends</jk>
BasicRestServletJenaGroup {}
+</p>
+
+<h5 class='topic'>SeeOtherRoot</h5>
+<p>
+ The {@link org.apache.juneau.rest.helper.SeeOtherRoot} class can be
used to redirect to the root URI
+ of a resource class.
+</p>
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>)
+ <jk>public</jk> SeeOtherRoot addPet(<ja>@Body</ja> Pet pet) {
+ <jsm>addPet</jsm>(Pet);
+
+ <jc>// Redirects to the servlet root URL.</jc>
+ <jk>return</jk> SeeOtherRoot.INSTANCE;
+ }
+</p>
+<p>
+ The runtime behavior is the same as the following:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>)
+ <jk>public</jk> SeeOther addPet(<ja>@Body</ja> Pet pet) {
+ <jsm>addPet</jsm>(Pet);
+
+ <jc>// Redirects to the servlet root URL.</jc>
+ <jk>return new</jk>
SeeOther(URI.<jsm>create</jsm>(<js>"servlet:/"</js>));
+ }
+</p>
+<p>
+ One distinction is that the former defines the description
<js>"Redirect to servlet root"</js> in the generated Swagger documentation.
+</p>
-<h5 class='topic'>ResourceDescription, BeanDescription,
ChildResourceDescriptions</h5>
+<h5 class='topic'>ReaderResource, StreamResource</h5>
</div><!-- END: 7.6.16 - juneau-rest-server.RestMethod.PredefinedHelperBeans
-->
</div><!-- END: 7.6 - juneau-rest-server.RestMethod -->
@@ -30365,7 +30597,7 @@ TODO(7.2.0)
<li class='jc'>{@link
org.apache.juneau.rest.helper.ChildResourceDescriptions}
<li class='jc'>{@link
org.apache.juneau.rest.helper.ReaderResource}
<li class='jc'>{@link
org.apache.juneau.rest.helper.ReaderResourceBuilder}
- <li class='jc'>{@link
org.apache.juneau.rest.helper.SeeOtherServletRoot}
+ <li class='jc'>{@link
org.apache.juneau.rest.helper.SeeOtherRoot}
<li class='jc'>{@link
org.apache.juneau.rest.helper.ResourceDescription}
<li class='jc'>{@link
org.apache.juneau.rest.helper.StreamResource}
<li class='jc'>{@link
org.apache.juneau.rest.helper.StreamResourceBuilder}
@@ -30527,7 +30759,7 @@ TODO(7.2.0)
<br>If not specified, the values are inferred from the Java
method name.
<br>See also:<a class="doclink"
href="#juneau-rest-server.RestMethod">Overview > juneau-rest-server >
@RestMethod</a>
<li>
- <code>RedirectToServletRoot</code> class has been renamed to
{@link org.apache.juneau.rest.helper.SeeOtherServletRoot}.
+ <code>RedirectToServletRoot</code> class has been renamed to
{@link org.apache.juneau.rest.helper.SeeOtherRoot}.
</ul>
<h5 class='topic w800'>juneau-rest-client</h5>
diff --git a/juneau-doc/src/main/resources/ReleaseNotes/7.2.0.html
b/juneau-doc/src/main/resources/ReleaseNotes/7.2.0.html
index 6bc079f..5a30032 100644
--- a/juneau-doc/src/main/resources/ReleaseNotes/7.2.0.html
+++ b/juneau-doc/src/main/resources/ReleaseNotes/7.2.0.html
@@ -276,7 +276,7 @@
<li class='jc'>{@link
org.apache.juneau.rest.helper.ChildResourceDescriptions}
<li class='jc'>{@link
org.apache.juneau.rest.helper.ReaderResource}
<li class='jc'>{@link
org.apache.juneau.rest.helper.ReaderResourceBuilder}
- <li class='jc'>{@link
org.apache.juneau.rest.helper.SeeOtherServletRoot}
+ <li class='jc'>{@link
org.apache.juneau.rest.helper.SeeOtherRoot}
<li class='jc'>{@link
org.apache.juneau.rest.helper.ResourceDescription}
<li class='jc'>{@link
org.apache.juneau.rest.helper.StreamResource}
<li class='jc'>{@link
org.apache.juneau.rest.helper.StreamResourceBuilder}
@@ -438,7 +438,7 @@
<br>If not specified, the values are inferred from the Java
method name.
<br>See also:<a class="doclink"
href="#juneau-rest-server.RestMethod">Overview > juneau-rest-server >
@RestMethod</a>
<li>
- <code>RedirectToServletRoot</code> class has been renamed to
{@link org.apache.juneau.rest.helper.SeeOtherServletRoot}.
+ <code>RedirectToServletRoot</code> class has been renamed to
{@link org.apache.juneau.rest.helper.SeeOtherRoot}.
</ul>
<h5 class='topic w800'>juneau-rest-client</h5>
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/06.RestMethod/14.PredefinedResponses.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/06.RestMethod/14.PredefinedResponses.html
index fdc4de7..e98d285 100644
---
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/06.RestMethod/14.PredefinedResponses.html
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/06.RestMethod/14.PredefinedResponses.html
@@ -13,7 +13,114 @@
***************************************************************************************************************************/
-->
-{todo} Predefined Responses
+{new} Predefined Responses
<p>
+ Predefined response beans are provided for all standard HTTP responses.
+ <br>These can be used as-is or extended to provide customized HTTP
responses.
+</p>
+<h5 class='figure'>Examples:</h5>
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>)
+ <jk>public</jk> Ok addPet(<ja>@Body</ja> Pet pet) {
+ <jsm>addPet</jsm>(Pet);
+
+ <jc>// Predefined "200 OK" response bean.</jc>
+ <jk>return new</jk> Ok(); <jc>// Could also use Ok.OK
instance</jc>
+ }
+</p>
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>)
+ <jk>public</jk> SeeOther addPet(<ja>@Body</ja> Pet pet) {
+ <jsm>addPet</jsm>(Pet);
+
+ <jc>// Predefined "302 See Other" response bean with redirect
to /pets.</jc>
+ <jk>return new</jk> SeeOther(<js>"servlet:/pets"</js>);
+ }
+</p>
+<ul class='doctree'>
+ <li class='jp'>{@link org.apache.juneau.rest.response}
+ <ul>
+ <li class='jc'>{@link org.apache.juneau.rest.response.Accepted}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.AlreadyReported}
+ <li class='jc'>{@link org.apache.juneau.rest.response.Continue}
+ <li class='jc'>{@link org.apache.juneau.rest.response.Created}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.EarlyHints}
+ <li class='jc'>{@link org.apache.juneau.rest.response.Found}
+ <li class='jc'>{@link org.apache.juneau.rest.response.IMUsed}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.MovedPermanently}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.MultipleChoices}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.MultiStatus}
+ <li class='jc'>{@link org.apache.juneau.rest.response.NoContent}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.NonAuthoritiveInformation}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.NotModified}
+ <li class='jc'>{@link org.apache.juneau.rest.response.Ok}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.PartialContent}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.PermanentRedirect}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.Processing}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.ResetContent}
+ <li class='jc'>{@link org.apache.juneau.rest.response.SeeOther}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.SwitchingProtocols}
+ <li class='jc'>{@link
org.apache.juneau.rest.response.TemporaryRedirect}
+ <li class='jc'>{@link org.apache.juneau.rest.response.UseProxy}
+ </ul>
+</ul>
+<p>
+ These predefined response beans are an example of {@link
org.apache.juneau.http.annotation.Response @Response}-annotated
+ objects that are describe in detail later.
+ <br>Without going into details, this is how the {@link
org.apache.juneau.rest.response.SeeOther} is defined:
+</p>
+<p class='bpcode w800'>
+ <ja>@Response</ja>(
+ code=303 <jc>// Set automatically on response</jc>,
+ description=<js>"See Other"</js> <jc>// Used in generated
Swagger</jc>
+ )
+ <jk>public class</jk> SeeOther {
+
+ <jk>private final</jk> String <jf>message</jf>;
+ <jk>private final</jk> URI <jf>location</jf>;
+
+ <jc>// Constructors omitted.</jc>
+
+ <jc>// Used to populate Location response header.</jc>
+ <ja>@ResponseHeader</ja>(name=<js>"Location"</js>)
+ <jk>public</jk> URI getLocation() {
+ <jk>return</jk> <jf>location</jf>;
+ }
+
+ <jc>// Used during serialization.</jc>
+ <ja>@ResponseBody</ja>
+ <jk>public</jk> String toString() {
+ <jk>return</jk> <jf>message</jf>;
+ }
+ }
+</p>
+<p>
+ The {@link org.apache.juneau.rest.helper.SeeOtherRoot} class shows how
these predefined beans can be extended.
+</p>
+<p class='bpcode w800'>
+ <ja>@Response</ja>(
+ description=<js>"Redirect to servlet root"</js> <jc>// Override
description in generated Swagger.</jc>
+ )
+ <jk>public class</jk> SeeOtherServletRoot <jk>extends</jk> SeeOther {
+
+ <jk>public</jk> SeeOtherServletRoot() {
+ <jk>super</jk>(URI.create("servlet:/"));
+ }
+ }
+</p>
+<p>
+ Note that the runtime behavior of the following code is identical to
the example above.
+ <br>However, the important distinction is that in the previous example,
the 302 response would show in
+ the generated Swagger (since we can see the response through
reflection), whereas it will NOT show up
+ in the following example (since all we see is an Object response).
+</p>
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>)
+ <jk>public</jk> Object addPet(<ja>@Body</ja> Pet pet) {
+ <jsm>addPet</jsm>(Pet);
+
+ <jc>// Note the Object return type.</jc>
+ <jk>return new</jk> SeeOther(<js>"servlet:/pets"</js>);
+ }
</p>
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/06.RestMethod/15.PredefinedExceptions.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/06.RestMethod/15.PredefinedExceptions.html
index 3fdb030..7ee4879 100644
---
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/06.RestMethod/15.PredefinedExceptions.html
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/06.RestMethod/15.PredefinedExceptions.html
@@ -13,24 +13,28 @@
***************************************************************************************************************************/
-->
-{todo} Predefined Exceptions
+{new} Predefined Exceptions
<p>
Exceptions are defined for all standardized HTTP responses.
These can be used to trigger HTTP errors simply by throwing an
exception.
</p>
+<p>
+ These are identical in behavior to the Predefined Responses in the
previous section, except these are meant
+ to be thrown instead of returned.
+</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
<ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
- <jk>public</jk> String login(
+ <jk>public</jk> Ok login(
<ja>@FormData</ja>(<js>"username"</js>) String username,
<ja>@FormData</ja>(<js>"password"</js>) String password,
) <jk>throws</jk> Unauthorized
{
- <jk>if</jk> (! isOK(username, password))
- <jk>throw new</jk> Unauthorized();
+ <jk>if</jk> (! <jsm>isOK</jsm>(username, password))
+ <jk>throw new</jk> Unauthorized(<js>"You're not
welcome!"</js>);
- <jk>return</jk> <js>"OK"</js>;
+ <jk>return</jk> Ok.<jsf>OK</jsf>;
}
</p>
<ul class='doctree'>
@@ -70,4 +74,10 @@
<li class='jc'>{@link
org.apache.juneau.rest.exception.UriTooLong}
<li class='jc'>{@link
org.apache.juneau.rest.exception.VariantAlsoNegotiates}
</ul>
-</ul>
\ No newline at end of file
+</ul>
+<p>
+ These exception extend from {@link java.lang.RuntimeException}, so they
can optionally be specified in the thrown
+ declaration of the method.
+ <br>The important distinction is that when part of the thrown
declaration, they show up in the generated Swagger
+ documentation, whereas they don't if not. This behavior can be used to
define what error conditions show in your Swagger doc.
+</p>
\ No newline at end of file
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/06.RestMethod/16.PredefinedHelperBeans.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/06.RestMethod/16.PredefinedHelperBeans.html
index 0eace46..85cce31 100644
---
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/06.RestMethod/16.PredefinedHelperBeans.html
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/06.RestMethod/16.PredefinedHelperBeans.html
@@ -26,21 +26,23 @@
<li class='jc'>{@link
org.apache.juneau.rest.helper.ChildResourceDescriptions}
<li class='jc'>{@link
org.apache.juneau.rest.helper.ReaderResource}
<li class='jc'>{@link
org.apache.juneau.rest.helper.ReaderResourceBuilder}
- <li class='jc'>{@link
org.apache.juneau.rest.helper.SeeOtherServletRoot}
+ <li class='jc'>{@link
org.apache.juneau.rest.helper.SeeOtherRoot}
<li class='jc'>{@link
org.apache.juneau.rest.helper.ResourceDescription}
+ <li class='jc'>{@link
org.apache.juneau.rest.helper.ResourceDescriptions}
<li class='jc'>{@link
org.apache.juneau.rest.helper.StreamResource}
<li class='jc'>{@link
org.apache.juneau.rest.helper.StreamResourceBuilder}
</ul>
</ul>
-<h5 class='topic'>ResourceDescription, BeanDescription,
ChildResourceDescriptions</h5>
+<h5 class='topic'>ResourceDescription, ResourceDescrptions</h5>
<p>
The {@link org.apache.juneau.rest.helper.ResourceDescription} class is
a bean with name/description
properties for labeling and linking to child resources.
<br>The following examples is pulled from the REST examples:
</p>
<p class='bpcode w800'>
- <jk>public class</jk> PredefinedLabelsResource <jk>extends</jk>
BasicRestServlet {
+ <ja>@Resource</ja>
+ <jk>public class</jk> PredefinedLabelsResource {
<ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>)
<jk>public</jk> ResourceDescription[] getChildMethods() {
@@ -62,45 +64,53 @@
<p class='bpcode w800'>
<jk>public class</jk> ResourceDescription {
+ <jc>// Renders as hyperlink when serialized as HTML.</jc>
<ja>@Html</ja>(link=<js>"servlet:/{name}"</js>)
- <jk>public</jk> Object getName() {...}
+ <jk>public</jk> String getName() {...}
- <jk>public</jk> Object getDescription() {...}
+ <jk>public</jk> String getDescription() {...}
}
</p>
<p>
- The {@link org.apache.juneau.rest.helper.BeanDescription} class
provides a simple view
- of a bean and it's properties.
+ {@link org.apache.juneau.rest.helper.ResourceDescriptions} is a
convenience class for doing the same.
+ <br>The example above can also be written as follows (which you'll
notice is more concise):
</p>
<p class='bpcode w800'>
- <ja>@RestMethod</ja>(name=<jsf>GET</jsf>,
path=<js>"/beanDescription"</js>)
- <jk>public</jk> BeanDescription getBeanDescription() {
- <jk>return new</jk> BeanDescription(Person.<jk>class</jk>);
- }
-</p>
-<p>
- This example renders the following:
+ <ja>@Resource</ja>
+ <jk>public class</jk> PredefinedLabelsResource {
+
+ <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>)
+ <jk>public</jk> ResourceDescriptions getChildMethods() {
+ <jk>return new</jk> ResourceDescriptions()
+ .append(<js>"beanDescription"</js>,
<js>"BeanDescription"</js>)
+ .append(<js>"htmlLinks"</js>,
<js>"HtmlLink"</js>);
+ }
+ }
</p>
-<img class='bordered'
src='doc-files/juneau-rest-server.PredefinedLabelBeans.2.png'
style='width:584px'/>
+<h5 class='topic'>@HtmlLink, LinkString</h5>
<p>
The {@link org.apache.juneau.html.annotation.HtmlLink @HtmlLink}
annotation can also be useful
for rendering custom hyperlinks:
</p>
<p class='bpcode w800'>
- <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/htmlLinks"</js>)
- <jk>public</jk> ALink[] htmlLinks() {
- <jk>return new</jk> ALink[] {
- <jk>new</jk> ALink(<js>"apache"</js>,
<js>"http://apache.org";</js>),
- <jk>new</jk> ALink(<js>"juneau"</js>,
<js>"http://juneau.apache.org";</js>)
+ <ja>@RestMethod</ja>
+ <jk>public</jk> MyLink[] htmlLinks() {
+ <jk>return new</jk> MyLink[] {
+ <jk>new</jk> MyLink(<js>"apache"</js>,
<js>"http://apache.org";</js>),
+ <jk>new</jk> MyLink(<js>"juneau"</js>,
<js>"http://juneau.apache.org";</js>)
};
}
+</p>
+<p class='bpcode w800'>
+ <ja>@HtmlLink</ja>(nameProperty=<js>"name"</js>,
hrefProperty=<js>"href"</js>)
+ <jk>public class</jk> MyLink {
+
+ <jc>// Simple bean properties.</jc>
+ <jk>public</jk> String <jf>name</jf>, <jf>href</jf>;
- <ja>@HtmlLink</ja>(nameProperty=<js>"n"</js>, hrefProperty=<js>"l"</js>)
- <jk>public static class</jk> ALink {
- <jk>public</jk> String <jf>n</jf>, <jf>l</jf>;
- <jk>public</jk> ALink(String n, String l) {
- <jk>this</jk>.<jf>n</jf> = n;
- <jk>this</jk>.<jf>l</jf> = l;
+ <jk>public</jk> MyLink(String name, String href) {
+ <jk>this</jk>.<jf>name</jf> = name;
+ <jk>this</jk>.<jf>href</jf> = href;
}
}
</p>
@@ -110,7 +120,7 @@
<br>The following is equivalent to above.
</p>
<p class='bpcode w800'>
- <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/htmlLinks"</js>)
+ <ja>@RestMethod</ja>
<jk>public</jk> LinkString[] htmlLinks() {
<jk>return new</jk> LinkString[] {
<jk>new</jk> LinkString(<js>"apache"</js>,
<js>"http://apache.org";</js>),
@@ -122,6 +132,110 @@
Both examples render the following consisting of a list of hyperlinks:
</p>
<img class='bordered'
src='doc-files/juneau-rest-server.PredefinedLabelBeans.3.png'
style='width:92px'/>
+<p>
+ In all other languages, it gets serialized as a simple bean with two
properties.
+</p>
+
+<h5 class='topic'>BeanDescription</h5>
+<p>
+ The {@link org.apache.juneau.rest.helper.BeanDescription} class
provides a simple view
+ of a bean and it's properties.
+</p>
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<jsf>GET</jsf>,
path=<js>"/beanDescription"</js>)
+ <jk>public</jk> BeanDescription getBeanDescription() {
+ <jk>return new</jk> BeanDescription(Person.<jk>class</jk>);
+ }
+</p>
+<p>
+ This example renders the following:
+</p>
+<img class='bordered'
src='doc-files/juneau-rest-server.PredefinedLabelBeans.2.png'
style='width:584px'/>
-<h5 class='topic'>ResourceDescription, BeanDescription,
ChildResourceDescriptions</h5>
+<h5 class='topic'>ChildResourceDescriptions</h5>
+<p>
+ The {@link org.apache.juneau.rest.helper.ChildResourceDescriptions} is
a convenience bean for generating
+ a table of child resources.
+</p>
+<p>
+ The {@link org.apache.juneau.rest.BasicRestServletGroup} class uses
this to generate router pages:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestResource</ja>
+ <jk>public abstract class</jk> BasicRestServletGroup <jk>extends</jk>
BasicRestServlet {
+
+ <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>,
summary=<js>"Navigation page"</js>)
+ <jk>public</jk> ChildResourceDescriptions
getChildren(RestRequest req) <jk>throws</jk> Exception {
+ <jk>return new</jk> ChildResourceDescriptions(req);
+ }
+ }
+</p>
+<p>
+ Note that all it requires is a {@link
org.apache.juneau.rest.RestRequest} object and it will generate a router
+ page using reflection against the resource class.
+</p>
+<p>
+ For example, the <code>RootResources</code> page in the REST examples
renders the child resources attached to the root resource:
+</p>
+<img class='bordered'
src='doc-files/juneau-rest-server.PredefinedLabelBeans.4.png'
style='width:800px'/>
+<p>
+ The <code>RootResources</code> page consists of the following and
extends from the {@link org.apache.juneau.rest.BasicRestServletGroup} class:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestResource</ja>(
+ ...
+ children={
+ HelloWorldResource.<jk>class</jk>,
+ PetStoreResource.<jk>class</jk>,
+ SystemPropertiesResource.<jk>class</jk>,
+ MethodExampleResource.<jk>class</jk>,
+ RequestEchoResource.<jk>class</jk>,
+ AddressBookResource.<jk>class</jk>,
+ SampleRemoteableServlet.<jk>class</jk>,
+ DtoExamples.<jk>class</jk>,
+ PhotosResource.<jk>class</jk>,
+ SqlQueryResource.<jk>class</jk>,
+ CodeFormatterResource.<jk>class</jk>,
+ UrlEncodedFormResource.<jk>class</jk>,
+ TempDirResource.<jk>class</jk>,
+ ConfigResource.<jk>class</jk>,
+ LogsResource.<jk>class</jk>,
+ DockerRegistryResource.<jk>class</jk>,
+ DebugResource.<jk>class</jk>,
+ ShutdownResource.<jk>class</jk>
+ }
+ )
+ <jk>public class</jk> RootResources <jk>extends</jk>
BasicRestServletJenaGroup {}
+</p>
+
+<h5 class='topic'>SeeOtherRoot</h5>
+<p>
+ The {@link org.apache.juneau.rest.helper.SeeOtherRoot} class can be
used to redirect to the root URI
+ of a resource class.
+</p>
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>)
+ <jk>public</jk> SeeOtherRoot addPet(<ja>@Body</ja> Pet pet) {
+ <jsm>addPet</jsm>(Pet);
+
+ <jc>// Redirects to the servlet root URL.</jc>
+ <jk>return</jk> SeeOtherRoot.INSTANCE;
+ }
+</p>
+<p>
+ The runtime behavior is the same as the following:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>)
+ <jk>public</jk> SeeOther addPet(<ja>@Body</ja> Pet pet) {
+ <jsm>addPet</jsm>(Pet);
+
+ <jc>// Redirects to the servlet root URL.</jc>
+ <jk>return new</jk>
SeeOther(URI.<jsm>create</jsm>(<js>"servlet:/"</js>));
+ }
+</p>
+<p>
+ One distinction is that the former defines the description
<js>"Redirect to servlet root"</js> in the generated Swagger documentation.
+</p>
+<h5 class='topic'>ReaderResource, StreamResource</h5>
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/helper/SeeOtherServletRoot.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/helper/SeeOtherRoot.java
similarity index 100%
rename from
juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/helper/SeeOtherServletRoot.java
rename to
juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/helper/SeeOtherRoot.java
