You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2017/09/08 23:21:18 UTC
svn commit: r21538 [4/27] - in /release/incubator/juneau:
juneau-microservice-server/ juneau-microservice-server/.settings/
juneau-microservice-server/src/ juneau-microservice-server/src/main/
juneau-microservice-server/src/main/java/ juneau-microservi...
Added: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/package.html
==============================================================================
--- release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/package.html (added)
+++ release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/package.html Fri Sep 8 23:21:12 2017
@@ -0,0 +1,1038 @@
+<!DOCTYPE HTML>
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ ***************************************************************************************************************************/
+ -->
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <style type="text/css">
+ /* For viewing in Page Designer */
+ @IMPORT url("javadoc.css");
+
+ /* For viewing in REST interface */
+ @IMPORT url("../htdocs/javadoc.css");
+ body {
+ margin: 20px;
+ }
+ </style>
+ <script>
+ /* Replace all @code and @link tags. */
+ window.onload = function() {
+ document.body.innerHTML = document.body.innerHTML.replace(/\{\@code ([^\}]+)\}/g, '<code>$1</code>');
+ document.body.innerHTML = document.body.innerHTML.replace(/\{\@link (([^\}]+)\.)?([^\.\}]+)\}/g, '<code>$3</code>');
+ }
+ </script>
+</head>
+<body>
+<p>Juneau Cloud Microservice API</p>
+
+<script>
+ function toggle(x) {
+ var div = x.nextSibling;
+ while (div != null && div.nodeType != 1)
+ div = div.nextSibling;
+ if (div != null) {
+ var d = div.style.display;
+ if (d == 'block' || d == '') {
+ div.style.display = 'none';
+ x.className += " closed";
+ } else {
+ div.style.display = 'block';
+ x.className = x.className.replace(/(?:^|\s)closed(?!\S)/g , '' );
+ }
+ }
+ }
+</script>
+
+<a id='TOC'></a><h5 class='toc'>Table of Contents</h5>
+<ol class='toc'>
+ <li><p><a class='doclink' href='#Introduction'>Microservice Introduction</a></p>
+ <li><p><a class='doclink' href='#GettingStarted'>Getting Started</a></p>
+ <ol>
+ <li><p><a class='doclink' href='#GettingStarted_Installing'>Installing in Eclipse</a></p>
+ <li><p><a class='doclink' href='#GettingStarted_Running'>Running in Eclipse</a></p>
+ <li><p><a class='doclink' href='#GettingStarted_Building'>Building and Running from Command-Line</a></p>
+ </ol>
+ <li><p><a class='doclink' href='#Manifest'>Manifest File</a></p>
+ <ol>
+ <li><p><a class='doclink' href='#Manifest_API'>Manifest API</a></p>
+ </ol>
+ <li><p><a class='doclink' href='#ConfigFile'>Config File</a></p>
+ <ol>
+ <li><p><a class='doclink' href='#ConfigFile_API'>Config File API</a></p>
+ </ol>
+ <li><p><a class='doclink' href='#ResourceClasses'>Resource Classes</a></p>
+ <li><p><a class='doclink' href='#RestMicroservice'>RestMicroservice</a></p>
+ <ol>
+ <li><p><a class='doclink' href='#RestMicroservice_Extending'>Extending RestMicroservice</a></p>
+ </ol>
+</ol>
+
+<!-- ======================================================================================================== -->
+<a id="Introduction"></a>
+<h2 class='topic' onclick='toggle(this)'>1 - Microservice Introduction</h2>
+<div class='topic'>
+ <p>
+ The Juneau Cloud 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>
+ <p>
+ The Microservice API consists of a combination of the Juneau Core, Server, and Client APIs and an embedded
+ Eclipse Jetty Servlet Container. 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>
+</div>
+
+<!-- ======================================================================================================== -->
+<a id="GettingStarted"></a>
+<h2 class='topic' onclick='toggle(this)'>2 - Getting Started</h2>
+<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="GettingStarted_Installing"></a>
+ <h3 class='topic' onclick='toggle(this)'>2.1 - Installing in Eclipse</h3>
+ <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/instructions1.png">
+ <li>
+ Select the zip file and click <b>Finish</b>.
+ <br><br>
+ <img class='bordered' src="doc-files/instructions2.png">
+ <li>
+ In your workspace, you should now see the following project:
+ <br><br>
+ <img class='bordered' src="doc-files/instructions3.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_links</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>
+ <p>
+ At this point, you're ready to start the microservice from your workspace.
+ </p>
+ </div>
+
+ <!-- ======================================================================================================== -->
+ <a id="GettingStarted_Running"></a>
+ <h3 class='topic' onclick='toggle(this)'>2.2 - Running in Eclipse</h3>
+ <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/instructions4.png">
+ <p>
+ In your console view, you should see the following output:
+ </p>
+ <img class='bordered' src="doc-files/instructions5.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/instructions6.png">
+ <p>
+ You have started a REST interface on port 10000.
+ </p>
+ </div>
+
+ <!-- ======================================================================================================== -->
+ <a id="GettingStarted_Building"></a>
+ <h3 class='topic' onclick='toggle(this)'>2.3 - Building and Running from Command Line</h3>
+ <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/build1.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/build2.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="Manifest"></a>
+<h2 class='topic' onclick='toggle(this)'>3 - Manifest File</h2>
+<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.
+ In most cases, this value will always be <l>org.apache.juneau.microservice.RestMicroservice</l>.
+ 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.
+ These are classes that subclass from either {@link org.apache.juneau.microservice.Resource} or
+ {@link org.apache.juneau.microservice.ResourceGroup}.
+ This is a specialized entry when using <l>org.apache.juneau.microservice.RestMicroservice</l>.
+ 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.
+ 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.
+ 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="Manifest_API"></a>
+ <h3 class='topic' onclick='toggle(this)'>3.1 - Manifest API</h3>
+ <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="ConfigFile"></a>
+<h2 class='topic' onclick='toggle(this)'>4 - Config File</h2>
+<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.
+ 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>
+
+ <h6 class='topic'>Examples:</h6>
+ <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>
+ <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>
+
+ <h6 class='topic'>Additional Information</h6>
+ <ul class='doctree'>
+ <li class='jp'>
+ <a href='../core/ini/package-summary.html#TOC'><l>org.apache.juneau.ini</l></a>
+ - Juneau Configuration API Javadocs.
+ </ul>
+
+ <!-- ======================================================================================================== -->
+ <a id="ConfigFile_API"></a>
+ <h3 class='topic' onclick='toggle(this)'>4.1 - Config File API</h3>
+ <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.RestConfig#addVars(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>
+
+ <h6 class='figure'>Example usage:</h6>
+ <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.RestConfig#addVars(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>$R{key}</l> - Request variables.
+ <ul>
+ <li><l>$R{attribute.X}</l> - Value returned by {@link org.apache.juneau.rest.RestRequest#getAttribute(String)} converted to a string.
+ <li><l>$R{contextPath}</l> - Value returned by {@link org.apache.juneau.rest.RestRequest#getContextPath()}.
+ <li><l>$R{formData.X}</l> - Value returned by {@link org.apache.juneau.rest.RequestFormData#getString(String)}.
+ <li><l>$R{header.X}</l> - Value returned by {@link org.apache.juneau.rest.RequestHeaders#getString(String)}.
+ <li><l>$R{method}</l> - Value returned by {@link org.apache.juneau.rest.RestRequest#getMethod()}.
+ <li><l>$R{methodSummary}</l> - Value returned by {@link org.apache.juneau.rest.RestRequest#getMethodSummary()}.
+ <li><l>$R{methodDescription}</l> - Value returned by {@link org.apache.juneau.rest.RestRequest#getMethodDescription()}.
+ <li><l>$R{path.X}</l> - Value returned by {@link org.apache.juneau.rest.RequestPathMatch#get(Object)}.
+ <li><l>$R{pathInfo}</l> - Value returned by {@link org.apache.juneau.rest.RestRequest#getPathInfo()}.
+ <li><l>$R{query.X}</l> - Value returned by {@link org.apache.juneau.rest.RequestQuery#getString(String)}.
+ <li><l>$R{requestParentURI}</l> - Value returned by {@link org.apache.juneau.UriContext#getRootRelativePathInfoParent()}.
+ <li><l>$R{requestURI}</l> - Value returned by {@link org.apache.juneau.rest.RestRequest#getRequestURI()}.
+ <li><l>$R{servletDescription}</l> - Value returned by {@link org.apache.juneau.rest.RestRequest#getServletDescription()}.
+ <li><l>$R{servletTitle}</l> - Value returned by {@link org.apache.juneau.rest.RestRequest#getServletTitle()}.
+ <li><l>$R{servletParentURI}</l> - Value returned by {@link org.apache.juneau.UriContext#getRootRelativeServletPathParent()}.
+ <li><l>$R{servletPath}</l> - Value returned by {@link org.apache.juneau.rest.RestRequest#getServletPath()}.
+ <li><l>$R{servletURI}</l> - Value returned by {@link org.apache.juneau.UriContext#getRootRelativeServletPath()}.
+ </ul>
+ <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>
+
+ <h6 class='figure'>Example usage:</h6>
+ <p class='bcode'>
+ <cc>#-----------------------------</cc>
+ <cc># Contents of microservice.cfg </cc>
+ <cc>#-----------------------------</cc>
+ <cs>[MyHelloResource]</cs>
+ <ck>greeting</ck> = <cv>Hello $R{path.person}!</cv>
+ <ck>localizedGreeting</ck> = <cv>$L{HelloMessage,$R{path.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 {
+
+ <jd>/** Standard hello message. */</jd>
+ <ja>@RestMethod</ja>(name=<js>"GET"</js>, 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=<js>"GET"</js>, path=<js>"/localized/{person}"</js>)
+ <jk>public</jk> String sayLocalizedHello(RestRequest req) {
+ <jk>return</jk> req.getConfig().getString(<js>"MyHelloResource/localizedGreeting"</js>);
+ }
+ }
+ <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.RestConfig#addVars(Class...)} method.
+ </p>
+ </ul>
+ <p>
+ That <l>sayLocalizedHello()</l> example might need some explanation since there's a lot going on there.
+ 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,$R{path.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="ResourceClasses"></a>
+<h2 class='topic' onclick='toggle(this)'>5 - Resource Classes</h2>
+<div class='topic'>
+ <p>
+ Now let's take a look at the resource classes themselves.
+ The top-level page:
+ </p>
+ <img class='bordered' src='doc-files/instructions6.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_links</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/helloworld1.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=<js>"GET"</js>, 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>
+
+ <h6 class='topic'>Additional Information</h6>
+ <ul class='doctree'>
+ <li class='jp'>
+ <a href='../server/package-summary.html#TOC'><l>org.apache.juneau.rest</l></a>
+ - Juneau Server API Javadocs.
+ </ul>
+</div>
+
+
+<!-- ======================================================================================================== -->
+<a id="RestMicroservice"></a>
+<h2 class='topic' onclick='toggle(this)'>6 - RestMicroservice</h2>
+<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="RestMicroservice_Extending"></a>
+ <h3 class='topic' onclick='toggle(this)'>6.1 - Extending RestMicroservice</h3>
+<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.
+ 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>
+</body>
+</html>
\ No newline at end of file
Propchange: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/package.html
------------------------------------------------------------------------------
svn:executable = *
Propchange: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/package.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigEdit.html
==============================================================================
--- release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigEdit.html (added)
+++ release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigEdit.html Fri Sep 8 23:21:12 2017
@@ -0,0 +1,39 @@
+<!DOCTYPE HTML>
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ ***************************************************************************************************************************/
+ -->
+<html>
+<head>
+ <meta http-equiv='Content-Type' content='text/html; charset=UTF-8'>
+ <style type='text/css'>
+ @import '$R{servletURI}/style.css';
+ </style>
+</head>
+<body>
+ <h3 class='title'>$R{servletTitle}</h3>
+ <h5 class='description'>Edit config file</h5>
+ <p class='links'><a href='$R{requestParentURI}'>up</a> - <a href='$R{servletURI}?method=OPTIONS'>options</a></p>
+ <form id='form' action='$R{servletURI}' method='POST' enctype='application/x-www-form-urlencoded'>
+ <div class='data'>
+ <table>
+ <tr><td colspan='2' align='right'><button type='submit'>Submit</button><button type='reset'>Reset</button></td></tr>
+ <tr><th colspan='2'>Contents</th></tr>
+ <tr><td colspan='2'><textarea name='contents' rows='40' cols='120' style='white-space: pre; word-wrap: normal; overflow-x: scroll;'>$A{contents}</textarea></td></tr>
+ </table>
+ </div>
+ </form>
+</body>
+</html>
+
Propchange: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigEdit.html
------------------------------------------------------------------------------
svn:executable = *
Propchange: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigEdit.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java
==============================================================================
--- release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java (added)
+++ release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java Fri Sep 8 23:21:12 2017
@@ -0,0 +1,212 @@
+// ***************************************************************************************************************************
+// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
+// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
+// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
+// * with the License. You may obtain a copy of the License at *
+// * *
+// * http://www.apache.org/licenses/LICENSE-2.0 *
+// * *
+// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
+// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
+// * specific language governing permissions and limitations under the License. *
+// ***************************************************************************************************************************
+package org.apache.juneau.microservice.resources;
+
+import static javax.servlet.http.HttpServletResponse.*;
+import static org.apache.juneau.dto.html5.HtmlBuilder.*;
+
+import java.io.*;
+import java.util.Map;
+
+import org.apache.juneau.*;
+import org.apache.juneau.dto.html5.*;
+import org.apache.juneau.ini.*;
+import org.apache.juneau.microservice.*;
+import org.apache.juneau.rest.*;
+import org.apache.juneau.rest.annotation.*;
+import org.apache.juneau.rest.annotation.Body;
+
+/**
+ * Shows contents of the microservice configuration file.
+ */
+@RestResource(
+ path="/config",
+ title="Configuration",
+ description="Contents of configuration file.",
+ htmldoc=@HtmlDoc(
+ links={
+ "up: request:/..",
+ "options: servlet:/?method=OPTIONS",
+ "edit: servlet:/edit"
+ }
+ )
+)
+public class ConfigResource extends Resource {
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * [GET /] - Show contents of config file.
+ *
+ * @return The config file.
+ * @throws Exception
+ */
+ @RestMethod(name="GET", path="/", description="Show contents of config file.")
+ public ConfigFile getConfigContents() throws Exception {
+ return getServletConfig().getConfigFile();
+ }
+
+ /**
+ * [GET /edit] - Show config file edit page.
+ *
+ * @param req The HTTP request.
+ * @return The config file as a reader resource.
+ * @throws Exception
+ */
+ @RestMethod(name="GET", path="/edit", description="Edit config file.")
+ public Form getConfigEditForm(RestRequest req) throws Exception {
+ return form().id("form").action("servlet:/").method("POST").enctype("application/x-www-form-urlencoded").children(
+ div()._class("data").children(
+ table(
+ tr(td().style("text-align:right").children(button("submit","Submit"),button("reset","Reset"))),
+ tr(th().child("Contents")),
+ tr(th().child(
+ textarea().name("contents").rows(40).cols(120).style("white-space:pre;word-wrap:normal;overflow-x:scroll;font-family:monospace;")
+ .text(getConfigContents().toString()))
+ )
+ )
+ )
+ );
+ }
+
+ /**
+ * [GET /{section}] - Show config file section.
+ *
+ * @param section The section name.
+ * @return The config file section.
+ * @throws Exception
+ */
+ @RestMethod(name="GET", path="/{section}",
+ description="Show config file section.",
+ swagger=@MethodSwagger(
+ parameters={
+ @Parameter(in="path", name="section", description="Section name.")
+ }
+ )
+ )
+ public ObjectMap getConfigSection(@Path("section") String section) throws Exception {
+ return getSection(section);
+ }
+
+ /**
+ * [GET /{section}/{key}] - Show config file entry.
+ *
+ * @param section The section name.
+ * @param key The section key.
+ * @return The value of the config file entry.
+ * @throws Exception
+ */
+ @RestMethod(name="GET", path="/{section}/{key}",
+ description="Show config file entry.",
+ swagger=@MethodSwagger(
+ parameters={
+ @Parameter(in="path", name="section", description="Section name."),
+ @Parameter(in="path", name="key", description="Entry name.")
+ }
+ )
+ )
+ public String getConfigEntry(@Path("section") String section, @Path("key") String key) throws Exception {
+ return getSection(section).getString(key);
+ }
+
+ /**
+ * [POST /] - Sets contents of config file from a FORM post.
+ *
+ * @param contents The new contents of the config file.
+ * @return The new config file contents.
+ * @throws Exception
+ */
+ @RestMethod(name="POST", path="/",
+ description="Sets contents of config file from a FORM post.",
+ swagger=@MethodSwagger(
+ parameters={
+ @Parameter(in="formData", name="contents", description="New contents in INI file format.")
+ }
+ )
+ )
+ public ConfigFile setConfigContentsFormPost(@FormData("contents") String contents) throws Exception {
+ return setConfigContents(new StringReader(contents));
+ }
+
+ /**
+ * [PUT /] - Sets contents of config file.
+ *
+ * @param contents The new contents of the config file.
+ * @return The new config file contents.
+ * @throws Exception
+ */
+ @RestMethod(name="PUT", path="/",
+ description="Sets contents of config file.",
+ swagger=@MethodSwagger(
+ parameters={
+ @Parameter(in="body", description="New contents in INI file format.")
+ }
+ )
+ )
+ public ConfigFile setConfigContents(@Body Reader contents) throws Exception {
+ ConfigFile cf2 = new ConfigFileBuilder().build(contents);
+ return getConfigContents().merge(cf2).save();
+ }
+
+ /**
+ * [PUT /{section}] - Add or overwrite a config file section.
+ *
+ * @param section The section name.
+ * @param contents The new contents of the config file section.
+ * @return The new section.
+ * @throws Exception
+ */
+ @RestMethod(name="PUT", path="/{section}",
+ description="Add or overwrite a config file section.",
+ swagger=@MethodSwagger(
+ parameters={
+ @Parameter(in="path", name="section", description="Section name."),
+ @Parameter(in="body", description="New contents for section as a simple map with string keys and values.")
+ }
+ )
+ )
+ public ObjectMap setConfigSection(@Path("section") String section, @Body Map<String,String> contents) throws Exception {
+ getConfigContents().setSection(section, contents);
+ return getSection(section);
+ }
+
+ /**
+ * [PUT /{section}/{key}] - Add or overwrite a config file entry.
+ *
+ * @param section The section name.
+ * @param key The section key.
+ * @param value The new value.
+ * @return The new value.
+ * @throws Exception
+ */
+ @RestMethod(name="PUT", path="/{section}/{key}",
+ description="Add or overwrite a config file entry.",
+ swagger=@MethodSwagger(
+ parameters={
+ @Parameter(in="path", name="section", description="Section name."),
+ @Parameter(in="path", name="key", description="Entry name."),
+ @Parameter(in="body", description="New value as a string.")
+ }
+ )
+ )
+ public String setConfigSection(@Path("section") String section, @Path("key") String key, @Body String value) throws Exception {
+ getConfigContents().put(section, key, value, false);
+ return getSection(section).getString(key);
+ }
+
+ private ObjectMap getSection(String name) throws Exception {
+ ObjectMap m = getConfigContents().getSectionMap(name);
+ if (m == null)
+ throw new RestException(SC_NOT_FOUND, "Section not found.");
+ return m;
+ }
+}
Propchange: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java
------------------------------------------------------------------------------
svn:executable = *
Propchange: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/DirectoryResource.java
==============================================================================
--- release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/DirectoryResource.java (added)
+++ release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/DirectoryResource.java Fri Sep 8 23:21:12 2017
@@ -0,0 +1,375 @@
+// ***************************************************************************************************************************
+// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
+// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
+// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
+// * with the License. You may obtain a copy of the License at *
+// * *
+// * http://www.apache.org/licenses/LICENSE-2.0 *
+// * *
+// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
+// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
+// * specific language governing permissions and limitations under the License. *
+// ***************************************************************************************************************************
+package org.apache.juneau.microservice.resources;
+
+import static java.util.logging.Level.*;
+import static javax.servlet.http.HttpServletResponse.*;
+import static org.apache.juneau.html.HtmlDocSerializerContext.*;
+import static org.apache.juneau.rest.RestContext.*;
+
+import java.io.*;
+import java.net.*;
+import java.util.*;
+import java.util.logging.*;
+
+import javax.servlet.*;
+
+import org.apache.juneau.*;
+import org.apache.juneau.annotation.*;
+import org.apache.juneau.microservice.*;
+import org.apache.juneau.rest.*;
+import org.apache.juneau.rest.annotation.*;
+import org.apache.juneau.rest.converters.*;
+import org.apache.juneau.transforms.*;
+import org.apache.juneau.utils.*;
+
+/**
+ * REST resource that allows access to a file system directory.
+ *
+ * <p>
+ * The root directory is specified in one of two ways:
+ * <ul class='spaced-list'>
+ * <li>
+ * Specifying the location via a <l>DirectoryResource.rootDir</l> property.
+ * <li>
+ * Overriding the {@link #getRootDir()} method.
+ * </ul>
+ *
+ * <p>
+ * Read/write access control is handled through the following properties:
+ * <ul class='spaced-list'>
+ * <li>
+ * <l>DirectoryResource.allowViews</l> - If <jk>true</jk>, allows view and download access to files.
+ * <li>
+ * <l>DirectoryResource.allowPuts</l> - If <jk>true</jk>, allows files to be created or overwritten.
+ * <li>
+ * <l>DirectoryResource.allowDeletes</l> - If <jk>true</jk>, allows files to be deleted.
+ * </ul>
+ *
+ * <p>
+ * Access can also be controlled by overriding the {@link #checkAccess(RestRequest)} method.
+ */
+@RestResource(
+ title="File System Explorer",
+ description="Contents of $R{attribute.path}",
+ messages="nls/DirectoryResource",
+ htmldoc=@HtmlDoc(
+ links={
+ "up: request:/..",
+ "options: servlet:/?method=OPTIONS"
+ }
+ ),
+ properties={
+ @Property(name=HTML_uriAnchorText, value=PROPERTY_NAME),
+ @Property(name=REST_allowMethodParam, value="*"),
+ @Property(name="DirectoryResource.rootDir", value="")
+ }
+)
+public class DirectoryResource extends Resource {
+ private static final long serialVersionUID = 1L;
+
+ private File rootDir; // The root directory
+
+ // Settings enabled through servlet init parameters
+ private boolean allowDeletes, allowPuts, allowViews;
+
+ private static Logger logger = Logger.getLogger(DirectoryResource.class.getName());
+
+ @Override /* Servlet */
+ public void init() throws ServletException {
+ ObjectMap p = getProperties();
+ rootDir = new File(p.getString("DirectoryResource.rootDir"));
+ allowViews = p.getBoolean("DirectoryResource.allowViews", false);
+ allowDeletes = p.getBoolean("DirectoryResource.allowDeletes", false);
+ allowPuts = p.getBoolean("DirectoryResource.allowPuts", false);
+ }
+
+ /**
+ * Returns the root directory defined by the 'rootDir' init parameter.
+ *
+ * <p>
+ * Subclasses can override this method to provide their own root directory.
+ *
+ * @return The root directory.
+ */
+ protected File getRootDir() {
+ if (rootDir == null) {
+ rootDir = new File(getProperties().getString("rootDir"));
+ if (! rootDir.exists())
+ if (! rootDir.mkdirs())
+ throw new RuntimeException("Could not create root dir");
+ }
+ return rootDir;
+ }
+
+ /**
+ * [GET /*] - On directories, returns a directory listing. On files, returns information about the file.
+ *
+ * @param req The HTTP request.
+ * @return Either a FileResource or list of FileResources depending on whether it's a
+ * file or directory.
+ * @throws Exception If file could not be read or access was not granted.
+ */
+ @RestMethod(name="GET", path="/*",
+ description="On directories, returns a directory listing.\nOn files, returns information about the file.",
+ converters={Queryable.class}
+ )
+ public Object doGet(RestRequest req) throws Exception {
+ checkAccess(req);
+
+ String pathInfo = req.getPathInfo();
+ File f = pathInfo == null ? rootDir : new File(rootDir.getAbsolutePath() + pathInfo);
+
+ if (!f.exists())
+ throw new RestException(SC_NOT_FOUND, "File not found");
+
+ req.setAttribute("path", f.getAbsolutePath());
+
+ if (f.isDirectory()) {
+ List<FileResource> l = new LinkedList<FileResource>();
+ File[] files = f.listFiles();
+ if (files != null) {
+ for (File fc : files) {
+ URL fUrl = new URL(req.getRequestURL().append("/").append(fc.getName()).toString());
+ l.add(new FileResource(fc, fUrl));
+ }
+ }
+ return l;
+ }
+
+ return new FileResource(f, new URL(req.getRequestURL().toString()));
+ }
+
+ /**
+ * [DELETE /*] - Delete a file on the file system.
+ *
+ * @param req The HTTP request.
+ * @return The message <js>"File deleted"</js> if successful.
+ * @throws Exception If file could not be read or access was not granted.
+ */
+ @RestMethod(name="DELETE", path="/*",
+ description="Delete a file on the file system."
+ )
+ public Object doDelete(RestRequest req) throws Exception {
+ checkAccess(req);
+
+ File f = new File(rootDir.getAbsolutePath() + req.getPathInfo());
+ deleteFile(f);
+
+ if (req.getHeader("Accept").contains("text/html"))
+ return new Redirect();
+ return "File deleted";
+ }
+
+ /**
+ * [PUT /*] - Add or overwrite a file on the file system.
+ *
+ * @param req The HTTP request.
+ * @return The message <js>"File added"</js> if successful.
+ * @throws Exception If file could not be read or access was not granted.
+ */
+ @RestMethod(name="PUT", path="/*",
+ description="Add or overwrite a file on the file system."
+ )
+ public Object doPut(RestRequest req) throws Exception {
+ checkAccess(req);
+
+ File f = new File(rootDir.getAbsolutePath() + req.getPathInfo());
+ String parentSubPath = f.getParentFile().getAbsolutePath().substring(rootDir.getAbsolutePath().length());
+ BufferedOutputStream bos = new BufferedOutputStream(new FileOutputStream(f));
+ IOPipe.create(req.getInputStream(), bos).closeOut().run();
+ if (req.getContentType().contains("html"))
+ return new Redirect(parentSubPath);
+ return "File added";
+ }
+
+ /**
+ * [VIEW /*] - View the contents of a file.
+ *
+ * <p>
+ * Applies to files only.
+ *
+ * @param req The HTTP request.
+ * @param res The HTTP response.
+ * @return A Reader containing the contents of the file.
+ * @throws Exception If file could not be read or access was not granted.
+ */
+ @RestMethod(name="VIEW", path="/*",
+ description="View the contents of a file.\nApplies to files only."
+ )
+ public Reader doView(RestRequest req, RestResponse res) throws Exception {
+ checkAccess(req);
+
+ File f = new File(rootDir.getAbsolutePath() + req.getPathInfo());
+
+ if (!f.exists())
+ throw new RestException(SC_NOT_FOUND, "File not found");
+
+ if (f.isDirectory())
+ throw new RestException(SC_METHOD_NOT_ALLOWED, "VIEW not available on directories");
+
+ res.setContentType("text/plain");
+ return new FileReader(f);
+ }
+
+ /**
+ * [DOWNLOAD /*] - Download the contents of a file.
+ *
+ * <p>
+ * Applies to files only.
+ *
+ * @param req The HTTP request.
+ * @param res The HTTP response.
+ * @return A Reader containing the contents of the file.
+ * @throws Exception If file could not be read or access was not granted.
+ */
+ @RestMethod(name="DOWNLOAD", path="/*",
+ description="Download the contents of a file.\nApplies to files only."
+ )
+ public Reader doDownload(RestRequest req, RestResponse res) throws Exception {
+ checkAccess(req);
+
+ File f = new File(rootDir.getAbsolutePath() + req.getPathInfo());
+
+ if (!f.exists())
+ throw new RestException(SC_NOT_FOUND, "File not found");
+
+ if (f.isDirectory())
+ throw new RestException(SC_METHOD_NOT_ALLOWED, "DOWNLOAD not available on directories");
+
+ res.setContentType("application");
+ return new FileReader(f);
+ }
+
+ /**
+ * Verify that the specified request is allowed.
+ *
+ * <p>
+ * Subclasses can override this method to provide customized behavior.
+ * Method should throw a {@link RestException} if the request should be disallowed.
+ *
+ * @param req The HTTP request.
+ */
+ protected void checkAccess(RestRequest req) {
+ String method = req.getMethod();
+ if (method.equals("VIEW") && ! allowViews)
+ throw new RestException(SC_METHOD_NOT_ALLOWED, "VIEW not enabled");
+ if (method.equals("PUT") && ! allowPuts)
+ throw new RestException(SC_METHOD_NOT_ALLOWED, "PUT not enabled");
+ if (method.equals("DELETE") && ! allowDeletes)
+ throw new RestException(SC_METHOD_NOT_ALLOWED, "DELETE not enabled");
+ if (method.equals("DOWNLOAD") && ! allowViews)
+ throw new RestException(SC_METHOD_NOT_ALLOWED, "DOWNLOAD not enabled");
+ }
+
+ /** File POJO */
+ public class FileResource {
+ private File f;
+ private URL url;
+
+ /**
+ * Constructor.
+ *
+ * @param f The file.
+ * @param url The URL of the file resource.
+ */
+ public FileResource(File f, URL url) {
+ this.f = f;
+ this.url = url;
+ }
+
+ // Bean property getters
+
+ /**
+ * @return The URL of the file resource.
+ */
+ public URL getUrl() {
+ return url;
+ }
+
+ /**
+ * @return The file type.
+ */
+ public String getType() {
+ return (f.isDirectory() ? "dir" : "file");
+ }
+
+ /**
+ * @return The file name.
+ */
+ public String getName() {
+ return f.getName();
+ }
+
+ /**
+ * @return The file size.
+ */
+ public long getSize() {
+ return f.length();
+ }
+
+ /**
+ * @return The file last modified timestamp.
+ */
+ @BeanProperty(swap=DateSwap.ISO8601DTP.class)
+ public Date getLastModified() {
+ return new Date(f.lastModified());
+ }
+
+ /**
+ * @return A hyperlink to view the contents of the file.
+ * @throws Exception If access is not allowed.
+ */
+ public URL getView() throws Exception {
+ if (allowViews && f.canRead() && ! f.isDirectory())
+ return new URL(url + "?method=VIEW");
+ return null;
+ }
+
+ /**
+ * @return A hyperlink to download the contents of the file.
+ * @throws Exception If access is not allowed.
+ */
+ public URL getDownload() throws Exception {
+ if (allowViews && f.canRead() && ! f.isDirectory())
+ return new URL(url + "?method=DOWNLOAD");
+ return null;
+ }
+
+ /**
+ * @return A hyperlink to delete the file.
+ * @throws Exception If access is not allowed.
+ */
+ public URL getDelete() throws Exception {
+ if (allowDeletes && f.canWrite())
+ return new URL(url + "?method=DELETE");
+ return null;
+ }
+ }
+
+ /** Utility method */
+ private void deleteFile(File f) {
+ try {
+ if (f.isDirectory()) {
+ File[] files = f.listFiles();
+ if (files != null) {
+ for (File fc : files)
+ deleteFile(fc);
+ }
+ }
+ f.delete();
+ } catch (Exception e) {
+ logger.log(WARNING, "Cannot delete file '" + f.getAbsolutePath() + "'", e);
+ }
+ }
+}
Propchange: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/DirectoryResource.java
------------------------------------------------------------------------------
svn:executable = *
Propchange: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/DirectoryResource.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/LogEntryFormatter.java
==============================================================================
--- release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/LogEntryFormatter.java (added)
+++ release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/LogEntryFormatter.java Fri Sep 8 23:21:12 2017
@@ -0,0 +1,266 @@
+// ***************************************************************************************************************************
+// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
+// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
+// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
+// * with the License. You may obtain a copy of the License at *
+// * *
+// * http://www.apache.org/licenses/LICENSE-2.0 *
+// * *
+// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
+// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
+// * specific language governing permissions and limitations under the License. *
+// ***************************************************************************************************************************
+package org.apache.juneau.microservice.resources;
+
+import static org.apache.juneau.internal.StringUtils.*;
+
+import java.text.*;
+import java.util.*;
+import java.util.concurrent.*;
+import java.util.concurrent.atomic.*;
+import java.util.logging.*;
+import java.util.logging.Formatter;
+import java.util.regex.*;
+
+/**
+ * Log entry formatter.
+ *
+ * <p>
+ * Uses three simple parameter for configuring log entry formats:
+ * <ul class='spaced-list'>
+ * <li>
+ * <code>dateFormat</code> - A {@link SimpleDateFormat} string describing the format for dates.
+ * <li>
+ * <code>format</code> - A string with <code>{...}</code> replacement variables representing predefined fields.
+ * <li>
+ * <code>useStackTraceHashes</code> - A setting that causes duplicate stack traces to be replaced with 8-character
+ * hash strings.
+ * </ul>
+ *
+ * <p>
+ * This class converts the format strings into a regular expression that can be used to parse the resulting log file.
+ */
+public class LogEntryFormatter extends Formatter {
+
+ private ConcurrentHashMap<String,AtomicInteger> hashes;
+ private DateFormat df;
+ private String format;
+ private Pattern rePattern;
+ private Map<String,Integer> fieldIndexes;
+
+ /**
+ * Create a new formatter.
+ *
+ * @param format
+ * The log entry format. e.g. <js>"[{date} {level}] {msg}%n"</js>
+ * The string can contain any of the following variables:
+ * <ol>
+ * <li><js>"{date}"</js> - The date, formatted per <js>"Logging/dateFormat"</js>.
+ * <li><js>"{class}"</js> - The class name.
+ * <li><js>"{method}"</js> - The method name.
+ * <li><js>"{logger}"</js> - The logger name.
+ * <li><js>"{level}"</js> - The log level name.
+ * <li><js>"{msg}"</js> - The log message.
+ * <li><js>"{threadid}"</js> - The thread ID.
+ * <li><js>"{exception}"</js> - The localized exception message.
+ * </ol>
+ * @param dateFormat
+ * The {@link SimpleDateFormat} format to use for dates. e.g. <js>"yyyy.MM.dd hh:mm:ss"</js>.
+ * @param useStackTraceHashes
+ * If <jk>true</jk>, only print unique stack traces once and then refer to them by a simple 8 character hash
+ * identifier.
+ */
+ public LogEntryFormatter(String format, String dateFormat, boolean useStackTraceHashes) {
+ this.df = new SimpleDateFormat(dateFormat);
+ if (useStackTraceHashes)
+ hashes = new ConcurrentHashMap<String,AtomicInteger>();
+
+ fieldIndexes = new HashMap<String,Integer>();
+
+ format = format
+ .replaceAll("\\{date\\}", "%1\\$s")
+ .replaceAll("\\{class\\}", "%2\\$s")
+ .replaceAll("\\{method\\}", "%3\\$s")
+ .replaceAll("\\{logger\\}", "%4\\$s")
+ .replaceAll("\\{level\\}", "%5\\$s")
+ .replaceAll("\\{msg\\}", "%6\\$s")
+ .replaceAll("\\{threadid\\}", "%7\\$s")
+ .replaceAll("\\{exception\\}", "%8\\$s");
+
+ this.format = format;
+
+ // Construct a regular expression to match this log entry.
+ int index = 1;
+ StringBuilder re = new StringBuilder();
+ int S1 = 1; // Looking for %
+ int S2 = 2; // Found %, looking for number.
+ int S3 = 3; // Found number, looking for $.
+ int S4 = 4; // Found $, looking for s.
+ int state = 1;
+ int i1 = 0;
+ for (int i = 0; i < format.length(); i++) {
+ char c = format.charAt(i);
+ if (state == S1) {
+ if (c == '%')
+ state = S2;
+ else {
+ if (! (Character.isLetterOrDigit(c) || Character.isWhitespace(c)))
+ re.append('\\');
+ re.append(c);
+ }
+ } else if (state == S2) {
+ if (Character.isDigit(c)) {
+ i1 = i;
+ state = S3;
+ } else {
+ re.append("\\%").append(c);
+ state = S1;
+ }
+ } else if (state == S3) {
+ if (c == '$') {
+ state = S4;
+ } else {
+ re.append("\\%").append(format.substring(i1, i));
+ state = S1;
+ }
+ } else if (state == S4) {
+ if (c == 's') {
+ int group = Integer.parseInt(format.substring(i1, i-1));
+ switch (group) {
+ case 1:
+ fieldIndexes.put("date", index++);
+ re.append("(" + dateFormat.replaceAll("[mHhsSdMy]", "\\\\d").replaceAll("\\.", "\\\\.") + ")");
+ break;
+ case 2:
+ fieldIndexes.put("class", index++);
+ re.append("([\\p{javaJavaIdentifierPart}\\.]+)");
+ break;
+ case 3:
+ fieldIndexes.put("method", index++);
+ re.append("([\\p{javaJavaIdentifierPart}\\.]+)");
+ break;
+ case 4:
+ fieldIndexes.put("logger", index++);
+ re.append("([\\w\\d\\.\\_]+)");
+ break;
+ case 5:
+ fieldIndexes.put("level", index++);
+ re.append("(SEVERE|WARNING|INFO|CONFIG|FINE|FINER|FINEST)");
+ break;
+ case 6:
+ fieldIndexes.put("msg", index++);
+ re.append("(.*)");
+ break;
+ case 7:
+ fieldIndexes.put("threadid", index++);
+ re.append("(\\\\d+)");
+ break;
+ case 8:
+ fieldIndexes.put("exception", index++);
+ re.append("(.*)");
+ break;
+ default: // Fall through.
+ }
+ } else {
+ re.append("\\%").append(format.substring(i1, i));
+ }
+ state = S1;
+ }
+ }
+
+ // The log parser
+ String sre = re.toString();
+ if (sre.endsWith("\\%n"))
+ sre = sre.substring(0, sre.length()-3);
+
+ // Replace instances of %n.
+ sre = sre.replaceAll("\\\\%n", "\\\\n");
+
+ rePattern = Pattern.compile(sre);
+ fieldIndexes = Collections.unmodifiableMap(fieldIndexes);
+ }
+
+ /**
+ * Returns the regular expression pattern used for matching log entries.
+ *
+ * @return The regular expression pattern used for matching log entries.
+ */
+ public Pattern getLogEntryPattern() {
+ return rePattern;
+ }
+
+ /**
+ * Returns the {@link DateFormat} used for matching dates.
+ *
+ * @return The {@link DateFormat} used for matching dates.
+ */
+ public DateFormat getDateFormat() {
+ return df;
+ }
+
+ /**
+ * Given a matcher that has matched the pattern specified by {@link #getLogEntryPattern()}, returns the field value
+ * from the match.
+ *
+ * @param fieldName
+ * The field name.
+ * Possible values are:
+ * <ul>
+ * <li><js>"date"</js>
+ * <li><js>"class"</js>
+ * <li><js>"method"</js>
+ * <li><js>"logger"</js>
+ * <li><js>"level"</js>
+ * <li><js>"msg"</js>
+ * <li><js>"threadid"</js>
+ * <li><js>"exception"</js>
+ * </ul>
+ * @param m The matcher.
+ * @return The field value, or <jk>null</jk> if the specified field does not exist.
+ */
+ public String getField(String fieldName, Matcher m) {
+ Integer i = fieldIndexes.get(fieldName);
+ return (i == null ? null : m.group(i));
+ }
+
+ @Override /* Formatter */
+ public String format(LogRecord r) {
+ String msg = formatMessage(r);
+ Throwable t = r.getThrown();
+ String hash = null;
+ int c = 0;
+ if (hashes != null && t != null) {
+ hash = hashCode(t);
+ hashes.putIfAbsent(hash, new AtomicInteger(0));
+ c = hashes.get(hash).incrementAndGet();
+ if (c == 1) {
+ msg = '[' + hash + '.' + c + "] " + msg;
+ } else {
+ msg = '[' + hash + '.' + c + "] " + msg + ", " + t.getLocalizedMessage();
+ t = null;
+ }
+ }
+ String s = String.format(format,
+ df.format(new Date(r.getMillis())),
+ r.getSourceClassName(),
+ r.getSourceMethodName(),
+ r.getLoggerName(),
+ r.getLevel(),
+ msg,
+ r.getThreadID(),
+ r.getThrown() == null ? "" : r.getThrown().getMessage());
+ if (t != null)
+ s += String.format("%n%s", getStackTrace(r.getThrown()));
+ return s;
+ }
+
+ private static String hashCode(Throwable t) {
+ int i = 0;
+ while (t != null) {
+ for (StackTraceElement e : t.getStackTrace())
+ i ^= e.hashCode();
+ t = t.getCause();
+ }
+ return Integer.toHexString(i);
+ }
+}
Propchange: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/LogEntryFormatter.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/LogParser.java
==============================================================================
--- release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/LogParser.java (added)
+++ release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/LogParser.java Fri Sep 8 23:21:12 2017
@@ -0,0 +1,228 @@
+// ***************************************************************************************************************************
+// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
+// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
+// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
+// * with the License. You may obtain a copy of the License at *
+// * *
+// * http://www.apache.org/licenses/LICENSE-2.0 *
+// * *
+// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
+// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
+// * specific language governing permissions and limitations under the License. *
+// ***************************************************************************************************************************
+package org.apache.juneau.microservice.resources;
+
+import java.io.*;
+import java.nio.charset.*;
+import java.text.*;
+import java.util.*;
+import java.util.regex.*;
+
+/**
+ * Utility class for reading log files.
+ *
+ * <p>
+ * Provides the capability of returning splices of log files based on dates and filtering based on thread and logger
+ * names.
+ */
+public class LogParser implements Iterable<LogParser.Entry>, Iterator<LogParser.Entry> {
+ private BufferedReader br;
+ private LogEntryFormatter formatter;
+ private Date start, end;
+ private Set<String> loggerFilter, severityFilter;
+ private String threadFilter;
+ private Entry next;
+
+ /**
+ * Constructor.
+ *
+ * @param formatter The log entry formatter.
+ * @param f The log file.
+ * @param start Don't return rows before this date. If <jk>null</jk>, start from the beginning of the file.
+ * @param end Don't return rows after this date. If <jk>null</jk>, go to the end of the file.
+ * @param thread Only return log entries with this thread name.
+ * @param loggers Only return log entries produced by these loggers (simple class names).
+ * @param severity Only return log entries with the specified severity.
+ * @throws IOException
+ */
+ public LogParser(LogEntryFormatter formatter, File f, Date start, Date end, String thread, String[] loggers, String[] severity) throws IOException {
+ br = new BufferedReader(new InputStreamReader(new FileInputStream(f), Charset.defaultCharset()));
+ this.formatter = formatter;
+ this.start = start;
+ this.end = end;
+ this.threadFilter = thread;
+ if (loggers != null)
+ this.loggerFilter = new HashSet<String>(Arrays.asList(loggers));
+ if (severity != null)
+ this.severityFilter = new HashSet<String>(Arrays.asList(severity));
+
+ // Find the first line.
+ String line;
+ while (next == null && (line = br.readLine()) != null) {
+ Entry e = new Entry(line);
+ if (e.matches())
+ next = e;
+ }
+ }
+
+ @Override /* Iterator */
+ public boolean hasNext() {
+ return next != null;
+ }
+
+ @Override /* Iterator */
+ public Entry next() {
+ Entry current = next;
+ Entry prev = next;
+ try {
+ next = null;
+ String line = null;
+ while (next == null && (line = br.readLine()) != null) {
+ Entry e = new Entry(line);
+ if (e.isRecord) {
+ if (e.matches())
+ next = e;
+ prev = null;
+ } else {
+ if (prev != null)
+ prev.addText(e.line);
+ }
+ }
+ } catch (IOException e) {
+ throw new RuntimeException(e);
+ }
+ return current;
+ }
+
+ @Override /* Iterator */
+ public void remove() {
+ throw new NoSuchMethodError();
+ }
+
+ @Override /* Iterable */
+ public Iterator<Entry> iterator() {
+ return this;
+ }
+
+ /**
+ * Closes the underlying reader.
+ *
+ * @throws IOException
+ */
+ public void close() throws IOException {
+ br.close();
+ }
+
+ /**
+ * Serializes the contents of the parsed log file to the specified writer and then closes the underlying reader.
+ *
+ * @param w The writer to write the log file to.
+ * @throws IOException
+ */
+ public void writeTo(Writer w) throws IOException {
+ try {
+ if (! hasNext())
+ w.append("[EMPTY]");
+ else for (LogParser.Entry le : this)
+ le.append(w);
+ } finally {
+ close();
+ }
+ }
+
+ /**
+ * Represents a single line from the log file.
+ */
+ @SuppressWarnings("javadoc")
+ public class Entry {
+ public Date date;
+ public String severity, logger;
+ protected String line, text;
+ protected String thread;
+ protected List<String> additionalText;
+ protected boolean isRecord;
+
+ Entry(String line) throws IOException {
+ try {
+ this.line = line;
+ Matcher m = formatter.getLogEntryPattern().matcher(line);
+ if (m.matches()) {
+ isRecord = true;
+ String s = formatter.getField("date", m);
+ if (s != null)
+ date = formatter.getDateFormat().parse(s);
+ thread = formatter.getField("thread", m);
+ severity = formatter.getField("level", m);
+ logger = formatter.getField("logger", m);
+ text = formatter.getField("msg", m);
+ if (logger != null && logger.indexOf('.') > -1)
+ logger = logger.substring(logger.lastIndexOf('.')+1);
+ }
+ } catch (ParseException e) {
+ throw new IOException(e);
+ }
+ }
+
+ private void addText(String t) {
+ if (additionalText == null)
+ additionalText = new LinkedList<String>();
+ additionalText.add(t);
+ }
+
+ public String getText() {
+ if (additionalText == null)
+ return text;
+ int i = text.length();
+ for (String s : additionalText)
+ i += s.length() + 1;
+ StringBuilder sb = new StringBuilder(i);
+ sb.append(text);
+ for (String s : additionalText)
+ sb.append('\n').append(s);
+ return sb.toString();
+ }
+
+ public String getThread() {
+ return thread;
+ }
+
+ public Writer appendHtml(Writer w) throws IOException {
+ w.append(toHtml(line)).append("<br>");
+ if (additionalText != null)
+ for (String t : additionalText)
+ w.append(toHtml(t)).append("<br>");
+ return w;
+ }
+
+ protected Writer append(Writer w) throws IOException {
+ w.append(line).append('\n');
+ if (additionalText != null)
+ for (String t : additionalText)
+ w.append(t).append('\n');
+ return w;
+ }
+
+ private boolean matches() {
+ if (! isRecord)
+ return false;
+ if (start != null && date.before(start))
+ return false;
+ if (end != null && date.after(end))
+ return false;
+ if (threadFilter != null && ! threadFilter.equals(thread))
+ return false;
+ if (loggerFilter != null && ! loggerFilter.contains(logger))
+ return false;
+ if (severityFilter != null && ! severityFilter.contains(severity))
+ return false;
+ return true;
+ }
+ }
+
+ private static String toHtml(String s) {
+ if (s.indexOf('<') != -1)
+ return s.replaceAll("<", "<");//$NON-NLS-2$
+ return s;
+ }
+}
+
Propchange: release/incubator/juneau/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/LogParser.java
------------------------------------------------------------------------------
svn:mime-type = text/plain