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 5e9a0e5 Javadoc updates.
5e9a0e5 is described below
commit 5e9a0e57d0fb6d16db6e18de71f4a3771dab1624
Author: JamesBognar <jamesbog...@apache.org>
AuthorDate: Tue Feb 6 11:34:02 2018 -0500
Javadoc updates.
---
.../doc-files/MicroserviceServer.Building.1.png | Bin
.../doc-files/MicroserviceServer.Building.2.png | Bin
.../doc-files/MicroserviceServer.Installing.1.png | Bin
.../doc-files/MicroserviceServer.Installing.2.png | Bin
.../doc-files/MicroserviceServer.Installing.3.png | Bin
.../doc-files/MicroserviceServer.Installing.4.png | Bin
.../doc-files/MicroserviceServer.Installing.5.png | Bin
.../doc-files/MicroserviceServer.Installing.6.png | Bin
.../MicroserviceServer.ResourceClasses.1.png | Bin
juneau-doc/src/main/javadoc/overview.html | 1138 ++++++++++++++++++--
10 files changed, 1048 insertions(+), 90 deletions(-)
diff --git
a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/build1.png
b/juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Building.1.png
similarity index 100%
rename from
juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/build1.png
rename to
juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Building.1.png
diff --git
a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/build2.png
b/juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Building.2.png
similarity index 100%
rename from
juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/build2.png
rename to
juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Building.2.png
diff --git
a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions1.png
b/juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Installing.1.png
similarity index 100%
rename from
juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions1.png
rename to
juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Installing.1.png
diff --git
a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions2.png
b/juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Installing.2.png
similarity index 100%
rename from
juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions2.png
rename to
juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Installing.2.png
diff --git
a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions3.png
b/juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Installing.3.png
similarity index 100%
rename from
juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions3.png
rename to
juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Installing.3.png
diff --git
a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions4.png
b/juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Installing.4.png
similarity index 100%
rename from
juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions4.png
rename to
juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Installing.4.png
diff --git
a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions5.png
b/juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Installing.5.png
similarity index 100%
rename from
juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions5.png
rename to
juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Installing.5.png
diff --git
a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions6.png
b/juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Installing.6.png
similarity index 100%
rename from
juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions6.png
rename to
juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.Installing.6.png
diff --git
a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/helloworld1.png
b/juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.ResourceClasses.1.png
similarity index 100%
rename from
juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/helloworld1.png
rename to
juneau-doc/src/main/javadoc/doc-files/MicroserviceServer.ResourceClasses.1.png
diff --git a/juneau-doc/src/main/javadoc/overview.html
b/juneau-doc/src/main/javadoc/overview.html
index 864c4a8..b81452e 100644
--- a/juneau-doc/src/main/javadoc/overview.html
+++ b/juneau-doc/src/main/javadoc/overview.html
@@ -248,6 +248,29 @@
<li><p><a class='doclink'
href='#juneau-rest-client.Other'>Other Useful Methods</a></p>
</ol>
<li><p><a class='doclink'
href='#juneau-microservice-server'><i>juneau-microservice-server</i></a></p>
+ <ol>
+ <li><p><a class='doclink'
href='#juneau-microservice-server.Introduction'>Microservice
Introduction</a></p>
+ <li><p><a class='doclink'
href='#juneau-microservice-server.GettingStarted'>Getting Started</a></p>
+ <ol>
+ <li><p><a class='doclink'
href='#juneau-microservice-server.Installing'>Installing in Eclipse</a></p>
+ <li><p><a class='doclink'
href='#juneau-microservice-server.Running'>Running in Eclipse</a></p>
+ <li><p><a class='doclink'
href='#juneau-microservice-server.Building'>Building and Running from
Command-Line</a></p>
+ </ol>
+ <li><p><a class='doclink'
href='#juneau-microservice-server.Manifest'>Manifest File</a></p>
+ <ol>
+ <li><p><a class='doclink'
href='#juneau-microservice-server.ManifestApi'>Manifest API</a></p>
+ </ol>
+ <li><p><a class='doclink'
href='#juneau-microservice-server.ConfigFile'>Config File</a></p>
+ <ol>
+ <li><p><a class='doclink'
href='#juneau-microservice-server.ConfigFileApi'>Config File API</a></p>
+ </ol>
+ <li><p><a class='doclink'
href='#juneau-microservice-server.ResourceClasses'>Resource Classes</a></p>
+ <li><p><a class='doclink'
href='#juneau-microservice-server.PredefinedResourceClasses'>Predefined
Resource Classes</a></p>
+ <li><p><a class='doclink'
href='#juneau-microservice-server.RestMicroservice'>RestMicroservice</a></p>
+ <ol>
+ <li><p><a class='doclink'
href='#juneau-microservice-server.ExtendingRestMicroservice'>Extending
RestMicroservice</a></p>
+ </ol>
+ </ol>
<li><p><a class='doclink'
href='#juneau-microservice-template'><i>juneau-microservice-template</i></a></p>
<li><p><a class='doclink'
href='#juneau-examples-core'><i>juneau-examples-core</i></a></p>
<li><p><a class='doclink'
href='#juneau-examples-rest'><i>juneau-examples-rest</i></a></p>
@@ -4831,22 +4854,19 @@
{@link
org.apache.juneau.rest.RestServlet org.apache.juneau.rest.RestServlet}
<br>Contains all the main logic.
<ul>
- <li class='jac'>
- {@link
org.apache.juneau.rest.RestServletDefault
org.apache.juneau.rest.RestServletDefault}
+ <li class='jac'>{@link
org.apache.juneau.rest.RestServletDefault
org.apache.juneau.rest.RestServletDefault}
<br>Provides a
default set of serializers, parsers, options page, stylesheet, and other common
settings.
<br><b>Developers will typically subclass this when creating REST resources in
JEE environments.</b>
<ul>
- <li
class='jac'>
-
{@link org.apache.juneau.microservice.Resource
org.apache.juneau.microservice.Resource}
-
<br>Subclass intended to be used in REST microservices.
+ <li
class='jac'>{@link org.apache.juneau.microservice.Resource
org.apache.juneau.microservice.Resource}
+
<br>Identical to <l>RestServletDefault</l> but provides support for
<code>$ARGS</code> and <code>$MF</code> variables.
<br><b>Developers will typically subclass this when creating microservices.</b>
- <li
class='jac'>
-
{@link org.apache.juneau.rest.RestServletGroupDefault
org.apache.juneau.rest.RestServletGroupDefault}
+ <li
class='jac'>{@link org.apache.juneau.rest.RestServletGroupDefault
org.apache.juneau.rest.RestServletGroupDefault}
<br>A default implementation for "router" pages.
<ul>
-
<li class='jac'>
-
{@link org.apache.juneau.microservice.ResourceGroup
org.apache.juneau.microservice.ResourceGroup}
-
<br>Subclass intended to be used in REST microservices.
+
<li class='jac'>{@link org.apache.juneau.microservice.ResourceGroup
org.apache.juneau.microservice.ResourceGroup}
+
<br>Identical to <l>RestServletGroupDefault</l> but provides support
for <code>$ARGS</code> and <code>$MF</code> variables.
+
<br><b>Developers will typically subclass this when creating
microservice groups.</b>
</ul>
</li>
</ul>
@@ -4978,11 +4998,18 @@
<js>"<h2>$R{methodSummary,resourceDescription}</h2>"</js>,
<js>"<a
href='http://juneau.apache.org'><img src='$U{servlet:/htdocs/juneau.png}'
style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/></a>"</js>
},
+ navlinks={
+ <js>"up: request:/.."</js>,
+ <js>"options: servlet:/?method=OPTIONS"</js>
+ },
stylesheet=<js>"servlet:/styles/light.css"</js>,
head={
<js>"<link rel='icon'
href='$U{servlet:/htdocs/juneau.png}'/>"</js>
}
),
+
+ <jc>// Optional external configuration file.</jc>
+ config=<js>"$S{juneau.configFile}"</js>,
<jc>// These are static files that are served up by the servlet
under the specified sub-paths.
// For example, "/servletPath/htdocs/javadoc.css" resolves to
the file "[servlet-package]/htdocs/javadoc.css"</jc>
@@ -9329,7 +9356,7 @@
<h5 class='section'>See Also:</h5>
<ul>
- <li class='jf'>{@link org.apache.juneau.dto.LinkString}
+ <li class='jc'>{@link org.apache.juneau.dto.LinkString}
</ul>
</div>
@@ -10111,7 +10138,8 @@
<div class='topic'>
<p>
One issue with REST (and HTTP in general) is that the
HTTP response code must be set as a header before the
- body of the request is sent. This can be problematic
when REST calls invoke long-running processes, pipes
+ body of the request is sent.
+ <br>This can be problematic when REST calls invoke
long-running processes, pipes
the results through the connection, and then fails
after an HTTP 200 has already been sent.
</p>
<p>
@@ -10150,7 +10178,7 @@
These convenience methods are specialized methods that
use the
{@link
org.apache.juneau.rest.client.RestCall#responsePattern(ResponsePattern)} method
which uses regular
expression matching against the response body.
- This method can be used to search for arbitrary
patterns in the response body.
+ <br>This method can be used to search for arbitrary
patterns in the response body.
</p>
<p>
The following example shows how to use a response
pattern finder to find and capture patterns for
@@ -10163,7 +10191,7 @@
<jk>final</jk> List<String> yList = <jk>new</jk>
ArrayList<String>();
String responseText = restClient.doGet(<jsf>URL</jsf>)
- .addResponsePattern(
+ .responsePattern(
<jk>new</jk> ResponsePattern(<js>"x=(\\d+)"</js>) {
<ja>@Override</ja>
<jk>public void</jk> onMatch(RestCall restCall,
Matcher m) <jk>throws</jk> RestCallException {
@@ -10175,7 +10203,7 @@
}
}
)
- .addResponsePattern(
+ .responsePattern(
<jk>new</jk> ResponsePattern(<js>"y=(\\S+)"</js>) {
<ja>@Override</ja>
<jk>public void</jk> onMatch(RestCall restCall,
Matcher m) <jk>throws</jk> RestCallException {
@@ -10192,8 +10220,8 @@
<p>
Using response patterns does not affect the
functionality of any of the other methods
used to retrieve the response such as {@link
org.apache.juneau.rest.client.RestCall#getResponseAsString()}
- or {@link
org.apache.juneau.rest.client.RestCall#getResponse(Class)}.<br>
- HOWEVER, if you want to retrieve the entire text of the
response from inside the match methods,
+ or {@link
org.apache.juneau.rest.client.RestCall#getResponse(Class)}.
+ <br>HOWEVER, if you want to retrieve the entire text of
the response from inside the match methods,
use {@link
org.apache.juneau.rest.client.RestCall#getCapturedResponse()} since this method
will not absorb
the response for those other methods.
</p>
@@ -10233,7 +10261,7 @@
<p>
Under-the-covers, this is simply a shortcut for adding
the {@link org.apache.juneau.rest.client.RestCallLogger#DEFAULT}
interceptor to the client.
- This causes the following output to be generated by the
Java <code>org.apache.juneau.rest.client</code>
+ <br>This causes the following output to be generated by
the Java <code>org.apache.juneau.rest.client</code>
logger at <jsf>WARNING</jsf> level:
</p>
<p class='bcode'>
@@ -10288,7 +10316,7 @@
<p>
Use the {@link
org.apache.juneau.rest.client.RestClientBuilder#logTo(Level,Logger)} and
{@link
org.apache.juneau.rest.client.RestCall#logTo(Level,Logger)} methods to log HTTP
calls.
- These methods will cause the HTTP request and response
headers and body to be logged to the specified logger.
+ <br>These methods will cause the HTTP request and
response headers and body to be logged to the specified logger.
</p>
<h5 class='figure'>Example:</h5>
@@ -10415,12 +10443,12 @@
<div class='topic'>
<p>
Juneau provides the capability of calling methods on
POJOs on a server through client-side proxy interfaces.
- It offers a number of advantages over other similar
remote proxy interfaces, such as being much simpler to
+ <br>It offers a number of advantages over other similar
remote proxy interfaces, such as being much simpler to
use and allowing much more flexibility.
</p>
<p>
Proxy interfaces are retrieved using the {@link
org.apache.juneau.rest.client.RestClient#getRemoteableProxy(Class)}
- method.
+ <br>method.
The remoteable servlet is a specialized subclass of
{@link org.apache.juneau.rest.RestServlet} that
provides a full-blown REST interface for calling
interfaces remotely.
</p>
@@ -10463,9 +10491,9 @@
</ul>
<p>
One significant feature is that the remoteable services
servlet is a full-blown REST interface.
- Therefore, in cases where the interface classes are not
available on the client side, the same method calls
+ <br>Therefore, in cases where the interface classes are
not available on the client side, the same method calls
can be made through pure REST calls.
- This can also aid significantly in debugging since
calls to the remoteable service can be called directly
+ <br>This can also aid significantly in debugging since
calls to the remoteable service can be called directly
from a browser with no code involved.
</p>
</div>
@@ -10486,7 +10514,7 @@
<p>
The {@link
org.apache.juneau.rest.client.RestClientBuilder#set(String,Object)} method can
be used to
set serializer and parser properties.
- For example, if you're parsing a response into POJOs
and you want to ignore fields that aren't on the
+ <br>For example, if you're parsing a response into
POJOs and you want to ignore fields that aren't on the
POJOs, you can use the {@link
org.apache.juneau.BeanContext#BEAN_ignoreUnknownBeanProperties} property.
</p>
<p class='bcode'>
@@ -10500,7 +10528,7 @@
<p>
The {@link
org.apache.juneau.rest.client.RestCall#retryable(int,long,RetryOn)} method can
be used to
automatically retry requests on failures.
- This can be particularly useful if you're attempting to
connect to a REST resource that may be in the
+ <br>This can be particularly useful if you're
attempting to connect to a REST resource that may be in the
process of still initializing.
</p>
<p class='bcode'>
@@ -10520,86 +10548,996 @@
<h5 class='figure'>Maven Dependency</h5>
<p class='bcode' style='width:500px;'>
-<xt><dependency></xt>
- <xt><groupId></xt>org.apache.juneau<xt></groupId></xt>
-
<xt><artifactId></xt>juneau-microservice-server<xt></artifactId></xt>
- <xt><version></xt>7.0.0<xt></version></xt>
-<xt></dependency></xt>
+ <xt><dependency></xt>
+
<xt><groupId></xt>org.apache.juneau<xt></groupId></xt>
+
<xt><artifactId></xt>juneau-microservice-server<xt></artifactId></xt>
+ <xt><version></xt>7.0.0<xt></version></xt>
+ <xt></dependency></xt>
</p>
<h5 class='figure'>Java Library</h5>
<p class='bcode' style='width:500px;'>
-juneau-microservice-server-7.0.0.jar
+ juneau-microservice-server-7.0.0.jar
</p>
<h5 class='figure'>OSGi Module</h5>
<p class='bcode' style='width:500px;'>
-org.apache.juneau.microservice.server_7.0.0.jar
+ org.apache.juneau.microservice.server_7.0.0.jar
</p>
<p>
- The <code>juneau-microservice-server</code> library consists of
the following classes used for constructing
- stand-alone microservices as executable jars or inside docker
containers:
+ Juneau Microservice is an API for creating stand-alone
executable jars that can be used to
+ start lightweight configurable REST interfaces with all the
power of the Juneau REST server and client APIs.
</p>
- <ul class='doctree'>
- <li class='jac'>
- {@link org.apache.juneau.microservice.Microservice}
- - Defines basic lifecycle methods for microservices in
general.
- <ul>
- <li class='jc'>
- {@link
org.apache.juneau.microservice.RestMicroservice}
- - Defines additional lifecycle methods
for REST microservices.
- <br>Starts up an externally-configured
Jetty server, registers servlets, and sets up
- other features such as logging.
+
+ <!--
===========================================================================================================
-->
+ <a id="juneau-microservice-server.Introduction"></a>
+ <h3 class='topic' onclick='toggle(this)'>10.1 - Microservice
Introduction</h3>
+ <div class='topic'>
+ <p>
+ The Microservice API consists of a combination of the
Juneau Core, Server, and Client APIs and an embedded
+ Eclipse Jetty Servlet Container.
+ <br>It includes all libraries needed to execute in a
Java 1.6+ environment.
+ </p>
+ <p>
+ Features include:
+ </p>
+ <ul class='spaced-list'>
+ <li>
+ An out-of-the-box zipped Eclipse project to get
started quickly.
+ <li>
+ Packaged as a simple executable jar and
configuration file.
+ <li>
+ All the power of the Juneau Cloud Tools for
defining REST servlets and clients with the ability to
+ serialize and parse POJOs as HTML, JSON, XML,
RDF, URL-Encoding, and others.
+ <li>
+ An extensible API that allows you to hook into
various lifecycle events.
+ <li>
+ Simple-to-use APIs for accessing manifest file
entries, command-line arguments, and external configuration
+ file properties.
+ <li>
+ Predefined REST resources for configuring
microservice and accessing log files.
+ </ul>
+ <p>
+ The <code>juneau-microservice-server</code> library
consists of the following classes:
+ </p>
+ <ul class='doctree'>
+ <li class='jac'>
+ {@link
org.apache.juneau.microservice.Microservice}
+ - Defines basic lifecycle methods for
microservices in general.
+ <ul>
+ <li class='jc'>
+ {@link
org.apache.juneau.microservice.RestMicroservice}
+ - Defines additional lifecycle
methods for REST microservices.
+ <br>Starts up an
externally-configured Jetty server, registers servlets, and sets up
+ other features such as logging.
+ </ul>
+ <li class='jc'>
+ {@link org.apache.juneau.microservice.Resource}
+ - A subclass of <code>RestServletDefault</code>
with support for manfest-file and args variables
+ and configured to use the external INI file.
+ <li class='jc'>
+ {@link
org.apache.juneau.microservice.ResourceGroup}
+ - A subclass of
<code>RestServletGroupDefault</code> with support for manfest-file and args
variables
+ and configured to use the external INI file.
+ </ul>
+ </div>
+
+ <!--
===========================================================================================================
-->
+ <a id="juneau-microservice-server.GettingStarted"></a>
+ <h3 class='topic' onclick='toggle(this)'>10.2 - Getting Started</h3>
+ <div class='topic'>
+ <p>
+ The <l>microservice-project.zip</l> file is a zipped
eclipse project that includes everything you
+ need to create a REST microservice in an Eclipse
workspace.
+ </p>
+
+ <!--
===========================================================================================================
-->
+ <a id="juneau-microservice-server.Installing"></a>
+ <h4 class='topic' onclick='toggle(this)'>10.2.1 - Installing in
Eclipse</h4>
+ <div class='topic'>
+ <p>
+ Follow these instructions to create a new
template project in Eclipse.
+ </p>
+ <ol class='spaced-list'>
+ <li>
+ Download the latest
microservice-project zip file (e.g. <l>microservice-project-5.2.zip</l>).
+ <li>
+ In your Eclipse workspace, go to
<b>File->Import->General->Existing Projects into Workspace</b>
+ and click <b>Next</b>.
+ <br><br>
+ <img class='bordered'
src="doc-files/MicroserviceServer.Installing.1.png">
+ <li>
+ Select the zip file and click
<b>Finish</b>.
+ <br><br>
+ <img class='bordered'
src="doc-files/MicroserviceServer.Installing.2.png">
+ <li>
+ In your workspace, you should now see
the following project:
+ <br><br>
+ <img class='bordered'
src="doc-files/MicroserviceServer.Installing.3.png">
+ </ol>
+ <p>
+ The important elements in this project are:
+ </p>
+ <ul class='spaced-list'>
+ <li>
+ <l>META-INF/MANIFEST.MF</l> - The
manifest file.
+ <br>This defines the entry point,
classpath, top-level REST resources, and location of external
+ configuration file.
+ <br><br>
+ <p class='bcode'>
+ <mk>Main-Class</mk>: org.apache.juneau.microservice.RestMicroservice
+ <mk>Rest-Resources</mk>:
+ org.apache.juneau.microservice.sample.RootResources
+ <mk>Main-ConfigFile</mk>: microservice.cfg
+ <mk>Class-Path</mk>:
+ lib/commons-codec-1.9.jar
+ lib/commons-io-1.2.jar
+ lib/commons-logging-1.1.1.jar
+ lib/httpclient-4.5.jar
+ lib/httpcore-4.4.1.jar
+ lib/httpmime-4.5.jar
+ lib/javax.servlet-api-3.0.jar
+ lib/jetty-all-8.1.0.jar
+ lib/juneau-all-5.2.jar
+ lib/org.apache.commons.fileupload_1.3.1.jar
+ </p>
+ <li>
+ <l>RestMicroservice.java</l> - The
application class.
+ <br>This is a specialized microservice
in Juneau for exposing REST servlets.
+ <li>
+ <l>RootResources.java</l> - The
top-level REST resource.
+ <br>This class routes HTTP requests to
child resources:
+ <br><br>
+ <p class='bcode'>
+ <jd>/**
+ * Root microservice page.
+ */</jd>
+ <ja>@RestResource</ja>(
+ path=<js>"/"</js>,
+ title=<js>"Juneau Microservice Template"</js>,
+ description=<js>"Template for creating REST microservices"</js>,
+ properties={
+ <ja>@Property</ja>(name=<jsf>HTMLDOC_navlinks</jsf>,
value=<js>"{options:'?method=OPTIONS'}"</js>)
+ },
+ children={
+ HelloWorldResource.<jk>class</jk>,
+ ConfigResource.<jk>class</jk>,
+ LogsResource.<jk>class</jk>
+ }
+ )
+ <jk>public class</jk> RootResources <jk>extends</jk> ResourceGroup {
+ <jc>// No actual code!</jc>
+ }
+ </p>
+ <li>
+ <l>microservice.cfg</l> - The external
configuration file.
+ <br>A deceivingly simple yet powerful
INI-style configuration file:
+ <br><br>
+ <p class='bcode'>
+
<cc>#================================================================================
+ # Basic configuration file for SaaS microservices
+ # Subprojects can use this as a starting point.
+
#================================================================================</cc>
+
+
<cc>#================================================================================
+ # REST settings
+
#================================================================================</cc>
+ <cs>[REST]</cs>
+
+ <cc># The HTTP port number to use.
+ # Default is Rest-Port setting in manifest file, or 8000.</cc>
+ <ck>port</ck> = <cv>10000</cv>
+ ...
+ </p>
</ul>
- <li class='jc'>
- {@link org.apache.juneau.microservice.Resource}
- - A subclass of <code>RestServletDefault</code> with
support for manfest-file and args variables
- and configured to use the external INI file.
- <li class='jc'>
- {@link org.apache.juneau.microservice.ResourceGroup}
- - A subclass of <code>RestServletGroupDefault</code>
with support for manfest-file and args variables
- and configured to use the external INI file.
- </ul>
- <p>
- The following predefined resource classes are also provided for
easy inclusion into your microservice:
+ <p>
+ At this point, you're ready to start the
microservice from your workspace.
+ </p>
+ </div>
+
+ <!--
===========================================================================================================
-->
+ <a id="juneau-microservice-server.Running"></a>
+ <h4 class='topic' onclick='toggle(this)'>10.2.2 - Running in
Eclipse</h4>
+ <div class='topic'>
+ <p>
+ The <l>microservice-project.launch</l> file is
already provided to allow you to quickly start
+ your new microservice.
+ </p>
+ <p>
+ Go to <b>Run->Run Configurations->Java
Application->microservice-project</b> and click <b>Run</b>.
+ </p>
+ <img class='bordered'
src="doc-files/MicroserviceServer.Installing.4.png">
+ <p>
+ In your console view, you should see the
following output:
+ </p>
+ <img class='bordered'
src="doc-files/MicroserviceServer.Installing.5.png">
+ <p>
+ Now open your browser and point to
<l>http://localhost:10000</l>.
+ You should see the following:
+ </p>
+ <img class='bordered'
src="doc-files/MicroserviceServer.Installing.6.png">
+ <p>
+ You have started a REST interface on port 10000.
+ </p>
+ </div>
+
+ <!--
===========================================================================================================
-->
+ <a id="juneau-microservice-server.Building"></a>
+ <h4 class='topic' onclick='toggle(this)'>10.2.3 - Building and
Running from Command-Line</h4>
+ <div class='topic'>
+ <p>
+ The <l>build.xml</l> file is a very basic ANT
script for creating your microservice
+ as an executable jar.
+ </p>
+ <p>
+ To build your microservice, right-click on
<l>build.xml</l> and select <b>Run As->Ant Build</b>.
+ Once complete (which should only take about 1
second), if you refresh your project, you should see the
+ following new directory:
+ </p>
+ <img class='bordered'
src='doc-files/MicroserviceServer.Building.1.png'>
+ <p>
+ If you open up a command prompt in the
<l>build/microservice</l> folder, you can start your microservice as
+ follows:
+ </p>
+ <img class='bordered'
src='doc-files/MicroserviceServer.Building.2.png'>
+ <p>
+ If you get this error message: <code
class='snippet'>java.net.BindException: Address already in use</code>,
+ then this microservice is already running
elsewhere and so it cannot bind to port 10000.
+ </p>
+ </div>
+
+ </div>
+
+ <!--
===========================================================================================================
-->
+ <a id="juneau-microservice-server.Manifest"></a>
+ <h3 class='topic' onclick='toggle(this)'>10.3 - Manifest File</h3>
+ <div class='topic'>
+ <p>
+ The <l>META-INF/MANIFEST.MF</l> file is used to
describe the microservice.
+ If you open it, you'll see the following:
+ </p>
+ <p class='bcode'>
+ <mk>Main-Class</mk>:
<mv>org.apache.juneau.microservice.RestMicroservice</mv>
+ <mk>Rest-Resources</mk>:
+ <mv>org.apache.juneau.microservice.sample.RootResources</mv>
+ <mk>Main-ConfigFile</mk>: <mv>microservice.cfg</mv>
+ <mk>Class-Path</mk>:
+ <mv>lib/commons-codec-1.9.jar
+ lib/commons-io-1.2.jar
+ lib/commons-logging-1.1.1.jar
+ lib/httpclient-4.5.jar
+ lib/httpcore-4.4.1.jar
+ lib/httpmime-4.5.jar
+ lib/javax.servlet-api-3.0.jar
+ lib/jetty-all-8.1.0.jar
+ lib/juneau-all-5.2.jar
+ lib/org.apache.commons.fileupload_1.3.1.jar</mv>
+ </p>
+ <p>
+ The <mk>Main-Class</mk> entry is the standard manifest
entry describing the entry point for the executable jar.
+ <br>In most cases, this value will always be
<l>org.apache.juneau.microservice.RestMicroservice</l>.
+ <br>However, it is possible to extend this class or
implement your own microservice, in which case you'll need
+ to modify this value to point to the new class.
+ </p>
+ <p>
+ The <mk>Rest-Resources</mk> entry is a comma-delimited
list of REST resources.
+ <br>These are classes that subclass from either {@link
org.apache.juneau.microservice.Resource} or
+ {@link org.apache.juneau.microservice.ResourceGroup}.
+ <br>This is a specialized entry when using
<l>org.apache.juneau.microservice.RestMicroservice</l>.
+ <br>In most cases, you'll want to specify a single
top-level "grouping" REST resource mapped to <l>"/"</l> that
+ extends from {@link
org.apache.juneau.microservice.ResourceGroup} so that you can define multiple
child
+ resources.
+ <br>In this case, we're pointing to a resource defined
in our project:
+
<l>org.apache.juneau.microservice.sample.RootResources</l>.
+ </p>
+ <p>
+ The <mk>Main-ConfigFile</mk> entry points to the
location of an external configuration file for our microservice.
+ </p>
+ <p>
+ The <mk>Class-Path</mk> entry is the standard manifest
file entry.
+ <br>However, if you need to add extra libraries to your
microservice, you'll need to copy them into your <l>lib</l>
+ directory and add them to the classpath here.
+ </p>
+ <p>
+ Other manifest file entries are also provided:
+ </p>
+ <ul class='spaced-list'>
+ <li>
+ <mk>Rest-Port</mk> - The HTTP port to use.
Default is <l>10000</l>.
+ <li>
+ <mk>Rest-ContextPath</mk> - The servlet context
path. Default is <l>"/"</l>.
+ <li>
+ <mk>Rest-AuthType</mk> - Authentication support.
+ <br>Possible values are <l>"NONE"</l> and
<l>"BASIC"</l>.
+ <br>Default is <l>"NONE"</l>.
+ <br>Used with the following additional settings:
+ <ul>
+ <li><mk>Rest-LoginUser</mk>
+ <li><mk>Rest-LoginPassword</mk>
+ <li><mk>Rest-AuthRealm</mk>
+ </ul>
+ </ul>
+ <p>
+ In addition to these predefined manifest entries, you
can add your own particular entries to the manifest file
+ and access them through the Manifest API described
next.
+ </p>
+
+ <!--
===========================================================================================================
-->
+ <a id="juneau-microservice-server.ManifestApi"></a>
+ <h4 class='topic' onclick='toggle(this)'>10.3.1 - Manifest
API</h4>
+ <div class='topic'>
+ <p>
+ The {@link
org.apache.juneau.microservice.Microservice#getManifest()} method is a static
method that
+ can be used to retrieve the manifest file as an
{@link org.apache.juneau.ObjectMap}.
+ </p>
+ <p class='bcode'>
+ <jc>// Get Main-Class from manifest file.</jc>
+ String mainClass =
Microservice.<jsm>getManifest</jsm>().getString(<js>"Main-Class"</js>,
<js>"unknown"</js>);
+
+ <jc>// Get Rest-Resources from manifest file.</jc>
+ String[] restResources =
Microservice.<jsm>getManifest</jsm>().getStringArray(<js>"Rest-Resources"</js>);
+ </p>
+ <p>
+ Since this method returns an {@link
org.apache.juneau.ObjectMap}, it's possible to retrieve entries as a
+ wide variety of object types such as java
primitives, arrays, collections, maps, or even POJOs serialized
+ as JSON.
+ </p>
+ </div>
+
+ </div>
+
+ <!--
===========================================================================================================
-->
+ <a id="juneau-microservice-server.ConfigFile"></a>
+ <h3 class='topic' onclick='toggle(this)'>10.4 - Config File</h3>
+ <div class='topic'>
+ <p>
+ The microservice config file is an external INI-style
configuration file that is used to configure
+ your microservice.
+ </p>
+ <p>
+ If you open the <l>microservice.cfg</l> file, you'll
see several predefined sections and settings.
+ </p>
+ <p class='bcode'>
+
<cc>#================================================================================
+ # Basic configuration file for SaaS microservices
+ # Subprojects can use this as a starting point.
+
#================================================================================</cc>
+
+
<cc>#================================================================================
+ # REST settings
+
#================================================================================</cc>
+ <cs>[REST]</cs>
+
+ <cc># The HTTP port number to use.
+ # Can be a comma-delimited list of ports to try.
+ # 0 means try a random port.
+ # Default is Rest-Port setting in manifest file, or 8000.</cc>
+ <ck>port</ck> = <cv>10000</cv>
+
+ <cc># A JSON map of servlet paths to servlet classes.
+ # Example:
+ # resourceMap = {'/*':'com.foo.MyServlet'}
+ # Either resourceMap or resources must be specified.</cc>
+ <ck>resourceMap</ck> =
+
+ <cc># A comma-delimited list of names of classes that extend from
Servlet.
+ # Resource paths are pulled from @RestResource.path() annotation, or
+ # "/*" if annotation not specified.
+ # Example:
+ # resources = com.foo.MyServlet
+ # Default is Rest-Resources in manifest file.
+ # Either resourceMap or resources must be specified.</cc>
+ <ck>resources</ck> =
+
+ <cc># The context root of the Jetty server.
+ # Default is Rest-ContextPath in manifest file, or "/".</cc>
+ <ck>contextPath</ck> =
+
+ <cc># Authentication: NONE, BASIC.</cc>
+ <ck>authType</ck> = <cv>NONE</cv>
+
+ <cc># The BASIC auth username.
+ # Default is Rest-LoginUser in manifest file.</cc>
+ <ck>loginUser</ck> =
+
+ <cc># The BASIC auth password.
+ # Default is Rest-LoginPassword in manifest file.</cc>
+ <ck>loginPassword</ck> =
+
+ <cc># The BASIC auth realm.
+ # Default is Rest-AuthRealm in manifest file.</cc>
+ <ck>authRealm</ck> =
+
+ <cc># Stylesheet to use for HTML views.
+ # The default options are:
+ # - styles/juneau.css
+ # - styles/devops.css
+ # Other stylesheets can be referenced relative to the servlet package
or working
+ # directory.</cc>
+ <ck>stylesheet</ck> = <cv>styles/devops.css</cv>
+
+ <cc># What to do when the config file is saved.
+ # Possible values:
+ # NOTHING - Don't do anything.
+ # RESTART_SERVER - Restart the Jetty server.
+ # RESTART_SERVICE - Shutdown and exit with code '3'.</cc>
+ <ck>saveConfigAction</ck> = <cv>RESTART_SERVER</cv>
+
+ <cc># Enable SSL support.</cc>
+ <ck>useSsl</ck> = <cv>false</cv>
+
+
<cc>#================================================================================
+ # Bean properties on the org.eclipse.jetty.util.ssl.SslSocketFactory
class
+
#--------------------------------------------------------------------------------
+ # Ignored if REST/useSsl is false.
+
#================================================================================</cc>
+ <cs>[REST-SslContextFactory]</cs>
+ <ck>keyStorePath</ck> = <cv>client_keystore.jks</cv>
+ <ck>keyStorePassword*</ck> = <cv>{HRAaRQoT}</cv>
+ <ck>excludeCipherSuites</ck> = <cv>TLS_DHE.*, TLS_EDH.*</cv>
+ <ck>excludeProtocols</ck> = <cv>SSLv3</cv>
+ <ck>allowRenegotiate</ck> = <cv>false</cv>
+
+
<cc>#================================================================================
+ # Logger settings
+ # See FileHandler Java class for details.
+
#================================================================================</cc>
+ <cs>[Logging]</cs>
+
+ <cc># The directory where to create the log file.
+ # Default is "."</cc>
+ <ck>logDir</ck> = <cv>logs</cv>
+
+ <cc># The name of the log file to create for the main logger.
+ # The logDir and logFile make up the pattern that's passed to the
FileHandler
+ # constructor.
+ # If value is not specified, then logging to a file will not be set
up.</cc>
+ <ck>logFile</ck> = <cv>microservice.%g.log</cv>
+
+ <cc># Whether to append to the existing log file or create a new one.
+ # Default is false.</cc>
+ <ck>append</ck> =
+
+ <cc># The SimpleDateFormat format to use for dates.
+ # Default is "yyyy.MM.dd hh:mm:ss".</cc>
+ <ck>dateFormat</ck> =
+
+ <cc># The log message format.
+ # The value can contain any of the following variables:
+ # {date} - The date, formatted per dateFormat.
+ # {class} - The class name.
+ # {method} - The method name.
+ # {logger} - The logger name.
+ # {level} - The log level name.
+ # {msg} - The log message.
+ # {threadid} - The thread ID.
+ # {exception} - The localized exception message.
+ # Default is "[{date} {level}] {msg}%n".</cc>
+ <ck>format</ck> =
+
+ <cc># The maximum log file size.
+ # Suffixes available for numbers.
+ # See ConfigFile.getInt(String,int) for details.
+ # Default is 1M.</cc>
+ <ck>limit</ck> = <cv>10M</cv>
+
+ <cc># Max number of log files.
+ # Default is 1.</cc>
+ <ck>count</ck> = <cv>5</cv>
+
+ <cc># Default log levels.
+ # Keys are logger names.
+ # Values are serialized Level POJOs.</cc>
+ <ck>levels</ck> = <cv>{ org.apache.juneau:'INFO' }</cv>
+
+ <cc># Only print unique stack traces once and then refer to them by a
simple 8 character hash identifier.
+ # Useful for preventing log files from filling up with duplicate stack
traces.
+ # Default is false.</cc>
+ <ck>useStackTraceHashes</ck> = <cv>true</cv>
+
+ <cc># The default level for the console logger.
+ # Default is WARNING.</cc>
+ <ck>consoleLevel</ck> =
+
+
<cc>#================================================================================
+ # System properties
+
#--------------------------------------------------------------------------------
+ # These are arbitrary system properties that are set during startup.
+
#================================================================================</cc>
+ <cs>[SystemProperties]</cs>
+
+ <cc># Configure Jetty for StdErrLog Logging</cc>
+ <ck>org.eclipse.jetty.util.log.class</ck> =
<cv>org.eclipse.jetty.util.log.StrErrLog</cv>
+
+ <cc># Jetty logging level</cc>
+ <ck>org.eclipse.jetty.LEVEL</ck> = <cv>WARN</cv>
+ </p>
+ <ul class='doctree'>
+ <li class='info'>
+ The predefined config file includes all
settings for instructional purposes.
+ <br>In your microservice, you can remove all
lines from your config file that have default values.
+ </ul>
+ <p>
+ Although the config file looks deceptively simple, the
config file API is a very powerful feature with many
+ capabilities, including:
+ </p>
+ <ul class='spaced-list'>
+ <li>
+ The ability to use variables to reference
environment variables, system properties, other config file
+ entries, and a host of other types.
+ <li>
+ The ability to store and retrieve POJOs as JSON.
+ <li>
+ APIs for updating, modifying, and saving
configuration files without losing comments or formatting.
+ <li>
+ Extensive listener APIs.
+ </ul>
+
+ <h5 class='topic'>Examples:</h5>
+ <p class='bcode'>
+ <cc>#--------------------------</cc>
+ <cc># My section</cc>
+ <cc>#--------------------------</cc>
+ <cs>[MySection]</cs>
+
+ <cc># An integer</cc>
+ <ck>anInt</ck> = <cv>1 </cv>
+
+ <cc># A boolean</cc>
+ <ck>aBoolean</ck> = <cv>true </cv>
+
+ <cc># An int array</cc>
+ <ck>anIntArray</ck> = <cv>1,2,3 </cv>
+
+ <cc># A POJO that can be converted from a String</cc>
+ <ck>aURL</ck> = <cv>http://foo </cv>
+
+ <cc># An encoded password</cc>
+ <ck>aPassword*</ck> = <cv>{HRAaRQoT}</cv>
+
+ <cc># A POJO that can be converted from JSON</cc>
+ <ck>aBean</ck> = <cv>{foo:'bar',baz:123}</cv>
+
+ <cc># A system property</cc>
+ <ck>locale</ck> = <cv>$S{java.locale, en_US}</cv>
+
+ <cc># An environment variable</cc>
+ <ck>path</ck> = <cv>$E{PATH, unknown}</cv>
+
+ <cc># A manifest file entry</cc>
+ <ck>mainClass</ck> = <cv>$MF{Main-Class}</cv>
+
+ <cc># Another value in this config file</cc>
+ <ck>sameAsAnInt</ck> = <cv>$C{MySection/anInt}</cv>
+
+ <cc># A command-line argument in the form "myarg=foo"</cc>
+ <ck>myArg</ck> = <cv>$ARG{myarg}</cv>
+
+ <cc># The first command-line argument</cc>
+ <ck>firstArg</ck> = <cv>$ARG{0}</cv>
+
+ <cc># Look for system property, or env var if that doesn't exist, or
command-line arg if that doesn't exist.</cc>
+ <ck>nested</ck> = <cv>$S{mySystemProperty,$E{MY_ENV_VAR,$ARG{0}}}</cv>
+
+ <cc># A POJO with embedded variables</cc>
+ <ck>aBean2</ck> = <cv>{foo:'$ARG{0}',baz:$C{MySection/anInt}}</cv>
+
</p>
- <ul class='doctree'>
- <li class='jc'>{@link
org.apache.juneau.microservice.resources.ConfigResource}
- - View and modify the external INI config file.
- <li class='jc'>{@link
org.apache.juneau.microservice.resources.DirectoryResource}
- - View and modify file system directories.
- <li class='jc'>{@link
org.apache.juneau.microservice.resources.LogsResource}
- - View and control generated log files.
- <li class='jc'>{@link
org.apache.juneau.microservice.resources.SampleRootResource}
- - A sample root resource class to get started from.
- <li class='jc'>{@link
org.apache.juneau.microservice.resources.ShutdownResource}
- - Shutdown and/or restart the JVM.
- </ul>
+ <p class='bcode'>
+ <jc>// Java code for accessing config entries above.</jc>
+ ConfigFile cf = Microservice.<jsm>getConfig</jsm>();
+
+ <jk>int</jk> anInt = cf.getInt(<js>"MySection/anInt"</js>);
+ <jk>boolean</jk> aBoolean =
cf.getBoolean(<js>"MySection/aBoolean"</js>);
+ <jk>int</jk>[] anIntArray = cf.getObject(<jk>int</jk>[].<jk>class</jk>,
<js>"MySection/anIntArray"</js>);
+ URL aURL = cf.getObject(URL.<jk>class</jk>, <js>"MySection/aURL"</js>);
+ String aPassword = cf.getString(<js>"MySection/aPassword"</js>);
+ MyBean aBean = cf.getObject(MyBean.<jk>class</jk>,
<js>"MySection/aBean"</js>);
+ Locale locale = cf.getObject(Locale.<jk>class</jk>,
<js>"MySection/locale"</js>);
+ String path = cf.getString(<js>"MySection/path"</js>);
+ String mainClass = cf.getString(<js>"MySection/mainClass"</js>);
+ <jk>int</jk> sameAsAnInt = cf.getInt(<js>"MySection/sameAsAnInt"</js>);
+ String myArg = cf.getString(<js>"MySection/myArg"</js>);
+ String firstArg = cf.getString(<js>"MySection/firstArg"</js>);
+ </p>
+
+ <!--
===========================================================================================================
-->
+ <a id="juneau-microservice-server.ConfigFileApi"></a>
+ <h4 class='topic' onclick='toggle(this)'>10.4.1 - Config File
API</h4>
+ <div class='topic'>
+ <p>
+ There are 3 primary ways of getting access to
the config file.
+ </p>
+ <ul class='doctree'>
+ <li class='jm'>
+ {@link
org.apache.juneau.microservice.Microservice#getConfig()}
+ - A static method that can be used to
access the config file from anywhere in your application.
+ <br>When using this method, any of the
following variables can be resolved:
+ <ul>
+ <li><l>$S{key},
$S{key,default}</l> - System properties.
+ <li><l>$E{key},
$E{key,default}</l> - Environment variables.
+ <li><l>$C{key},
$C{key,default}</l> - Config file entries.
+ <li><l>$MF{key},
$MF{key,default}</l> - Manifest file entries.
+ <li><l>$ARG{key},
$ARG{key,default}</l> - Command-line arguments.
+ </ul>
+ Additional user-defined variables can
be defined by overriding the
+ {@link
org.apache.juneau.microservice.Microservice#createVarResolver()} method
+ and using the {@link
org.apache.juneau.rest.RestContextBuilder#vars(Class...)} method.
+ <li class='jm'>
+ {@link
org.apache.juneau.rest.RestContext#getConfigFile()}
+ - An instance method to access it from
inside a REST servlet.
+ <br>The following variables are
available in addition to the variables defined above:
+ <ul>
+ <li><l>$I{key},
$I{key,default}</l> - Servlet initialization parameters.
+ </ul>
+
+ <h5 class='figure'>Example usage:</h5>
+ <p class='bcode'>
+ <cc>#-------------------------------</cc>
+ <cc># Properties for MyHelloResource </cc>
+ <cc>#-------------------------------</cc>
+ <cs>[MyHelloResource]</cs>
+ <ck>greeting</ck> = <cv>Hello world!</cv>
+ </p>
+ <p class='bcode'>
+ <ja>@RestResource</ja>(...)
+ <jk>public class</jk> MyHelloResource <jk>extends</jk> Resource {
+ <jc>// Access config file when initializing fields.</jc>
+ <jk>private</jk> String greeting =
getConfig().getString(<js>"MyHelloResource/greeting"</js>);
+
+ <jc>// Or access config file in servlet init method.</jc>
+ <ja>@Override</ja> <jc>/* Servlet */</jc>
+ <jk>public void</jk> init() {
+ String greeting =
getConfig().getString(<js>"MyHelloResource/greeting"</js>);
+ }
+ }
+ </p>
+ <p>
+ Additional user-defined
variables can be defined at this level by adding a
+ {@link
org.apache.juneau.rest.annotation.HookEvent#INIT} hook method
+ and using the {@link
org.apache.juneau.rest.RestContextBuilder#vars(Class...)} method.
+ </p>
+ <li class='jm'>
+ {@link
org.apache.juneau.rest.RestRequest#getConfigFile()}
+ - An instance method to access it from
inside a REST method.
+ <br>The following variables are
available in addition to the variables defined above:
+ <ul>
+ <li><l>$L{key},
$L{key,args}</l> - Localized variables pulled from
+ {@link
org.apache.juneau.rest.RestRequest#getMessage(String, Object...)}.
+ <li><l>$RA{key1,[key2...]}</l>
- Request attribute variables.
+ <li><l>$RF{key1,[key2...]}</l>
- Request form data variables.
+ <li><l>$RH{key1,[key2...]}</l>
- Request header variables.
+ <li><l>$RP{key1,[key2...]}</l>
- Request path variables.
+ <li><l>$RQ{key1,[key2...]}</l>
- Request query parameter variables.
+ <li><l>$R{key1,[key2...]}</l> -
Other request variables.
+ <li><l>$SA{key,mediaType}</l> -
Object returned by {@link
org.apache.juneau.rest.RestRequest#getAttribute(String)} converted to a string
using the serializer registered to handle the specified media type.
+ <li><l>$UE{...}</l> -
URL-Encode the specified value.
+ </ul>
+
+ <h5 class='figure'>Example usage:</h5>
+ <p class='bcode'>
+ <cc>#-----------------------------</cc>
+ <cc># Contents of microservice.cfg </cc>
+ <cc>#-----------------------------</cc>
+ <cs>[MyHelloResource]</cs>
+ <ck>greeting</ck> = <cv>Hello $RP{person}!</cv>
+ <ck>localizedGreeting</ck> = <cv>$L{HelloMessage,$RP{person}}</cv>
+ </p>
+ <p class='bcode'>
+ <cc>#---------------------------------</cc>
+ <cc># Contents of MyHelloResource.java </cc>
+ <cc>#---------------------------------</cc>
+ <ja>@RestResource</ja>(
+ path=<js>"/hello"</js>,
+ messages=<js>"nls/Messages"</js>,
+ ...
+ )
+ <jk>public class</jk> MyHelloResource <jk>extends</jk> Resource {
- <h5 class='toc'>Additional Information -
org.apache.juneau.microservice</h5>
- <ol class='toc'>
- <li><p><a class='doclink'
href='org/apache/juneau/microservice/package-summary.html#Introduction'>Microservice
Introduction</a></p>
- <li><p><a class='doclink'
href='org/apache/juneau/microservice/package-summary.html#GettingStarted'>Getting
Started</a></p>
- <ol>
- <li><p><a class='doclink'
href='org/apache/juneau/microservice/package-summary.html#GettingStarted_Installing'>Installing
in Eclipse</a></p>
- <li><p><a class='doclink'
href='org/apache/juneau/microservice/package-summary.html#GettingStarted_Running'>Running
in Eclipse</a></p>
- <li><p><a class='doclink'
href='org/apache/juneau/microservice/package-summary.html#GettingStarted_Building'>Building
and Running from Command-Line</a></p>
- </ol>
- <li><p><a class='doclink'
href='org/apache/juneau/microservice/package-summary.html#Manifest'>Manifest
File</a></p>
- <ol>
- <li><p><a class='doclink'
href='org/apache/juneau/microservice/package-summary.html#Manifest_API'>Manifest
API</a></p>
- </ol>
- <li><p><a class='doclink'
href='org/apache/juneau/microservice/package-summary.html#ConfigFile'>Config
File</a></p>
- <ol>
- <li><p><a class='doclink'
href='org/apache/juneau/microservice/package-summary.html#ConfigFile_API'>Config
File API</a></p>
- </ol>
- <li><p><a class='doclink'
href='org/apache/juneau/microservice/package-summary.html#ResourceClasses'>Resource
Classes</a></p>
- <li><p><a class='doclink'
href='org/apache/juneau/microservice/package-summary.html#RestMicroservice'>RestMicroservice</a></p>
- <ol>
- <li><p><a class='doclink'
href='org/apache/juneau/microservice/package-summary.html#RestMicroservice_Extending'>Extending
RestMicroservice</a></p>
- </ol>
- </ol>
+ <jd>/** Standard hello message. */</jd>
+ <ja>@RestMethod</ja>(name=<jsf>GET</jsf>,
path=<js>"/{person}"</js>)
+ <jk>public</jk> String sayHello(RestRequest req) {
+ <jk>return</jk>
req.getConfig().getString(<js>"MyHelloResource/greeting"</js>);
+ }
+
+ <jd>/** Hello message in users language. */</jd>
+ <ja>@RestMethod</ja>(name=<jsf>GET</jsf>,
path=<js>"/localized/{person}"</js>)
+ <jk>public</jk> String sayLocalizedHello(RestRequest req) {
+ <jk>return</jk>
req.getConfig().getString(<js>"MyHelloResource/localizedGreeting"</js>);
+ }
+ }
+ </p>
+ <p class='bcode'>
+ <cc>#---------------------------------------</cc>
+ <cc># Contents of nls/Messages_en.properties </cc>
+ <cc>#---------------------------------------</cc>
+ <ck>MyHelloResource.HelloMessage</ck> = <cv>Hello {0}!</cv>
+ </p>
+ <p>
+ Additional user-defined
variables can be defined at this level by overriding the
+ {@link
org.apache.juneau.rest.RestContextBuilder#vars(Class...)} method.
+ </p>
+ </ul>
+ <p>
+ That <l>sayLocalizedHello()</l> example might
need some explanation since there's a lot going on there.
+ <br>Here's what happens when an HTTP call is
made to <l>GET /hello/localized/Bob</l>:
+ </p>
+ <ol class='spaced-list'>
+ <li>
+ The HTTP call matches the <l>/hello</l>
path on the <l>MyHelloResource</l> class.
+ <li>
+ The HTTP call matches the
<l>/localized/{person}</l> path on the <l>sayLocalizedHello()</l> method.
+ <li>
+ The request attribute <l>person</l>
gets assigned the value <l>"Bob"</l>.
+ <li>
+ The call to
<l>req.getConfig().getString("MyHelloResource/localizedGreeting")</l>
+ finds the value
<l>"$L{HelloMessage,$RP{person}}"</l>.
+ <li>
+ The arguments in the <l>$L{}</l>
variable get resolved, resulting in <l>"$L{HelloMessage,Bob}"</l>.
+ <li>
+ The <l>$L{}</l> variable gets resolved
to the message <l>"Hello {0}!"</l> in the localized properties
+ file of the servlet based on the
<l>Accept-Language</l> header on the request.
+ <li>
+ The arguments get replaced in the
message resulting in <l>"Hello Bob!"</l>.
+ <li>
+ The resulting message <l>"Hello
Bob!"</l> is returned as a POJO to be serialized to whatever content
+ type was specified on the <l>Accept</l>
header on the request.
+ </ol>
+ <p>
+ This particular example is needlessly complex,
but it gives an idea of how variables can be used
+ recursively to produce sophisticated results
+ </p>
+ </div>
+
+ </div>
+
+ <!--
===========================================================================================================
-->
+ <a id="juneau-microservice-server.ResourceClasses"></a>
+ <h3 class='topic' onclick='toggle(this)'>10.5 - Resource Classes</h3>
+ <div class='topic'>
+ <p>
+ Now let's take a look at the resource classes
themselves.
+ <br>The top-level page...
+ </p>
+ <img class='bordered'
src='doc-files/MicroserviceServer.Installing.6.png'>
+ <p>
+ ...is generated by this class...
+ <p class='bcode'>
+ <jd>/**
+ * Root microservice page.
+ */</jd>
+ <ja>@RestResource</ja>(
+ path=<js>"/"</js>,
+ title=<js>"Juneau Microservice Template"</js>,
+ description=<js>"Template for creating REST microservices"</js>,
+ properties={
+ <ja>@Property</ja>(name=<jsf>HTMLDOC_navlinks</jsf>,
value=<js>"{options:'?method=OPTIONS'}"</js>)
+ },
+ children={
+ HelloWorldResource.<jk>class</jk>,
+ ConfigResource.<jk>class</jk>,
+ LogsResource.<jk>class</jk>
+ }
+ )
+ <jk>public class</jk> RootResources <jk>extends</jk> ResourceGroup {
+ <jk>private static final long</jk> <jsf>serialVersionUID</jsf>
= 1L;
+ }
+ </p>
+ <ul class='spaced-list'>
+ <li>
+ The </l>label</l> and <l>description</l>
annotations define the titles on the page.
+ <br>These can be globalized using
<l>$L{...}</l> variables, or by defining specially-named properties in the
+ properties file for the resource.
+ <li>
+ In this case, the <l>path</l> annotation
defines the context root of your application since it was
+ not specified in the manifest or config file.
+ <br>Therefore, this resource is mapped to
<l>http://localhost:10000</l>.
+ <li>
+ The <l>children</l> annotation make up the list
of child resources.
+ <br>These child resources can be anything that
extends from <l>Servlet</l>, although usually
+ they will be subclasses of {@link
org.apache.juneau.microservice.Resource} or other resource groups.
+ </ul>
+ <p>
+ If you click the <l>helloWorld</l> link in your
application, you'll get a simple hello world message:
+ </p>
+ <img class='bordered'
src='doc-files/MicroserviceServer.ResourceClasses.1.png'>
+ <p>
+ ...which is generated by this class...
+ </p>
+ <p class='bcode'>
+ <jd>/**
+ * Sample REST resource that prints out a simple "Hello world!" message.
+ */</jd>
+ <ja>@RestResource</ja>(
+ path=<js>"/helloWorld"</js>,
+ title=<js>"Hello World example"</js>,
+ description=<js>"Simplest possible REST resource"</js>
+ )
+ <jk>public class</jk> HelloWorldResource <jk>extends</jk> Resource {
+
+ <jd>/** GET request handler */</jd>
+ <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/*"</js>)
+ <jk>public</jk> String sayHello() {
+ <jk>return</jk> <js>"Hello world!"</js>;
+ }
+ }
+ </p>
+ <p>
+ The {@link org.apache.juneau.microservice.Resource} and
{@link org.apache.juneau.microservice.ResourceGroup}
+ classes are powerful servlets designed specifically for
creating REST APIs using nothing more than serialized
+ and parsed POJOs.
+ </p>
+ </div>
+
+ <!--
===========================================================================================================
-->
+ <a id="juneau-microservice-server.PredefinedResourceClasses"></a>
+ <h3 class='topic' onclick='toggle(this)'>10.6 - Predefined Resource
Classes</h3>
+ <div class='topic'>
+ <p>
+ The following predefined resource classes are also
provided for easy inclusion into your microservice:
+ </p>
+ <ul class='doctree'>
+ <li class='jc'>{@link
org.apache.juneau.microservice.resources.ConfigResource}
+ - View and modify the external INI config file.
+ <li class='jc'>{@link
org.apache.juneau.microservice.resources.DirectoryResource}
+ - View and modify file system directories.
+ <li class='jc'>{@link
org.apache.juneau.microservice.resources.LogsResource}
+ - View and control generated log files.
+ <li class='jc'>{@link
org.apache.juneau.microservice.resources.SampleRootResource}
+ - A sample root resource class to get started
from.
+ <li class='jc'>{@link
org.apache.juneau.microservice.resources.ShutdownResource}
+ - Shutdown and/or restart the JVM.
+ </ul>
+ </div>
+
+ <!--
===========================================================================================================
-->
+ <a id="juneau-microservice-server.RestMicroservice"></a>
+ <h3 class='topic' onclick='toggle(this)'>10.7 - RestMicroservice</h3>
+ <div class='topic'>
+ <p>
+ The {@link
org.apache.juneau.microservice.RestMicroservice} class is the main application
entry-point for REST
+ microservices.
+ </p>
+ <p>
+ The class hierarchy is:
+ </p>
+ <ul class='doctree'>
+ <li class='jac'>
+ {@link
org.apache.juneau.microservice.Microservice}
+ - Abstract class that defines simple start/stop
methods and access to the manifest file, config file, and
+ arguments.
+ <ul>
+ <li class='jc'>
+ {@link
org.apache.juneau.microservice.RestMicroservice}
+ - Specialized microservice for
starting up REST interfaces using Jetty and specifying REST servlets
+ through the manifest file or
config file.
+ </ul>
+ </li>
+ </ul>
+ <p>
+ Refer to the Javadocs for these class for more
information.
+ </p>
+
+ <!--
===========================================================================================================
-->
+ <a
id="juneau-microservice-server.ExtendingRestMicroservice"></a>
+ <h4 class='topic' onclick='toggle(this)'>10.7.1 - Extending
RestMicroservice</h4>
+ <div class='topic'>
+ <p>
+ This example shows how the {@link
org.apache.juneau.microservice.RestMicroservice} class
+ can be extended to implement lifecycle listener
methods or override existing methods.
+ <br>We'll create a new class
<l>com.foo.SampleCustomRestMicroservice</l>.
+ </p>
+ <p>
+ First, the manifest file needs to be modified
to point to our new microservice:
+ </p>
+ <p class='bcode'>
+ <mk>Main-Class:</mk> com.foo.SampleCustomRestMicroservice
+ </p>
+ <p>
+ Then we define the following class:
+ </p>
+ <p class='bcode'>
+ <jd>/**
+ * Sample subclass of a RestMicroservice that provides customized
behavior.
+ * This class must be specified in the Main-Class entry in the manifest
file and optionally
+ * a Main-ConfigFile entry.
+ */</jd>
+ <jk>public class</jk> SampleCustomRestMicroservice <jk>extends</jk>
RestMicroservice {
+
+ <jd>/**
+ * Must implement a main method and call start()!
+ */</jd>
+ <jk>public static void</jk> main(String[] args) <jk>throws</jk>
Exception {
+ <jk>new</jk> SampleCustomRestMicroservice(args).start();
+ }
+
+ <jd>/**
+ * Must implement a constructor!
+ *
+ * <ja>@param</ja> args Command line arguments.
+ * <ja>@throws</ja> Exception
+ */</jd>
+ <jk>public</jk> SampleCustomRestMicroservice(String[] args)
<jk>throws</jk> Exception {
+ <jk>super</jk>(args);
+ }
+
+
<jc>//--------------------------------------------------------------------------------
+ // Methods on Microservice that can be overridden and
customized.
+
//--------------------------------------------------------------------------------</jc>
+
+ <ja>@Override</ja> <jc>/* Microservice */</jc>
+ <jk>protected void</jk> start() <jk>throws</jk> Exception {
+ <jk>super</jk>.start();
+ }
+
+ <ja>@Override</ja> <jc>/* Microservice */</jc>
+ <jk>public void</jk> stop() {
+ <jk>super</jk>.stop();
+ }
+
+ <ja>@Override</ja> <jc>/* Microservice */</jc>
+ <jk>public void</jk> kill() {
+ <jk>super</jk>.kill();
+ }
+
+ <ja>@Override</ja> <jc>/* Microservice */</jc>
+ <jk>public void</jk> onStart() {
+ System.<jsf>err</jsf>.println(<js>"onStart()
called!"</js>);
+ }
+
+ <ja>@Override</ja> <jc>/* Microservice */</jc>
+ <jk>public void</jk> onStop() {
+ System.<jsf>err</jsf>.println(<js>"onStop()
called!"</js>);
+ }
+
+
<jc>//--------------------------------------------------------------------------------
+ // Methods on RestMicroservice that can be overridden and
customized.
+
//--------------------------------------------------------------------------------</jc>
+
+ <ja>@Override</ja> <jc>/* RestMicroservice */</jc>
+ <jk>protected void</jk> initLogging() <jk>throws</jk> Exception
{
+ <jk>super</jk>.initLogging();
+ }
+
+ <ja>@Override</ja> <jc>/* RestMicroservice */</jc>
+ <jk>protected</jk> Server createServer() <jk>throws</jk>
Exception {
+ <jk>return super</jk>.createServer();
+ }
+
+ <ja>@Override</ja> <jc>/* RestMicroservice */</jc>
+ <jk>protected void</jk> startServer() <jk>throws</jk> Exception
{
+ <jk>super</jk>.startServer();
+ }
+
+ <ja>@Override</ja> <jc>/* RestMicroservice */</jc>
+ <jk>protected void</jk> onCreateServer() {
+ System.<jsf>err</jsf>.println(<js>"onCreateServer()
called!"</js>);
+ }
+
+ <ja>@Override</ja> <jc>/* RestMicroservice */</jc>
+ <jk>protected void</jk> onStartServer() {
+ System.<jsf>err</jsf>.println(<js>"onStartServer()
called!"</js>);
+ }
+
+ <ja>@Override</ja> <jc>/* RestMicroservice */</jc>
+ <jk>protected void</jk> onPostStartServer() {
+ System.<jsf>err</jsf>.println(<js>"onPostStartServer()
called!"</js>);
+ }
+
+ <ja>@Override</ja> <jc>/* RestMicroservice */</jc>
+ <jk>protected void</jk> onStopServer() {
+ System.<jsf>err</jsf>.println(<js>"onStopServer()
called!"</js>);
+ }
+
+ <ja>@Override</ja> <jc>/* RestMicroservice */</jc>
+ <jk>protected void</jk> onPostStopServer() {
+ System.<jsf>err</jsf>.println(<js>"onPostStopServer()
called!"</js>);
+ }
+ }
+ </p>
+ </div>
+ </div>
</div>
<!--
===========================================================================================================
-->
@@ -14526,6 +15464,23 @@ org.apache.juneau.microservice.server_7.0.0.jar
without closing the stream.
<br>The {@link
org.apache.juneau.rest.response.DefaultHandler} class now calls
<code>finish()</code>
instead of <code>close()</code> on the stream.
+ <li>
+ Added the following annotations to the {@link
org.apache.juneau.rest.RestServletDefault} class
+ (which were previously defined on the {@link
org.apache.juneau.microservice.Resource} class):
+ <p class='bcode'>
+ <ja>@RestResource</ja>(
+ htmldoc=<ja>@HtmlDoc</ja>(
+ navlinks={
+ <js>"up: request:/.."</js>,
+ <js>"options: servlet:/?method=OPTIONS"</js>
+ },
+
stylesheet=<js>"$C{REST/stylesheet,servlet:/styles/devops.css}"</js>
+ ),
+
+ <jc>// Optional external configuration file.</jc>
+ config=<js>"$S{juneau.configFile}"</js>
+ )
+ </p>
</ul>
<h5 class='topic'>juneau-rest-client</h5>
@@ -14544,6 +15499,9 @@ org.apache.juneau.microservice.server_7.0.0.jar
<li>{@link
org.apache.juneau.rest.client.RestCall#getResponseHeader(String)
getResponseHeader(String)}
<li>{@link
org.apache.juneau.rest.client.RestCall#getResponseCode() getResponseCode()}
</ul>
+ <li>
+ {@link org.apache.juneau.rest.client.RestCall}
and {@link org.apache.juneau.rest.client.RestClient}
+ now implement the <code>Closeable</code>
interface.
</ul>
<h5 class='topic'>Documentation</h5>
--
To stop receiving notification emails like this one, please contact
jamesbog...@apache.org.
