juneau-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jamesbog...@apache.org
Subject [juneau] branch master updated: Javadoc updates.
Date Tue, 06 Feb 2018 16:34:04 GMT
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 <jamesbognar@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>"&lt;h2&gt;$R{methodSummary,resourceDescription}&lt;/h2&gt;"</js>,
 				<js>"&lt;a href='http://juneau.apache.org'&gt;&lt;img src='$U{servlet:/htdocs/juneau.png}' style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/&gt;&lt;/a&gt;"</js>
 			},
+			navlinks={
+				<js>"up: request:/.."</js>,
+				<js>"options: servlet:/?method=OPTIONS"</js>
+			},
 			stylesheet=<js>"servlet:/styles/light.css"</js>,
 			head={
 				<js>"&lt;link rel='icon' href='$U{servlet:/htdocs/juneau.png}'/&gt;"</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&lt;String&gt; yList = <jk>new</jk> ArrayList&lt;String&gt;();
 	
 	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>&lt;dependency&gt;</xt>
-	<xt>&lt;groupId&gt;</xt>org.apache.juneau<xt>&lt;/groupId&gt;</xt>
-	<xt>&lt;artifactId&gt;</xt>juneau-microservice-server<xt>&lt;/artifactId&gt;</xt>
-	<xt>&lt;version&gt;</xt>7.0.0<xt>&lt;/version&gt;</xt>
-<xt>&lt;/dependency&gt;</xt>
+	<xt>&lt;dependency&gt;</xt>
+		<xt>&lt;groupId&gt;</xt>org.apache.juneau<xt>&lt;/groupId&gt;</xt>
+		<xt>&lt;artifactId&gt;</xt>juneau-microservice-server<xt>&lt;/artifactId&gt;</xt>
+		<xt>&lt;version&gt;</xt>7.0.0<xt>&lt;/version&gt;</xt>
+	<xt>&lt;/dependency&gt;</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-&gt;Import-&gt;General-&gt;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-&gt;Run Configurations-&gt;Java Application-&gt;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-&gt;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
jamesbognar@apache.org.

Mime
View raw message