http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/RestMicroservice.java ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/RestMicroservice.java b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/RestMicroservice.java new file mode 100755 index 0000000..8dfda47 --- /dev/null +++ b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/RestMicroservice.java @@ -0,0 +1,644 @@ +// *************************************************************************************************************************** +// * 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; + +import static org.apache.juneau.internal.StringUtils.*; +import static org.apache.juneau.internal.FileUtils.*; +import static org.apache.juneau.internal.ClassUtils.*; + +import java.io.*; +import java.net.*; +import java.util.*; +import java.util.logging.*; + +import javax.servlet.*; + +import org.apache.juneau.*; +import org.apache.juneau.ini.*; +import org.apache.juneau.json.*; +import org.apache.juneau.microservice.resources.*; +import org.apache.juneau.parser.*; +import org.apache.juneau.rest.annotation.*; +import org.eclipse.jetty.server.*; +import org.eclipse.jetty.servlet.*; +import org.eclipse.jetty.xml.*; + +/** + * Entry point for Juneau microservice that implements a REST interface using Jetty on a single port. + * + * <h6 class='topic'>Jetty Server Details</h6> + * + * The Jetty server is created by the {@link #createServer()} method and started with the {@link #startServer()} method. + * These methods can be overridden to provided customized behavior. + * + * <h6 class='topic'>Defining REST Resources</h6> + * + * Top-level REST resources are defined by the {@link #getResourceMap()} method. + * This method can be overridden to provide a customized list of REST resources. + * + * <h6 class='topic'>Logging</h6> + * + * Logging is initialized by the {@link #initLogging()} method. + * This method can be overridden to provide customized logging behavior. + * + * <h6 class='topic'>Lifecycle Listener Methods</h6> + * Subclasses can optionally implement the following event listener methods: + * <ul class='spaced-list'> + * <li> + * {@link #onStart()} - Gets executed before {@link #start()}. + * <li> + * {@link #onStop()} - Gets executed before {@link #stop()}. + * <li> + * {@link #onCreateServer()} - Gets executed before {@link #createServer()}. + * <li> + * {@link #onStartServer()} - Gets executed before {@link #startServer()}. + * <li> + * {@link #onPostStartServer()} - Gets executed after {@link #startServer()}. + * <li> + * {@link #onStopServer()} - Gets executed before {@link #stop()}. + * <li> + * {@link #onPostStopServer()} - Gets executed after {@link #stop()}. + * </ul> + */ +public class RestMicroservice extends Microservice { + + ServletContextHandler servletContextHandler; + Server server; + int port; + String contextPath; + Logger logger; + Object jettyXml; + + /** + * Main method. + * + * <p> + * Subclasses must also implement this method! + * + * @param args Command line arguments. + * @throws Exception + */ + public static void main(String[] args) throws Exception { + new RestMicroservice(args).start().join(); + } + + /** + * Constructor. + * + * @param args Command line arguments. + * @throws Exception + */ + public RestMicroservice(String...args) throws Exception { + super(args); + } + + + //-------------------------------------------------------------------------------- + // Methods implemented on Microservice API + //-------------------------------------------------------------------------------- + + @Override /* Microservice */ + public RestMicroservice start() throws Exception { + super.start(); + try { + initLogging(); + } catch (Exception e) { + // If logging can be initialized, just print a stack trace and continue. + e.printStackTrace(); + } + createServer(); + startServer(); + return this; + } + + @Override /* Microservice */ + public RestMicroservice join() throws Exception { + server.join(); + return this; + } + + @Override /* Microservice */ + public RestMicroservice stop() { + Thread t = new Thread() { + @Override /* Thread */ + public void run() { + try { + if (server.isStopping() || server.isStopped()) + return; + onStopServer(); + logger.warning("Stopping server."); + server.stop(); + logger.warning("Server stopped."); + onPostStopServer(); + } catch (Exception e) { + logger.log(Level.SEVERE, e.getLocalizedMessage(), e); + } + } + }; + t.start(); + try { + t.join(); + } catch (InterruptedException e) { + e.printStackTrace(); + } + super.stop(); + return this; + } + + + //-------------------------------------------------------------------------------- + // RestMicroservice API methods. + //-------------------------------------------------------------------------------- + + /** + * Returns the port that this microservice started up on. + * @return The port that this microservice started up on. + */ + public int getPort() { + return port; + } + + /** + * Returns the URI where this microservice is listening on. + * @return The URI where this microservice is listening on. + */ + public URI getURI() { + String scheme = getConfig().getBoolean("REST/useSsl") ? "https" : "http"; + String hostname = "localhost"; + String ctx = "/".equals(contextPath) ? null : contextPath; + try { + hostname = InetAddress.getLocalHost().getHostName(); + } catch (UnknownHostException e) {} + try { + return new URI(scheme, null, hostname, port, ctx, null, null); + } catch (URISyntaxException e) { + throw new RuntimeException(e); + } + } + + /** + * Initialize the logging for this microservice. + * + * <p> + * Subclasses can override this method to provide customized logging. + * + * <p> + * The default implementation uses the <cs>Logging</cs> section in the config file to set up logging: + * <p class='bcode'> + * <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> = logs + * + * <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> = microservice.%g.log + * + * <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> = 10M + * + * <cc># Max number of log files. + * # Default is 1.</cc> + * <ck>count</ck> = 5 + * + * <cc># Default log levels. + * # Keys are logger names. + * # Values are serialized Level POJOs.</cc> + * <ck>levels</ck> = { org.apache.juneau:'INFO' } + * + * <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> = true + * + * <cc># The default level for the console logger. + * # Default is WARNING.</cc> + * <ck>consoleLevel</ck> = WARNING + * </p> + * + * @throws Exception + */ + protected void initLogging() throws Exception { + ConfigFile cf = getConfig(); + logger = Logger.getLogger(""); + String logFile = cf.getString("Logging/logFile"); + if (! isEmpty(logFile)) { + LogManager.getLogManager().reset(); + String logDir = cf.getString("Logging/logDir", "."); + mkdirs(new File(logDir), false); + boolean append = cf.getBoolean("Logging/append"); + int limit = cf.getInt("Logging/limit", 1024*1024); + int count = cf.getInt("Logging/count", 1); + FileHandler fh = new FileHandler(logDir + '/' + logFile, limit, count, append); + + boolean useStackTraceHashes = cf.getBoolean("Logging/useStackTraceHashes"); + String format = cf.getString("Logging/format", "[{date} {level}] {msg}%n"); + String dateFormat = cf.getString("Logging/dateFormat", "yyyy.MM.dd hh:mm:ss"); + fh.setFormatter(new LogEntryFormatter(format, dateFormat, useStackTraceHashes)); + logger.addHandler(fh); + + ConsoleHandler ch = new ConsoleHandler(); + ch.setLevel(Level.parse(cf.getString("Logging/consoleLevel", "WARNING"))); + ch.setFormatter(new LogEntryFormatter(format, dateFormat, false)); + logger.addHandler(ch); + } + ObjectMap loggerLevels = cf.getObject("Logging/levels", ObjectMap.class); + if (loggerLevels != null) + for (String l : loggerLevels.keySet()) + Logger.getLogger(l).setLevel(loggerLevels.get(l, Level.class)); + } + + /** + * Method used to create (but not start) an instance of a Jetty server. + * + * <p> + * Subclasses can override this method to customize the Jetty server before it is started. + * + * <p> + * The default implementation is configured by the following values in the config file + * if a jetty.xml is not specified via a <code>REST/jettyXml</code> setting: + * <p class='bcode'> + * <cc>#================================================================================ + * # REST settings + * #================================================================================</cc> + * <cs>[REST]</cs> + * + * <cc># The HTTP port number to use. + * # Default is Rest-Port setting in manifest file, or 8000. + * # Can also specify a comma-delimited lists of ports to try, including 0 meaning + * # try a random port.</cc> + * <ck>port</ck> = 10000 + * + * <cc># The context root of the Jetty server. + * # Default is Rest-ContextPath in manifest file, or "/".</cc> + * <ck>contextPath</ck> = + * + * <cc># Enable SSL support.</cc> + * <ck>useSsl</ck> = false + * + * @return The newly-created server. + * @throws Exception + */ + protected Server createServer() throws Exception { + onCreateServer(); + + ConfigFile cf = getConfig(); + ObjectMap mf = getManifest(); + if (jettyXml == null) + jettyXml = cf.getString("REST/jettyXml", mf.getString("Rest-JettyXml", null)); + if (jettyXml != null) { + InputStream is = null; + if (jettyXml instanceof String) { + jettyXml = new File(jettyXml.toString()); + } + if (jettyXml instanceof File) { + File f = (File)jettyXml; + if (f.exists()) + is = new FileInputStream((File)jettyXml); + else + throw new FormattedRuntimeException("Jetty.xml file ''{0}'' was specified but not found on the file system.", jettyXml); + } else if (jettyXml instanceof InputStream) { + is = (InputStream)jettyXml; + } + + XmlConfiguration config = new XmlConfiguration(is); + server = (Server)config.configure(); + + } else { + int[] ports = cf.getObjectWithDefault("REST/port", mf.getWithDefault("Rest-Port", new int[]{8000}, int[].class), int[].class); + + port = findOpenPort(ports); + if (port == 0) { + System.err.println("Open port not found. Tried " + JsonSerializer.DEFAULT_LAX.toString(ports)); + System.exit(1); + } + + contextPath = cf.getString("REST/contextPath", mf.getString("Rest-ContextPath", "/")); + server = new Server(port); + + servletContextHandler = new ServletContextHandler(ServletContextHandler.SESSIONS); + + servletContextHandler.setContextPath(contextPath); + server.setHandler(servletContextHandler); + + for (Map.Entry<String,Class<? extends Servlet>> e : getResourceMap().entrySet()) + servletContextHandler.addServlet(e.getValue(), e.getKey()).setInitOrder(0); + } + + return server; + } + + /** + * Adds an arbitrary servlet to this microservice. + * + * @param servlet The servlet instance. + * @param pathSpec The context path of the servlet. + * @return This object (for method chaining). + * @throws RuntimeException if {@link #createServer()} has not previously been called. + */ + public RestMicroservice addServlet(Servlet servlet, String pathSpec) { + if (servletContextHandler == null) + throw new RuntimeException("Servlet context handler not found. createServer() must be called first."); + ServletHolder sh = new ServletHolder(servlet); + servletContextHandler.addServlet(sh, pathSpec); + return this; + } + + /** + * Adds a servlet attribute to the Jetty server. + * + * @param name The server attribute name. + * @param value The context path of the servlet. + * @return This object (for method chaining). + * @throws RuntimeException if {@link #createServer()} has not previously been called. + */ + public RestMicroservice addServletAttribute(String name, Object value) { + if (server == null) + throw new RuntimeException("Server not found. createServer() must be called first."); + server.setAttribute(name, value); + return this; + } + + /** + * Returns the underlying Jetty server. + * + * @return The underlying Jetty server, or <jk>null</jk> if {@link #createServer()} has not yet been called. + */ + public Server getServer() { + return server; + } + + private static int findOpenPort(int[] ports) { + for (int port : ports) { + try { + // If port is 0, try a random port between ports[0] and 32767. + if (port == 0) + port = new Random().nextInt(32767 - ports[0] + 1) + ports[0]; + ServerSocket ss = new ServerSocket(port); + ss.close(); + return port; + } catch (IOException e) {} + } + return 0; + } + + /** + * Method used to start the Jetty server created by {@link #createServer()}. + * + * <p> + * Subclasses can override this method to customize server startup. + * + * @return The port that this server started on. + * @throws Exception + */ + protected int startServer() throws Exception { + onStartServer(); + server.start(); + this.port = ((ServerConnector)server.getConnectors()[0]).getLocalPort(); + logger.warning("Server started on port " + port); + onPostStartServer(); + return port; + } + + /** + * Returns the resource map to use for this microservice. + * + * <p> + * Subclasses can override this method to programmatically specify their resources. + * + * <p> + * The default implementation is configured by the following values in the config file: + * <p class='bcode'> + * + * <cc>#================================================================================ + * # REST settings + * #================================================================================</cc> + * <cs>[REST]</cs> + * + * <cc># A JSON map of servlet paths to servlet classes. + * # Example: + * # resourceMap = {'/*':'com.foo.MyServlet'} + * # Either resourceMap or resources must be specified if it's not defined in + * # the manifest file.</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 if it's not defined in + * # the manifest file.</cc> + * <ck>resources</ck> = + * </p> + * + * <p> + * In most cases, the rest resources will be specified in the manifest file since it's not likely to be a + * configurable property: + * <p class='bcode'> + * <mk>Rest-Resources:</mk> org.apache.juneau.microservice.sample.RootResources + * </p> + * + * @return The map of REST resources. + * @throws ClassNotFoundException + * @throws ParseException + */ + @SuppressWarnings("unchecked") + protected Map<String,Class<? extends Servlet>> getResourceMap() throws ClassNotFoundException, ParseException { + ConfigFile cf = getConfig(); + ObjectMap mf = getManifest(); + Map<String,Class<? extends Servlet>> rm = new LinkedHashMap<String,Class<? extends Servlet>>(); + + ObjectMap resourceMap = cf.getObject("REST/resourceMap", ObjectMap.class); + String[] resources = cf.getStringArray("REST/resources", mf.getStringArray("Rest-Resources")); + + if (resourceMap != null && ! resourceMap.isEmpty()) { + for (Map.Entry<String,Object> e : resourceMap.entrySet()) { + Class<?> c = Class.forName(e.getValue().toString()); + if (! isParentClass(Servlet.class, c)) + throw new ClassNotFoundException("Invalid class specified as resource. Must be a Servlet. Class='"+c.getName()+"'"); + rm.put(e.getKey(), (Class<? extends Servlet>)c); + } + } else if (resources.length > 0) { + for (String resource : resources) { + Class<?> c = Class.forName(resource); + if (! isParentClass(Servlet.class, c)) + throw new ClassNotFoundException("Invalid class specified as resource. Must be a Servlet. Class='"+c.getName()+"'"); + RestResource rr = c.getAnnotation(RestResource.class); + String path = rr == null ? "/*" : rr.path(); + if (! path.endsWith("*")) + path += (path.endsWith("/") ? "*" : "/*"); + rm.put(path, (Class<? extends Servlet>)c); + } + } + return rm; + } + + /** + * Called when {@link ConfigFile#save()} is called on the config file. + * + * <p> + * The default behavior is configured by the following value in the config file: + * <p class='bcode'> + * <cs>[REST]</cs> + * + * <cc># What to do when the config file is saved. + * # Possible values: + * # NOTHING - Don't do anything. (default) + * # RESTART_SERVER - Restart the Jetty server. + * # RESTART_SERVICE - Shutdown and exit with code '3'.</cc> + * <ck>saveConfigAction</ck> = RESTART_SERVER + * </p> + */ + @Override /* Microservice */ + protected void onConfigSave(ConfigFile cf) { + try { + String saveConfigAction = cf.getString("REST/saveConfigAction", "NOTHING"); + if (saveConfigAction.equals("RESTART_SERVER")) { + new Thread() { + @Override /* Thread */ + public void run() { + try { + RestMicroservice.this.stop(); + RestMicroservice.this.start(); + } catch (Exception e) { + logger.log(Level.SEVERE, e.getLocalizedMessage(), e); + } + } + }.start(); + } else if (saveConfigAction.equals("RESTART_SERVICE")) { + stop(); + System.exit(3); + } + } catch (Exception e) { + throw new RuntimeException(e); + } + } + + /** + * Sets the <code>jetty.xml</code> used to configure the Jetty server. + * + * <p> + * + * @param jettyXml + * The <code>jetty.xml</code>. + * <br>Can be any of the following: + * <ul> + * <li>A {@link File} representing the location on the file system. + * <li>An {@link InputStream} containing the contents of the file. + * <li>A {@link String} representing the file system path. + * </ul> + * @return This object (for method chaining). + */ + public RestMicroservice setJettyXml(Object jettyXml) { + if (jettyXml instanceof String || jettyXml instanceof File || jettyXml instanceof InputStream) + this.jettyXml = jettyXml; + else + throw new FormattedRuntimeException("Invalid object type passed to setJettyXml()", jettyXml == null ? null : jettyXml.getClass().getName()); + return this; + } + + + //-------------------------------------------------------------------------------- + // Lifecycle listener methods. + //-------------------------------------------------------------------------------- + + /** + * Called before {@link #createServer()} is called. + * + * <p> + * Subclasses can override this method to hook into the lifecycle of this application. + */ + protected void onCreateServer() {} + + /** + * Called before {@link #startServer()} is called. + * + * <p> + * Subclasses can override this method to hook into the lifecycle of this application. + */ + protected void onStartServer() {} + + /** + * Called after the Jetty server is started. + * + * <p> + * Subclasses can override this method to hook into the lifecycle of this application. + */ + protected void onPostStartServer() {} + + /** + * Called before the Jetty server is stopped. + * + * <p> + * Subclasses can override this method to hook into the lifecycle of this application. + */ + protected void onStopServer() {} + + /** + * Called after the Jetty server is stopped. + * + * <p> + * Subclasses can override this method to hook into the lifecycle of this application. + */ + protected void onPostStopServer() {} + + + //-------------------------------------------------------------------------------- + // Overridden methods. + //-------------------------------------------------------------------------------- + + @Override /* Microservice */ + public RestMicroservice setConfig(String cfPath, boolean create) throws IOException { + super.setConfig(cfPath, create); + return this; + } + + @Override /* Microservice */ + public RestMicroservice setManifestContents(String...contents) throws IOException { + super.setManifestContents(contents); + return this; + } +}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/build1.png ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/build1.png b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/build1.png new file mode 100755 index 0000000..008c6b5 Binary files /dev/null and b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/build1.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/build2.png ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/build2.png b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/build2.png new file mode 100755 index 0000000..9e55346 Binary files /dev/null and b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/build2.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/helloworld1.png ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/helloworld1.png b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/helloworld1.png new file mode 100755 index 0000000..f5f0c7c Binary files /dev/null and b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/helloworld1.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions1.png ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions1.png b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions1.png new file mode 100755 index 0000000..1234828 Binary files /dev/null and b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions1.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions2.png ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions2.png b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions2.png new file mode 100755 index 0000000..4589f19 Binary files /dev/null and b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions2.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions3.png ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions3.png b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions3.png new file mode 100755 index 0000000..21808c0 Binary files /dev/null and b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions3.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions4.png ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions4.png b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions4.png new file mode 100755 index 0000000..b5e8471 Binary files /dev/null and b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions4.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions5.png ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions5.png b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions5.png new file mode 100755 index 0000000..50504de Binary files /dev/null and b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions5.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions6.png ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions6.png b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions6.png new file mode 100755 index 0000000..e730d32 Binary files /dev/null and b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/instructions6.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/manifest1.png ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/manifest1.png b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/manifest1.png new file mode 100755 index 0000000..77604c1 Binary files /dev/null and b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/doc-files/manifest1.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/package.html ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/package.html b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/package.html new file mode 100755 index 0000000..2b29358 --- /dev/null +++ b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/package.html @@ -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 http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigEdit.html ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigEdit.html b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigEdit.html new file mode 100755 index 0000000..f02609b --- /dev/null +++ b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigEdit.html @@ -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> + http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/750916a9/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java ---------------------------------------------------------------------- diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java new file mode 100755 index 0000000..9f0abb0 --- /dev/null +++ b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java @@ -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; + } +}
