This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/juneau.git
commit da2b9682a2a5ed64ad9a0ab61aa22300d544699a
Author: JamesBognar <james.bog...@salesforce.com>
AuthorDate: Sat Jun 18 08:19:44 2022 -0400
Javadocs
---
.../01.jrss.Overview.html | 155 ++++++++++++++++-----
.../02.jrss.ChildResources.html | 85 -----------
.../doc-files/jrss.Overview.HelloWorldResource.png | Bin 0 -> 76244 bytes
.../doc-files/jrss.Overview.RootResources.json.png | Bin 0 -> 121600 bytes
.../doc-files/jrss.Overview.RootResources.png | Bin 0 -> 195239 bytes
.../juneau/examples/rest/springboot/App.java | 2 +-
.../rest/springboot/HelloWorldResource.java | 34 +----
.../examples/rest/springboot/RootResources.java | 6 +-
8 files changed, 128 insertions(+), 154 deletions(-)
diff --git
a/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/01.jrss.Overview.html
b/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/01.jrss.Overview.html
index f79a8be23..8060d5e3d 100644
---
a/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/01.jrss.Overview.html
+++
b/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/01.jrss.Overview.html
@@ -13,66 +13,153 @@
***************************************************************************************************************************/
-->
-{title:'Overview', created:'8.0.0', flags:'todo'}
+{title:'Overview', created:'8.0.0', updated:'9.0.0'}
<div class='topic'>
<p>
- The Juneau integration component for Spring Boot consists of
the following classes:
+ The Juneau REST servlet APIs are designed to work seemlessly
with the Spring Boot framework.
+ The only restriction is that your top-level REST resource must
extend from one of the following classes:
</p>
<ul class='javatree'>
- <li class='ja'>{@del oajr.springboot.annotation.JuneauRestRoot}
- <li class='jc'>{@del oajr.springboot.JuneauRestInitializer}
- <li class='jc'>{@del oajr.springboot.SpringRestResourceResolver}
+ <li class='jp'>{@link oajr.springboot}
+ <ul class='javatree'>
+ <li class='jc'>{@link
oajr.springboot.BasicSpringRestServlet} - Basic servlet
+ <li class='jc'>{@link
oajr.springboot.BasicSpringRestServletGroup} - Basic servlet group
+ </ul>
</ul>
<p>
- A typical Spring Boot application can use the {@del
oajr.springboot.JuneauRestInitializer} to find
- and register Juneau REST servlets via the {@del
oajr.springboot.annotation.JuneauRestRoot} annotation.
+ These classes are the equivalent to the {@link
oajr.servlet.BasicRestServlet} and {@link oajr.servlet.BasicRestServletGroup}
+ except they hook into the injection framework of Spring Boot to
provide resolution of beans (e.g. child resources, various
+ configuration classes).
</p>
- <h5 class='figure'>Example:</h5>
+ <p>
+ The {@link org.apache.juneau.examples.rest.springboot} package
and {@link org.apache.juneau.examples.rest.springboot.App}
+ application are a basic Spring Boot application that shows off
simple Juneau examples including injection beans.
+ </p>
<p class='bjava'>
| <ja>@SpringBootApplication</ja>
| <ja>@Controller</ja>
| <jk>public class</jk> App {
|
- | <jk>public static void</jk> main(String[] args)
{
- | <jk>new</jk>
SpringApplicationBuilder(App.<jk>class</jk>)
- | .initializers(<jk>new</jk>
JuneauRestInitializer(App.<jk>class</jk>))
- | .run(args);
+ | <jc>//Entry point method.</jc>
+ | <jk>public static void</jk> main(String[]
<jv>args</jv>) {
+ | <jk>new</jk>
SpringApplicationBuilder(App.<jk>class</jk>).run(<jv>args</jv>);
+ | }
+ |
+ | <jc>// Our root REST bean.
+ | // Note that this must extend from {@link
SpringRestServlet} to allow use of injection.
+ | // All REST objects are attached to this bean
using the {@link Rest#children()} annotation.</jc>
+ | <ja>@Bean</ja>
+ | <jk>public</jk> RootResources
getRootResources() {
+ | <jk>return new</jk> RootResources();
+ | }
+ |
+ | <jc>// Registers our REST bean at the URI
root.</jc>
+ | <ja>@Bean</ja>
+ | <jk>public</jk>
ServletRegistrationBean<Servlet> getRootServlet(RootResources
<jv>rootResources</jv>) {
+ | <jk>return new</jk>
ServletRegistrationBean<>(<jv>rootResources</jv>, <js>"/*"</js>);
| }
|
- | <jd>/** Our root resource */</jd>
- | <ja>@Bean @JuneauRestRoot</ja>
- | <jk>public</jk> RootResource getRootResource() {
- | <jk>return new</jk> RootResource();
<jc>// A subclass of RestServlet.</jc>
+ | <jc>// Injected child resource.</jc>
+ | <ja>@Bean</ja>
+ | <jk>public</jk> HelloWorldResource
getHelloWorldResource() {
+ | <jk>return new</jk>
HelloWorldResource();
+ | }
+ |
+ | <jc>// Injected child bean used in injected
child resource.</jc>
+ | <ja>@Bean</ja>
+ | <jk>public</jk> HelloWorldMessageProvider
getHelloWorldMessageProvider() {
+ | <jk>return new</jk>
HelloWorldMessageProvider(<js>"Hello Spring injection user!"</js>);
| }
| }
- </p>
+ </p>
<p>
- The initializer will search for Spring beans annotated with the
<ja>@JuneauRestRoot</ja> annotation identifying it
- as a top-level servlet to be deployed in the Spring Boot web
container.
+ Our root resource servlet serves as a router page. It is
defined as follows:
</p>
+ <p class='bjava'>
+ | <ja>@Rest</ja>(
+ | title=<js>"Root resources"</js>,
+ | description=<js>"Example of a router resource
page."</js>,
+ | children={
+ | HelloWorldResource.<jk>class</jk>,
+ | DtoExamples.<jk>class</jk>,
+ | UtilityBeansResource.<jk>class</jk>,
+ | HtmlBeansResource.<jk>class</jk>,
+ | ConfigResource.<jk>class</jk>,
+ | ShutdownResource.<jk>class</jk>
+ | }
+ | )
+ | <ja>@HtmlDocConfig</ja>(
+ | widgets={
+ | ContentTypeMenuItem.<jk>class</jk>
+ | },
+ | navlinks={
+ | <js>"api: servlet:/api"</js>,
+ | <js>"stats: servlet:/stats"</js>,
+ | <js>"$W{ContentTypeMenuItem}"</js>,
+ | <js>"source:
$C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java"</js>
+ | },
+ | aside={
+ | <js>"<div class='text'>"</js>,
+ | <js>" <p>This is an example of
a 'router' page that serves as a jumping-off point to child
resources.</p>"</js>,
+ | <js>" <p>Resources can be
nested arbitrarily deep through router pages.</p>"</js>,
+ | <js>" <p>Note the <span
class='link'>API</span> link provided that lets you see the generated
swagger doc for this page.</p>"</js>,
+ | <js>" <p>Also note the <span
class='link'>STATS</span> link that provides basic usage
statistics.</p>"</js>,
+ | <js>" <p>Also note the <span
class='link'>SOURCE</span> link on these pages to view the source code
for the page.</p>"</js>,
+ | <js>" <p>All content on pages
in the UI are serialized POJOs. In this case, it's a serialized array of beans
with 2 properties, 'name' and 'description'.</p>"</js>,
+ | <js>" <p>Other features (such
as this aside) are added through annotations.</p>"</js>,
+ | <js>"</div>"</js>
+ | },
+ | asideFloat="RIGHT"
+ | )
+ | <ja>@SerializerConfig</ja>(
+ | quoteChar=<js>"'"</js>
+ | )
+ | <jk>public class</jk> RootResources <jk>extends</jk>
BasicSpringRestServletGroup <jk>implements</jk> BasicUniversalConfig {
+ | <jk>private static final long</jk>
<jsf>serialVersionUID</jsf> = 1L;
+ | }
+ </p>
+
+ <h5 class='figure'>HTML representation</h5>
+ <img class='bordered w800'
src='doc-files/jrss.Overview.RootResources.png'>
+
+ <h5 class='figure'>JSON representation</h5>
+ <img class='bordered w800'
src='doc-files/jrss.Overview.RootResources.json.png'>
+
<p>
- Another option is to use the <ja>@JuneauRestRoot</ja>
annotation on your Spring Boot source class like so:
+ The {@link
org.apache.juneau.examples.rest.springboot.HelloWorldResource} class shows an
example of a child resource
+ defined as an injected bean.
</p>
<p class='bjava'>
- | <ja>@SpringBootApplication</ja>
- | <ja>@Controller</ja>
- |
<ja>@JuneauRestRoot</ja>(servlets=RootResource.<jk>class</jk>)
- | <jk>public class</jk> App {
+ | <ja>@Rest</ja>(
+ | title=<js>"Hello World"</js>,
+ | description=<js>"An example of the
simplest-possible resource"</js>,
+ | path=<js>"/helloWorld"</js>
+ | )
+ | <ja>@HtmlDocConfig</ja>(
+ | aside={
+ | <js>"<div style='max-width:400px'
class='text'>"</js>,
+ | <js>" <p>This page shows a
resource that simply response with a 'Hello world!' message</p>"</js>,
+ | <js>" <p>The POJO serialized is
a simple String.</p>"</js>,
+ | <js>"</div>"</js>
+ | }
+ | )
+ | <jk>public class</jk> HelloWorldResource
<jk>extends</jk> BasicRestObject <jk>implements</jk> BasicUniversalConfig {
+ |
+ | <ja>@Inject</ja>
+ | <jk>private</jk> HelloWorldMessageProvider
<jf>messageProvider</jf>;
|
- | <jk>public static void</jk> main(String[] args)
{
- | <jk>new</jk>
SpringApplicationBuilder(App.<jk>class</jk>)
- | .initializers(<jk>new</jk>
JuneauRestInitializer(App.<jk>class</jk>))
- | .run(args);
+ | <ja>@RestGet</ja>(path=<js>"/*"</js>,
summary=<js>"Responds with injected message"</js>)
+ | <jk>public</jk> String sayHello() {
+ | <jk>return</jk>
<jf>messageProvider</jf>.get();
| }
| }
</p>
+
<p>
- The root servlets are given an instance of {@del
oajr.springboot.SpringRestResourceResolver} which allows
- for child resources to be defined as injectable Spring beans.
- </p>
- <p>
- The {@doc juneau-examples-rest-springboot} section describes
how the Examples REST application is deployed
- using Spring Boot and quickly deployable as an online
application using Heroku.
+ Note that the message rendered is coming from our injected
message provider:
</p>
+ <h5 class='figure'>HTML representation</h5>
+ <img class='bordered w800'
src='doc-files/jrss.Overview.HelloWorldResource.png'>
+
</div>
\ No newline at end of file
diff --git
a/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/02.jrss.ChildResources.html
b/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/02.jrss.ChildResources.html
deleted file mode 100644
index 810819628..000000000
---
a/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/02.jrss.ChildResources.html
+++ /dev/null
@@ -1,85 +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:'Child Resources', created:'8.1.0', flags:'todo'}
-
-<div class='topic'>
- <p>
- When using the <ja>@JuneauRestRoot</ja> annotation, servlet are
given an instance of {@del oajr.springboot.SpringRestResourceResolver}.
- The resource resolver gets passed down through the children
hierarchy, allowing child resources to be defined as injectable Spring beans.
- </p>
- <h5 class='figure'>Example:</h5>
- <p class='bjava'>
- | <ja>@Configuration</ja>
- | <jk>public class</jk> AppConfiguration {
- |
- | <ja>@Bean @JuneauRestRoot</ja>
- | <jk>public</jk> RootResource getRootResource() {
- | <jk>return new</jk> RootResource();
- | }
- |
- | <ja>@Bean</ja>
- | <jk>public</jk> ChildResource
getChildResource() {
- | <jk>return new</jk> ChildResource();
- | }
- |
- | <ja>@Bean</ja>
- | <jk>public</jk> GrandChildResource
getGrandChildResource() {
- | <jk>return new</jk>
GrandChildResource();
- | }
- | }
- </p>
- <p>
- The root resource class must extend from <c>HttpServlet</c> so
that it can be registered as a normal
- servlet using the Spring Boot architecture. The {@link
oajr.servlet.BasicRestServletGroup} class is our router class
- that extends from <c>HttpServlet</c>:
- </p>
- <p class='bjava'>
- | <ja>@Rest</ja>(
- | path=<js>"/root"</js>,
- | children={
- | ChildResource.<jk>class</jk>
- | }
- | )
- | <jk>public class</jk> RootResource <jk>extends</jk>
BasicRestServletGroup <jk>implements</jk> BasicUniversalConfig {
- | <jc>// No code needed.</jc>
- | }
- </p>
- <p>
- Because Spring Boot will automatically register any beans that
extend from <c>HttpServlet</c>, we
- DON'T want the child classes to extend from <c>HttpServlet</c>.
Instead, we extend from
- {@del oajr.BasicRestGroup} and {@del oajr.BasicRest} instead:
- </p>
-
- <p class='bjava'>
- | <ja>@Rest</ja>(
- | path=<js>"/child"</js>,
- | children={
- | GrandChildResource.<jk>class</jk>
- | }
- | )
- | <jk>public class</jk> ChildResource <jk>extends</jk>
BasicRestGroup <jk>implements</jk> BasicUniversalConfig {
- | <jc>// No code needed.</jc>
- | }
- </p>
- <p class='bjava'>
- | <ja>@Rest</ja>(
- | path=<js>"/grandchild"</js>
- | )
- | <jk>public class</jk> GrandChildResource
<jk>extends</jk> BasicRestObject <jk>implements</jk> BasicUniversalConfig {
- | <jc>// Injectable bean</jc>
- | }
- </p>
-</div>
\ No newline at end of file
diff --git
a/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/doc-files/jrss.Overview.HelloWorldResource.png
b/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/doc-files/jrss.Overview.HelloWorldResource.png
new file mode 100644
index 000000000..8bbed7952
Binary files /dev/null and
b/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/doc-files/jrss.Overview.HelloWorldResource.png
differ
diff --git
a/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/doc-files/jrss.Overview.RootResources.json.png
b/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/doc-files/jrss.Overview.RootResources.json.png
new file mode 100644
index 000000000..4220a5efd
Binary files /dev/null and
b/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/doc-files/jrss.Overview.RootResources.json.png
differ
diff --git
a/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/doc-files/jrss.Overview.RootResources.png
b/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/doc-files/jrss.Overview.RootResources.png
new file mode 100644
index 000000000..3d860c2dc
Binary files /dev/null and
b/juneau-doc/docs/Topics/09.juneau-rest-server-springboot/doc-files/jrss.Overview.RootResources.png
differ
diff --git
a/juneau-examples/juneau-examples-rest-springboot/src/main/java/org/apache/juneau/examples/rest/springboot/App.java
b/juneau-examples/juneau-examples-rest-springboot/src/main/java/org/apache/juneau/examples/rest/springboot/App.java
index ca603ee1a..3351de7c8 100644
---
a/juneau-examples/juneau-examples-rest-springboot/src/main/java/org/apache/juneau/examples/rest/springboot/App.java
+++
b/juneau-examples/juneau-examples-rest-springboot/src/main/java/org/apache/juneau/examples/rest/springboot/App.java
@@ -70,7 +70,7 @@ public class App {
*/
@Bean
public HelloWorldResource getHelloWorldResource() {
- return new HelloWorldResource("Hello Spring user!");
+ return new HelloWorldResource();
}
/**
diff --git
a/juneau-examples/juneau-examples-rest-springboot/src/main/java/org/apache/juneau/examples/rest/springboot/HelloWorldResource.java
b/juneau-examples/juneau-examples-rest-springboot/src/main/java/org/apache/juneau/examples/rest/springboot/HelloWorldResource.java
index e82942e19..8a19c649b 100644
---
a/juneau-examples/juneau-examples-rest-springboot/src/main/java/org/apache/juneau/examples/rest/springboot/HelloWorldResource.java
+++
b/juneau-examples/juneau-examples-rest-springboot/src/main/java/org/apache/juneau/examples/rest/springboot/HelloWorldResource.java
@@ -12,8 +12,6 @@
//
***************************************************************************************************************************
package org.apache.juneau.examples.rest.springboot;
-import java.util.*;
-
import javax.inject.*;
import org.apache.juneau.html.annotation.*;
@@ -44,42 +42,16 @@ import org.apache.juneau.rest.servlet.*;
)
public class HelloWorldResource extends BasicRestObject implements
BasicUniversalConfig {
- private final String message;
-
- /**
- * Optional message provider that can be injected into this object.
- */
@Inject
- private Optional<HelloWorldMessageProvider> messageProvider;
-
- /**
- * Default constructor.
- * <p>
- * Used by default if bean cannot be found in the Spring application
context.
- */
- public HelloWorldResource() {
- this("Hello world!");
- }
-
- /**
- * Constructor.
- *
- * @param message The message to display.
- */
- public HelloWorldResource(String message) {
- this.message = message;
- }
+ private HelloWorldMessageProvider messageProvider;
/**
* GET request handler.
*
* @return A simple Hello-World message.
*/
- @RestGet(path="/*", summary="Responds with \"Hello world!\"")
+ @RestGet(path="/*", summary="Responds with injected message")
public String sayHello() {
- String message = this.message;
- if (messageProvider != null && messageProvider.isPresent())
- message = messageProvider.get().get();
- return message;
+ return messageProvider.get();
}
}
diff --git
a/juneau-examples/juneau-examples-rest-springboot/src/main/java/org/apache/juneau/examples/rest/springboot/RootResources.java
b/juneau-examples/juneau-examples-rest-springboot/src/main/java/org/apache/juneau/examples/rest/springboot/RootResources.java
index d24eb65c1..ac76a6104 100644
---
a/juneau-examples/juneau-examples-rest-springboot/src/main/java/org/apache/juneau/examples/rest/springboot/RootResources.java
+++
b/juneau-examples/juneau-examples-rest-springboot/src/main/java/org/apache/juneau/examples/rest/springboot/RootResources.java
@@ -33,7 +33,6 @@ import org.apache.juneau.serializer.annotation.*;
* @serial exclude
*/
@Rest(
- path="/*",
title="Root resources",
description="Example of a router resource page.",
children={
@@ -59,8 +58,9 @@ import org.apache.juneau.serializer.annotation.*;
"<div class='text'>",
" <p>This is an example of a 'router' page that serves as
a jumping-off point to child resources.</p>",
" <p>Resources can be nested arbitrarily deep through
router pages.</p>",
- " <p>Note the <span class='link'>options</span> link
provided that lets you see the generated swagger doc for this page.</p>",
- " <p>Also note the <span class='link'>sources</span> link
on these pages to view the source code for the page.</p>",
+ " <p>Note the <span class='link'>API</span> link provided
that lets you see the generated swagger doc for this page.</p>",
+ " <p>Also note the <span class='link'>STATS</span> link
that provides basic usage statistics.</p>",
+ " <p>Also note the <span class='link'>SOURCE</span> link
on these pages to view the source code for the page.</p>",
" <p>All content on pages in the UI are serialized POJOs.
In this case, it's a serialized array of beans with 2 properties, 'name' and
'description'.</p>",
" <p>Other features (such as this aside) are added
through annotations.</p>",
"</div>"
