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:25:37 UTC
svn commit: r21540 [17/27] - in /release/incubator/juneau:
juneau-rest-client/ juneau-rest-client/.settings/ juneau-rest-client/bin/
juneau-rest-client/src/ juneau-rest-client/src/main/
juneau-rest-client/src/main/java/ juneau-rest-client/src/main/java...
Added: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HookEvent.java
==============================================================================
--- release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HookEvent.java (added)
+++ release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HookEvent.java Fri Sep 8 23:25:34 2017
@@ -0,0 +1,435 @@
+// ***************************************************************************************************************************
+// * 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.rest.annotation;
+
+import java.io.*;
+import java.util.*;
+import java.util.logging.*;
+
+import javax.servlet.*;
+import javax.servlet.http.*;
+
+import org.apache.juneau.*;
+import org.apache.juneau.dto.swagger.*;
+import org.apache.juneau.http.*;
+import org.apache.juneau.ini.*;
+import org.apache.juneau.internal.*;
+import org.apache.juneau.rest.*;
+import org.apache.juneau.utils.*;
+
+/**
+ * Identifies servlet and REST call lifecycle events which cause {@link RestHook @RestHook}-annotated Java methods
+ * to be called.
+ */
+public enum HookEvent {
+
+ /**
+ * Identifies a method that should be called immediately after the <code>HttpServlet.service(HttpServletRequest, HttpServletResponse)</code>
+ * method is called.
+ *
+ * <p>
+ * Note that you only have access to the raw request and response objects at this point.
+ *
+ * <p>
+ * The list of valid parameter types are as follows:
+ * <ul>
+ * <li>Servlet request/response objects:
+ * <ul>
+ * <li>{@link HttpServletRequest}
+ * <li>{@link HttpServletResponse}
+ * </ul>
+ * </ul>
+ *
+ * <h6 class='figure'>Example:</h6>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(...)
+ * <jk>public class</jk> MyResource <jk>extends</jk> RestServletDefault {
+ *
+ * <jc>// Add a request attribute to all incoming requests.</jc>
+ * <ja>@RestHook</ja>(<jsf>START_CALL</jsf>)
+ * <jk>public void</jk> onStartCall(HttpServletRequest req) {
+ * req.setAttribute(<js>"foobar"</js>, <jk>new</jk> FooBar());
+ * }
+ * }
+ * </p>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>The method should return <jk>void</jk> although if it does return any value, the value will be ignored.
+ * <li>The method should be <jk>public</jk> although other visibilities are valid if the security manager allows it.
+ * <li>Static methods can be used.
+ * <li>Multiple START_CALL methods can be defined on a class.
+ * <br>START_CALL methods on parent classes are invoked before START_CALL methods on child classes.
+ * <br>The order of START_CALL method invocations within a class is alphabetical, then by parameter count, then by parameter types.
+ * <li>The method can throw any exception.
+ * <br>{@link RestException RestExceptions} can be thrown to cause a particular HTTP error status code.
+ * <br>All other exceptions cause an HTTP 500 error status code.
+ * <li>Note that if you override a parent method, you probably need to call <code><jk>super</jk>.parentMethod(...)</code>.
+ * <br>The method is still considered part of the parent class for ordering purposes even though it's
+ * overridden by the child class.
+ * </ul>
+ */
+ START_CALL,
+
+ /**
+ * Identifies a method that gets called immediately before the <ja>@RestMethod</ja> annotated method gets called.
+ *
+ * <p>
+ * At this point, the {@link RestRequest} object has been fully initialized, and all {@link RestGuard} and
+ * {@link RestMatcher} objects have been called.
+ *
+ * <p>
+ * The list of valid parameter types are as follows:
+ * <ul>
+ * <li>Servlet request/response objects:
+ * <ul>
+ * <li>{@link HttpServletRequest}
+ * <li>{@link HttpServletResponse}
+ * </ul>
+ * <li>Extended request/response objects:
+ * <ul>
+ * <li>{@link RestRequest}
+ * <li>{@link RestResponse}
+ * </ul>
+ * <li>Header objects:
+ * <ul>
+ * <li>{@link Accept}
+ * <li>{@link AcceptCharset}
+ * <li>{@link AcceptEncoding}
+ * <li>{@link AcceptLanguage}
+ * <li>{@link Authorization}
+ * <li>{@link CacheControl}
+ * <li>{@link Connection}
+ * <li>{@link ContentLength}
+ * <li>{@link ContentType}
+ * <li>{@link org.apache.juneau.http.Date}
+ * <li>{@link Expect}
+ * <li>{@link From}
+ * <li>{@link Host}
+ * <li>{@link IfMatch}
+ * <li>{@link IfModifiedSince}
+ * <li>{@link IfNoneMatch}
+ * <li>{@link IfRange}
+ * <li>{@link IfUnmodifiedSince}
+ * <li>{@link MaxForwards}
+ * <li>{@link Pragma}
+ * <li>{@link ProxyAuthorization}
+ * <li>{@link Range}
+ * <li>{@link Referer}
+ * <li>{@link TE}
+ * <li>{@link UserAgent}
+ * <li>{@link Upgrade}
+ * <li>{@link Via}
+ * <li>{@link Warning}
+ * <li>{@link TimeZone}
+ * </ul>
+ * <li>Other objects:
+ * <ul>
+ * <li>{@link ResourceBundle}
+ * <li>{@link MessageBundle}
+ * <li>{@link InputStream}
+ * <li>{@link ServletInputStream}
+ * <li>{@link Reader}
+ * <li>{@link OutputStream}
+ * <li>{@link ServletOutputStream}
+ * <li>{@link Writer}
+ * <li>{@link RequestHeaders}
+ * <li>{@link RequestQuery}
+ * <li>{@link RequestFormData}
+ * <li>{@link HttpMethod}
+ * <li>{@link Logger}
+ * <li>{@link JuneauLogger}
+ * <li>{@link RestContext}
+ * <li>{@link org.apache.juneau.parser.Parser}
+ * <li>{@link Locale}
+ * <li>{@link Swagger}
+ * <li>{@link RequestPathMatch}
+ * <li>{@link RequestBody}
+ * <li>{@link ConfigFile}
+ * <li>{@link UriContext}
+ * <li>{@link UriResolver}
+ * </ul>
+ * </ul>
+ *
+ * <h6 class='figure'>Example:</h6>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(...)
+ * <jk>public class</jk> MyResource <jk>extends</jk> RestServletDefault {
+ *
+ * <jc>// Log the incoming request.</jc>
+ * <ja>@RestHook</ja>(<jsf>PRE_CALL</jsf>)
+ * <jk>public void</jk> onPreCall(Accept accept, Logger logger) {
+ * logger.fine(<js>"Accept {0} header found."</js>, accept);
+ * }
+ * }
+ * </p>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>The method should return <jk>void</jk> although if it does return any value, the value will be ignored.
+ * <li>The method should be <jk>public</jk> although other visibilities are valid if the security manager allows it.
+ * <li>Static methods can be used.
+ * <li>Multiple PRE_CALL methods can be defined on a class.
+ * <br>PRE_CALL methods on parent classes are invoked before PRE_CALL methods on child classes.
+ * <br>The order of PRE_CALL method invocations within a class is alphabetical, then by parameter count, then by parameter types.
+ * <li>The method can throw any exception.
+ * <br>{@link RestException RestExceptions} can be thrown to cause a particular HTTP error status code.
+ * <br>All other exceptions cause an HTTP 500 error status code.
+ * <li>Note that if you override a parent method, you probably need to call <code><jk>super</jk>.parentMethod(...)</code>.
+ * <br>The method is still considered part of the parent class for ordering purposes even though it's
+ * overridden by the child class.
+ * <li>It's advisable not to mess around with the HTTP body itself since you may end up consuming the body
+ * before the actual REST method has a chance to use it.
+ * </ul>
+ */
+ PRE_CALL,
+
+ /**
+ * Identifies a method that gets called immediately after the <ja>@RestMethod</ja> annotated method gets called.
+ *
+ * <p>
+ * At this point, the output object returned by the method call has been set on the response, but
+ * {@link RestConverter RestConverters} have not yet been executed and the response has not yet been written.
+ *
+ * <p>
+ * The list of valid parameter types are the same as {@link #PRE_CALL}.
+ *
+ * <h6 class='figure'>Example:</h6>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(...)
+ * <jk>public class</jk> MyResource <jk>extends</jk> RestServletDefault {
+ *
+ * <jc>// Log the result of the request.</jc>
+ * <ja>@RestHook</ja>(<jsf>POST_CALL</jsf>)
+ * <jk>public void</jk> onPostCall(RestResponse res, Logger logger) {
+ * logger.fine(<js>Output {0} was set on the response."</js>, res.getOutput());
+ * }
+ * }
+ * </p>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>The method should return <jk>void</jk> although if it does return any value, the value will be ignored.
+ * <li>The method should be <jk>public</jk> although other visibilities are valid if the security manager allows it.
+ * <li>Static methods can be used.
+ * <li>Multiple POST_CALL methods can be defined on a class.
+ * <br>POST_CALL methods on parent classes are invoked before POST_CALL methods on child classes.
+ * <br>The order of POST_CALL method invocations within a class is alphabetical, then by parameter count, then by parameter types.
+ * <li>The method can throw any exception, although at this point it is too late to set an HTTP error status code.
+ * <li>Note that if you override a parent method, you probably need to call <code><jk>super</jk>.parentMethod(...)</code>.
+ * <br>The method is still considered part of the parent class for ordering purposes even though it's
+ * overridden by the child class.
+ * </ul>
+ */
+ POST_CALL,
+
+ /**
+ * Identifies a method that gets called right before we exit the servlet service method.
+ *
+ * <p>
+ * At this point, the output has been written and flushed.
+ *
+ * <p>
+ * The list of valid parameter types are as follows:
+ * <ul>
+ * <li>Servlet request/response objects:
+ * <ul>
+ * <li>{@link HttpServletRequest}
+ * <li>{@link HttpServletResponse}
+ * </ul>
+ * </ul>
+ *
+ * <p>
+ * The following attributes are set on the {@link HttpServletRequest} object that can be useful for logging purposes:
+ * <ul>
+ * <li><js>"Exception"</js> - Any exceptions thrown during the request.
+ * <li><js>"ExecTime"</js> - Execution time of the request.
+ * </ul>
+ *
+ * <h6 class='figure'>Example:</h6>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(...)
+ * <jk>public class</jk> MyResource <jk>extends</jk> RestServletDefault {
+ *
+ * <jc>// Log the time it took to execute the request.</jc>
+ * <ja>@RestHook</ja>(<jsf>END_CALL</jsf>)
+ * <jk>public void</jk> onEndCall(RestRequest req, Logger logger) {
+ * Exception e = (Exception)req.getAttribute(<js>"Exception"</js>);
+ * Long execTime = (Long)req.getAttribute(<js>"ExecTime"</js>);
+ * <jk>if</jk> (e != <jk>null</jk>)
+ * logger.warn(e, <js>"Request failed in {0}ms."</js>, execTime);
+ * <jk>else</jk>
+ * logger.fine(<js>"Request finished in {0}ms."</js>, execTime);
+ * }
+ * }
+ * </p>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>The method should return <jk>void</jk> although if it does return any value, the value will be ignored.
+ * <li>The method should be <jk>public</jk> although other visibilities are valid if the security manager allows it.
+ * <li>Static methods can be used.
+ * <li>Multiple END_CALL methods can be defined on a class.
+ * <br>END_CALL methods on parent classes are invoked before END_CALL methods on child classes.
+ * <br>The order of END_CALL method invocations within a class is alphabetical, then by parameter count, then by parameter types.
+ * <li>The method can throw any exception, although at this point it is too late to set an HTTP error status code.
+ * <li>Note that if you override a parent method, you probably need to call <code><jk>super</jk>.parentMethod(...)</code>.
+ * <br>The method is still considered part of the parent class for ordering purposes even though it's
+ * overridden by the child class.
+ * </ul>
+ */
+ END_CALL,
+
+ /**
+ * Identifies a method that gets called during servlet initialization.
+ *
+ * <p>
+ * This method is called from within the {@link Servlet#init(ServletConfig)} method after the {@link RestConfig}
+ * object has been created and initialized with the annotations defined on the class, but before the
+ * {@link RestContext} object has been created.
+ *
+ * <p>
+ * The only valid parameter type for this method is {@link RestConfig} which can be used to configure the servlet.
+ *
+ * <p>
+ * An example of this is the <code>PetStoreResource</code> class that uses an init method to perform initialization
+ * of an internal data structure.
+ *
+ * <h6 class='figure'>Example:</h6>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(...)
+ * <jk>public class</jk> PetStoreResource <jk>extends</jk> ResourceJena {
+ *
+ * <jc>// Our database.</jc>
+ * <jk>private</jk> Map<Integer,Pet> <jf>petDB</jf>;
+ *
+ * <ja>@RestHook</ja>(<jsf>INIT</jsf>)
+ * <jk>public void</jk> onInit(RestConfig config) <jk>throws</jk> Exception {
+ * <jc>// Load our database from a local JSON file.</jc>
+ * <jf>petDB</jf> = JsonParser.<jsf>DEFAULT</jsf>.parse(getClass().getResourceAsStream(<js>"PetStore.json"</js>), LinkedHashMap.<jk>class</jk>, Integer.<jk>class</jk>, Pet.<jk>class</jk>);
+ * }
+ * }
+ * </p>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>The method should return <jk>void</jk> although if it does return any value, the value will be ignored.
+ * <li>The method should be <jk>public</jk> although other visibilities are valid if the security manager allows it.
+ * <li>Static methods can be used.
+ * <li>Multiple INIT methods can be defined on a class.
+ * <br>INIT methods on parent classes are invoked before INIT methods on child classes.
+ * <br>The order of INIT method invocations within a class is alphabetical, then by parameter count, then by parameter types.
+ * <li>The method can throw any exception causing initialization of the servlet to fail.
+ * <li>Note that if you override a parent method, you probably need to call <code><jk>super</jk>.parentMethod(...)</code>.
+ * <br>The method is still considered part of the parent class for ordering purposes even though it's
+ * overridden by the child class.
+ * </ul>
+ */
+ INIT,
+
+ /**
+ * Identifies a method that gets called immediately after servlet initialization.
+ *
+ * <p>
+ * This method is called from within the {@link Servlet#init(ServletConfig)} method after the {@link RestContext}
+ * object has been created.
+ *
+ * <p>
+ * The only valid parameter type for this method is {@link RestContext} which can be used to retrieve information
+ * about the servlet.
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>The method should return <jk>void</jk> although if it does return any value, the value will be ignored.
+ * <li>The method should be <jk>public</jk> although other visibilities are valid if the security manager allows it.
+ * <li>Static methods can be used.
+ * <li>Multiple POST_INIT methods can be defined on a class.
+ * <br>POST_INIT methods on parent classes are invoked before POST_INIT methods on child classes.
+ * <br>The order of POST_INIT method invocations within a class is alphabetical, then by parameter count, then by parameter types.
+ * <li>The method can throw any exception causing initialization of the servlet to fail.
+ * <li>Note that if you override a parent method, you probably need to call <code><jk>super</jk>.parentMethod(...)</code>.
+ * <br>The method is still considered part of the parent class for ordering purposes even though it's
+ * overridden by the child class.
+ * </ul>
+ */
+ POST_INIT,
+
+ /**
+ * Identical to {@link #POST_INIT} except the order of execution is child-resources first.
+ *
+ * <p>
+ * Use this annotation if you need to perform any kind of initialization on child resources before the parent resource.
+ *
+ * <p>
+ * This method is called from within the {@link Servlet#init(ServletConfig)} method after the {@link RestContext}
+ * object has been created and after the {@link #POST_INIT} methods have been called.
+ *
+ * <p>
+ * The only valid parameter type for this method is {@link RestContext} which can be used to retrieve information
+ * about the servlet.
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>The method should return <jk>void</jk> although if it does return any value, the value will be ignored.
+ * <li>The method should be <jk>public</jk> although other visibilities are valid if the security manager allows it.
+ * <li>Static methods can be used.
+ * <li>Multiple POST_INIT_CHILD_FIRST methods can be defined on a class.
+ * <br>POST_INIT_CHILD_FIRST methods on parent classes are invoked before POST_INIT_CHILD_FIRST methods on child classes.
+ * <br>The order of POST_INIT_CHILD_FIRST method invocations within a class is alphabetical, then by parameter count, then by parameter types.
+ * <li>The method can throw any exception causing initialization of the servlet to fail.
+ * </ul>
+ */
+ POST_INIT_CHILD_FIRST,
+
+ /**
+ * Identifies a method that gets called during servlet destroy.
+ *
+ * <p>
+ * This method is called from within the {@link Servlet#destroy()}.
+ *
+ * <p>
+ * The only valid parameter type for this method is {@link RestContext}, although typically no arguments will
+ * be specified.
+ *
+ * <h6 class='figure'>Example:</h6>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(...)
+ * <jk>public class</jk> PetStoreResource <jk>extends</jk> ResourceJena {
+ *
+ * <jc>// Our database.</jc>
+ * <jk>private</jk> Map<Integer,Pet> <jf>petDB</jf>;
+ *
+ * <ja>@RestHook</ja>(<jsf>DESTROY</jsf>)
+ * <jk>public void</jk> onDestroy() {
+ * <jf>petDB</jf> = <jk>null</jk>;
+ * }
+ * }
+ * </p>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>The method should return <jk>void</jk> although if it does return any value, the value will be ignored.
+ * <li>The method should be <jk>public</jk> although other visibilities are valid if the security manager allows it.
+ * <li>Static methods can be used.
+ * <li>Multiple DESTROY methods can be defined on a class.
+ * <br>DESTROY methods on child classes are invoked before DESTROY methods on parent classes.
+ * <br>The order of DESTROY method invocations within a class is alphabetical, then by parameter count, then by parameter types.
+ * <li>In general, destroy methods should not throw any exceptions, although if any are thrown, the stack trace will be
+ * printed to <code>System.err</code>.
+ * <li>Note that if you override a parent method, you probably need to call <code><jk>super</jk>.parentMethod(...)</code>.
+ * <br>The method is still considered part of the parent class for ordering purposes even though it's
+ * overridden by the child class.
+ * </ul>
+ */
+ DESTROY
+}
Propchange: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HookEvent.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HtmlDoc.java
==============================================================================
--- release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HtmlDoc.java (added)
+++ release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HtmlDoc.java Fri Sep 8 23:25:34 2017
@@ -0,0 +1,473 @@
+// ***************************************************************************************************************************
+// * 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.rest.annotation;
+
+import org.apache.juneau.*;
+import org.apache.juneau.html.*;
+import org.apache.juneau.rest.*;
+import org.apache.juneau.rest.widget.*;
+
+/**
+ * Contains all the configurable annotations for the {@link HtmlDocSerializer}.
+ *
+ * <p>
+ * Used with {@link RestResource#htmldoc()} and {@link RestMethod#htmldoc()} to customize the HTML view of serialized
+ * POJOs.
+ *
+ * <p>
+ * All annotations specified here have no effect on any serializers other than {@link HtmlDocSerializer} and is
+ * provided as a shorthand method of for specifying configuration properties.
+ *
+ * <p>
+ * For example, the following two methods for defining the HTML document title are considered equivalent:
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * properties={
+ * <ja>@Property</ja>(name=<jsf>HTMLDOC_title</jsf>, value=<js>"My Resource Page"</js>)
+ * }
+ * )
+ *
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * title=<js>"My Resource Page"</js>
+ * )
+ * )
+ * </p>
+ *
+ * <p>
+ * The purpose of these annotation is to populate the HTML document view which by default consists of the following
+ * structure:
+ * <p class='bcode'>
+ * <xt><html>
+ * <head>
+ * <style <xa>type</xa>=<xs>'text/css'</xs>>
+ * <xv>CSS styles and links to stylesheets</xv>
+ * </style>
+ * </head>
+ * <body>
+ * <header>
+ * <xv>Page header</xv>
+ * </header>
+ * <nav>
+ * <xv>Page links</xv>
+ * </nav>
+ * <aside>
+ * <xv>Side-bar page links</xv>
+ * </aside>
+ * <article>
+ * <xv>Contents of serialized object</xv>
+ * </article>
+ * <footer>
+ * <xv>Footer message</xv>
+ * </footer>
+ * </body>
+ * </html></xt>
+ * </p>
+ */
+public @interface HtmlDoc {
+
+ /**
+ * Sets the HTML header section contents.
+ *
+ * <p>
+ * The format of this value is HTML.
+ *
+ * <p>
+ * The page header normally contains the title and description, but this value can be used to override the contents
+ * to be whatever you want.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * header={
+ * <js>"<p>This is my REST interface</p>"</js>
+ * }
+ * )
+ * )
+ * </p>
+ *
+ * <h6 class='topic'>Other Notes</h6>
+ * <ul class='spaced-list'>
+ * <li>
+ * A value of <js>"NONE"</js> can be used to force no header.
+ * <li>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of supported variables.
+ * <li>
+ * Multiple values are combined with newlines into a single string.
+ * <li>
+ * The programmatic equivalent to this annotation are the
+ * {@link RestConfig#setHtmlHeader(String)} and {@link RestResponse#setHtmlHeader(Object)} methods.
+ * <li>
+ * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class.
+ * <li>
+ * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the
+ * parent class if not overridden.
+ * <li>
+ * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value.
+ * </ul>
+ */
+ String[] header() default {};
+
+ /**
+ * Sets the links in the HTML nav section.
+ *
+ * <p>
+ * The value is an array of strings with two possible values:
+ * <ul>
+ * <li>A key-value pair representing a hyperlink label and href:
+ * <br><js>"google: http://google.com"</js>
+ * <li>Arbitrary HTML.
+ * </ul>
+ *
+ * <p>
+ * The page links are positioned immediately under the title and text.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * links={
+ * <js>"up: request:/.."</js>,
+ * <js>"options: servlet:/?method=OPTIONS"</js>
+ * }
+ * )
+ * )
+ * </p>
+ *
+ * <h6 class='topic'>Other Notes</h6>
+ * <ul class='spaced-list'>
+ * <li>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of supported variables.
+ * <li>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <li>
+ * This field can also use URIs of any support type in {@link UriResolver}.
+ * <li>
+ * The programmatic equivalent to this annotation are the
+ * {@link RestConfig#setHtmlLinks(String[])} and {@link RestResponse#setHtmlLinks(String[])} methods.
+ * <li>
+ * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class.
+ * <li>
+ * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the
+ * parent class.
+ * <li>
+ * The parent links can be included by adding the literal <js>"INHERIT"</js> as a value.
+ * <br>Use the syntax <js>"key[index]: value"</js> or <js>"[index]: value"</js> to specify an index location
+ * to place a link inside the list of parent links.
+ * </ul>
+ */
+ String[] links() default {};
+
+ /**
+ * Sets the HTML nav section contents.
+ *
+ * <p>
+ * The format of this value is HTML.
+ *
+ * <p>
+ * The nav section of the page contains the links.
+ *
+ * <p>
+ * The format of this value is HTML.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * nav={
+ * <js>"<p>Custom nav content</p>"</js>
+ * }
+ * )
+ * )
+ * </p>
+ *
+ * <h6 class='topic'>Other Notes</h6>
+ * <ul class='spaced-list'>
+ * <li>
+ * When a value is specified, the {@link #links()} value will be ignored.
+ * <li>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of supported variables.
+ * <li>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <li>
+ * Multiple values are combined with newlines into a single string.
+ * <li>
+ * The programmatic equivalent to this annotation are the
+ * {@link RestConfig#setHtmlNav(String)} and {@link RestResponse#setHtmlNav(Object)} methods.
+ * <li>
+ * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class.
+ * <li>
+ * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the
+ * parent class.
+ * <li>
+ * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value.
+ * </ul>
+ */
+ String[] nav() default {};
+
+ /**
+ * Sets the HTML aside section contents.
+ *
+ * <p>
+ * The format of this value is HTML.
+ *
+ * <p>
+ * The aside section typically floats on the right side of the page.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * aside={
+ * <js>"<p>Custom aside content</p>"</js>
+ * }
+ * )
+ * )
+ * </p>
+ *
+ * <h6 class='topic'>Other Notes</h6>
+ * <ul class='spaced-list'>
+ * <li>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of supported variables.
+ * <li>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <li>
+ * Multiple values are combined with newlines into a single string.
+ * <li>
+ * The programmatic equivalent to this annotation are the
+ * {@link RestConfig#setHtmlAside(String)} and {@link RestResponse#setHtmlAside(Object)} methods.
+ * <li>
+ * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class.
+ * <li>
+ * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the
+ * parent class.
+ * <li>
+ * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value.
+ * </ul>
+ */
+ String[] aside() default {};
+
+ /**
+ * Sets the HTML footer section contents.
+ *
+ * <p>
+ * The format of this value is HTML.
+ *
+ * <p>
+ * The footer section typically floats on the bottom of the page.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * footer={
+ * <js>"<p>Custom footer content</p>"</js>
+ * }
+ * )
+ * )
+ * </p>
+ *
+ * <h6 class='topic'>Other Notes</h6>
+ * <ul class='spaced-list'>
+ * <li>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of supported variables.
+ * <li>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <li>
+ * Multiple values are combined with newlines into a single string.
+ * <li>
+ * The programmatic equivalent to this annotation are the
+ * {@link RestConfig#setHtmlFooter(String)} and {@link RestResponse#setHtmlFooter(Object)} methods.
+ * <li>
+ * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class.
+ * <li>
+ * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the
+ * parent class.
+ * <li>
+ * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value.
+ * </ul>
+ */
+ String[] footer() default {};
+
+ /**
+ * Sets the HTML CSS style section contents.
+ *
+ * <p>
+ * The format of this value is CSS.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * style={
+ * <js>".red{color:red;}"</js>,
+ * <js>".blue{color:blue;}"</js>
+ * }
+ * )
+ * )
+ * </p>
+ *
+ * <h6 class='topic'>Other Notes</h6>
+ * <ul class='spaced-list'>
+ * <li>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of supported variables.
+ * <li>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <li>
+ * Multiple values are combined with newlines into a single string.
+ * <li>
+ * The programmatic equivalent to this annotation are the
+ * {@link RestConfig#setHtmlStyle(String)} and {@link RestResponse#setHtmlStyle(Object)} methods.
+ * <li>
+ * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class.
+ * <li>
+ * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the
+ * parent class.
+ * <li>
+ * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value.
+ * </ul>
+ */
+ String[] style() default {};
+
+ /**
+ * Sets the CSS URL in the HTML CSS style section.
+ *
+ * <p>
+ * The format of this value is a URL.
+ *
+ * <p>
+ * Specifies the URL to the stylesheet to add as a link in the style tag in the header.
+ *
+ * <p>
+ * The format of this value is CSS.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * stylesheet=<js>"http://someOtherHost/stealTheir.css"</js>
+ * )
+ * )
+ * </p>
+ *
+ * <h6 class='topic'>Other Notes</h6>
+ * <ul class='spaced-list'>
+ * <li>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>) and can use URL protocols
+ * defined by {@link UriResolver}.
+ * <br>See {@link RestContext#getVarResolver()} for the list of supported variables.
+ * <li>
+ * The programmatic equivalent to this annotation are the
+ * {@link RestConfig#setHtmlStylesheet(String)}/{@link RestResponse#setHtmlStylesheet(Object)} methods.
+ * <li>
+ * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class.
+ * <li>
+ * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the
+ * parent class.
+ * </ul>
+ */
+ String stylesheet() default "";
+
+ /**
+ * Sets the HTML script section contents.
+ *
+ * <p>
+ * The format of this value is Javascript.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * script={
+ * <js>"alert('Hello!')"</js>
+ * }
+ * )
+ * )
+ * </p>
+ *
+ * <h6 class='topic'>Other Notes</h6>
+ * <ul class='spaced-list'>
+ * <li>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of supported variables.
+ * <li>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <li>
+ * Multiple values are combined with newlines into a single string.
+ * <li>
+ * The programmatic equivalent to this annotation are the
+ * {@link RestConfig#setHtmlScript(String)} and {@link RestResponse#setHtmlScript(Object)} methods.
+ * <li>
+ * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class.
+ * <li>
+ * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the
+ * parent class.
+ * <li>
+ * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value.
+ * </ul>
+ */
+ String[] script() default {};
+
+ /**
+ * Shorthand method for forcing the rendered HTML content to be no-wrap.
+ *
+ * <p>
+ * This only applies to the rendered data portion of the page.
+ */
+ boolean nowrap() default false;
+
+ /**
+ * Specifies the text to display when serializing an empty array or collection.
+ */
+ String noResultsMessage() default "no results";
+
+ /**
+ * Specifies the template class to use for rendering the HTML page.
+ *
+ * <p>
+ * By default, uses {@link HtmlDocTemplateBasic} to render the contents, although you can provide your own custom
+ * renderer or subclasses from the basic class to have full control over how the page is rendered.
+ *
+ * <h6 class='topic'>Other Notes</h6>
+ * <ul class='spaced-list'>
+ * <li>
+ * The programmatic equivalent to this annotation are the
+ * {@link RestConfig#setHtmlTemplate(Class)} and {@link RestResponse#setHtmlTemplate(Class)} methods.
+ * <li>
+ * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class.
+ * <li>
+ * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the
+ * parent class.
+ * </ul>
+ */
+ Class<? extends HtmlDocTemplate> template() default HtmlDocTemplate.class;
+
+ /**
+ * Defines widgets that can be used in conjunction with string variables of the form <js>"$W{name}"</js>to quickly
+ * generate arbitrary replacement HTML.
+ *
+ * <h6 class='topic'>Other Notes</h6>
+ * <ul class='spaced-list'>
+ * <li>
+ * Widgets are inherited from parent to child, but can be overridden by reusing the widget name.
+ * </ul>
+ */
+ Class<? extends Widget>[] widgets() default {};
+}
Propchange: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HtmlDoc.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Inherit.java
==============================================================================
--- release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Inherit.java (added)
+++ release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Inherit.java Fri Sep 8 23:25:34 2017
@@ -0,0 +1,32 @@
+// ***************************************************************************************************************************
+// * 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.rest.annotation;
+
+/**
+ * Inheritance values for the {@link RestMethod#serializersInherit()} and {@link RestMethod#parsersInherit()}
+ * annotations.
+ */
+public enum Inherit {
+
+ /** Inherit serializers from parent. */
+ SERIALIZERS,
+
+ /** Inherit parsers from parent. */
+ PARSERS,
+
+ /** Inherit bean filters and POJO swaps from parent. */
+ TRANSFORMS,
+
+ /** Inherit properties from parent. */
+ PROPERTIES
+}
Propchange: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Inherit.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Messages.java
==============================================================================
--- release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Messages.java (added)
+++ release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Messages.java Fri Sep 8 23:25:34 2017
@@ -0,0 +1,51 @@
+// ***************************************************************************************************************************
+// * 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.rest.annotation;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+import java.util.*;
+
+import org.apache.juneau.utils.*;
+
+/**
+ * Annotation that can be applied to a parameter of a {@link RestMethod} annotated method to identify it as the
+ * resource bundle for the request locale.
+ *
+ * <p>
+ * Parameter type must be either {@link ResourceBundle} or {@link MessageBundle}.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>)
+ * <jk>public</jk> String doGet(<ja>@Messages</ja> ResourceBundle messages) {
+ * <jk>return</jk> messages.getString(<js>"myLocalizedMessage"</js>);
+ * }
+ * </p>
+ *
+ * <p>
+ * This is functionally equivalent to the following code...
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>)
+ * <jk>public</jk> String doGet(RestRequest req) {
+ * <jk>return</jk> req.getMessage(<js>"myLocalizedMessage"</js>);
+ * }
+ * </p>
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Inherited
+public @interface Messages {}
Propchange: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Messages.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Method.java
==============================================================================
--- release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Method.java (added)
+++ release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Method.java Fri Sep 8 23:25:34 2017
@@ -0,0 +1,50 @@
+// ***************************************************************************************************************************
+// * 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.rest.annotation;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+/**
+ * Annotation that can be applied to a parameter of a {@link RestMethod} annotated method to identify it as the HTTP
+ * method.
+ *
+ * <p>
+ * Typically used for HTTP method handlers of type <js>"*"</js> (i.e. handle all requests).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"*"</js>)
+ * <jk>public void</jk> doAnything(RestRequest req, RestResponse res, <ja>@Method</ja> String method) {
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * This is functionally equivalent to the following code...
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"*"</js>)
+ * <jk>public void</jk> doAnything(RestRequest req, RestResponse res) {
+ * String method = req.getMethod();
+ * ...
+ * }
+ * </p>
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Inherited
+public @interface Method {
+}
Propchange: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Method.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java
==============================================================================
--- release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java (added)
+++ release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java Fri Sep 8 23:25:34 2017
@@ -0,0 +1,214 @@
+// ***************************************************************************************************************************
+// * 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.rest.annotation;
+
+import org.apache.juneau.rest.*;
+
+/**
+ * Extended annotation for {@link RestMethod#swagger() RestMethod.swagger()}.
+ */
+public @interface MethodSwagger {
+
+ /**
+ * Optional external documentation information for the exposed API.
+ *
+ * <p>
+ * Used to populate the Swagger external documentation field.
+ *
+ * <p>
+ * A simplified JSON string with the following fields:
+ * <p class='bcode'>
+ * {
+ * description: string,
+ * url: string
+ * }
+ * </p>
+ *
+ * <p>
+ * The default value pulls the description from the <code>(className.?)[javaMethodName].externalDocs</code> entry in
+ * the servlet resource bundle.
+ * (e.g. <js>"MyClass.myMethod.externalDocs = {url:'http://juneau.apache.org'}"</js> or
+ * <js>"myMethod.externalDocs = {url:'http://juneau.apache.org'}"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * swagger=<ja>@MethodSwagger</ja>(
+ * <js>"{url:'http://juneau.apache.org'}"</js>
+ * )
+ * )
+ * </p>
+ *
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field <code>/paths/{path}/{method}/externalDocs</code>.
+ */
+ String externalDocs() default "";
+
+ /**
+ * Optional tagging information for the exposed API.
+ *
+ * <p>
+ * Used to populate the Swagger tags field.
+ *
+ * <p>
+ * A comma-delimited list of tags for API documentation control.
+ * Tags can be used for logical grouping of operations by resources or any other qualifier.
+ *
+ * <p>
+ * The default value pulls the description from the <code>(className.?)[javaMethodName].tags</code> entry in the
+ * servlet resource bundle.
+ * (e.g. <js>"MyClass.myMethod.tags = foo,bar"</js> or <js>"myMethod.tags = foo,bar"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * swagger=<ja>@MethodSwagger</ja>(
+ * tags=<js>"foo,bar"</js>
+ * )
+ * )
+ * </p>
+ *
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field <code>/paths/{path}/{method}/tags</code>.
+ */
+ String tags() default "";
+
+ /**
+ * Optional deprecated flag for the exposed API.
+ *
+ * <p>
+ * Used to populate the Swagger deprecated field.
+ *
+ * <p>
+ * The default value pulls the description from the <code>(className.?)[javaMethodName].deprecated</code> entry in
+ * the servlet resource bundle.
+ * (e.g. <js>"MyClass.myMethod.deprecated = true"</js> or <js>"myMethod.deprecated = foo,bar"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * swagger=<ja>@MethodSwagger</ja>(
+ * deprecated=<jk>true</jk>
+ * )
+ * )
+ * </p>
+ *
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field <code>/paths/{path}/{method}/deprecated</code>.
+ */
+ boolean deprecated() default false;
+
+ /**
+ * Optional parameter descriptions.
+ *
+ * <p>
+ * This annotation is provided for documentation purposes and is used to populate the method <js>"parameters"</js>
+ * column on the Swagger page.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * name=<js>"POST"</js>, path=<js>"/{a}"</js>,
+ * description=<js>"This is my method."</js>,
+ * swagger=<ja>@MethodSwagger</ja>(
+ * parameters={
+ * <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"a"</js>, description=<js>"The 'a' attribute"</js>),
+ * <ja>@Parameter</ja>(in=<js>"query"</js>, name=<js>"b"</js>, description=<js>"The 'b' parameter"</js>, required=<jk>true</jk>),
+ * <ja>@Parameter</ja>(in=<js>"body"</js>, description=<js>"The HTTP content"</js>),
+ * <ja>@Parameter</ja>(in=<js>"header"</js>, name=<js>"D"</js>, description=<js>"The 'D' header"</js>),
+ * }
+ * )
+ * )
+ * </p>
+ *
+ * <p>
+ * This is functionally equivalent to specifying the following keys in the resource bundle for the class, except in
+ * this case the strings are internationalized.
+ * <p class='bcode'>
+ * <jk>MyClass.myMethod.description</jk> = <js>This is my method.</js>
+ * <jk>MyClass.myMethod.req.path.a.description</jk> = <js>The 'a' attribute</js>
+ * <jk>MyClass.myMethod.req.query.b.description</jk> = <js>The 'b' parameter</js>
+ * <jk>MyClass.myMethod.req.body.description</jk> = <js>The HTTP content</js>
+ * <jk>MyClass.myMethod.req.header.d.description</jk> = <js>The 'D' header</js>
+ * </p>
+ *
+ * <p>
+ * As a general rule, use annotations when you don't care about internationalization (i.e. you only want to support
+ * English), and use resource bundles if you need to support localization.
+ *
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of supported variables.
+ *
+ * <p>
+ * Corresponds to the swagger field <code>/paths/{path}/{method}/parameters</code>.
+ */
+ Parameter[] parameters() default {};
+
+ /**
+ * Optional output description.
+ *
+ * <p>
+ * This annotation is provided for documentation purposes and is used to populate the method <js>"responses"</js>
+ * column on the Swagger page.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * name=<js>"GET"</js>, path=<js>"/"</js>,
+ * swagger=<ja>@MethodSwagger</ja>(
+ * responses={
+ * <ja>@Response</ja>(200),
+ * <ja>@Response</ja>(
+ * value=302,
+ * description=<js>"Thing wasn't found here"</js>,
+ * headers={
+ * <ja>@Parameter</ja>(name=<js>"Location"</js>, description=<js>"The place to find the thing"</js>)
+ * }
+ * )
+ * }
+ * )
+ * )
+ * </p>
+ *
+ * <p>
+ * This is functionally equivalent to specifying the following keys in the resource bundle for the class, except in
+ * this case the strings are internationalized.
+ * <p class='bcode'>
+ * <jk>MyClass.myMethod.res.200.description</jk> = <js>OK</js>
+ * <jk>MyClass.myMethod.res.302.description</jk> = <js>Thing wasn't found here</js>
+ * <jk>MyClass.myMethod.res.302.header.Location.description</jk> = <js>The place to find the thing</js>
+ * </p>
+ *
+ * <p>
+ * As a general rule, use annotations when you don't care about internationalization (i.e. you only want to support
+ * English), and use resource bundles if you need to support localization.
+ *
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <br>See {@link RestContext#getVarResolver()} for the list of supported variables.
+ */
+ Response[] responses() default {};
+}
Propchange: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Parameter.java
==============================================================================
--- release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Parameter.java (added)
+++ release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Parameter.java Fri Sep 8 23:25:34 2017
@@ -0,0 +1,208 @@
+// ***************************************************************************************************************************
+// * 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.rest.annotation;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+/**
+ * Annotation used in conjunction with {@link MethodSwagger#parameters()} to identify content and header descriptions
+ * on specific method requests.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * name=<js>"*"</js>,
+ * swagger=@MethodSwagger(
+ * parameters={
+ * <ja>@Parameter</ja>(in=<js>"header"</js>, name=<js>"Range"</js>, description=<js>"$L{ContentRange.description}"</js>)
+ * }
+ * )
+ * )
+ * <jk>public void</jk> doAnything(RestRequest req, RestResponse res, <ja>@Method</ja> String method) {
+ * ...
+ * }
+ * </p>
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Inherited
+public @interface Parameter {
+
+ /**
+ * The location of the parameter.
+ *
+ * <p>
+ * Possible values are:
+ * <ul>
+ * <li><js>"query"</js>
+ * <li><js>"header"</js>
+ * <li><js>"path"</js>
+ * <li><js>"formData"</js>
+ * <li><js>"body"</js>
+ * </ul>
+ */
+ String in() default "";
+
+ /**
+ * The name of the parameter (e.g. <js>"Content-Range"</js>).
+ *
+ * <p>
+ * Parameter names are case sensitive.
+ * If <code>in</code> is <js>"path"</js>, the name field MUST correspond to the associated path segment from the
+ * <code>path</code> field in the <a class="doclink"
+ * href="http://swagger.io/specification/#pathsObject">Paths Object</a>.
+ * See <a class="doclink" href="http://swagger.io/specification/#pathTemplating">Path Templating</a> for further
+ * information.
+ * For all other cases, the name corresponds to the parameter name used based on the <code>in</code> property.
+ */
+ String name() default "";
+
+ /**
+ * Parameter description (e.g. <js>"Indicates the range returned when Range header is present in the request"</js>).
+ *
+ * <p>
+ * A brief description of the parameter.
+ * This could contain examples of use.
+ * <a class="doclink" href="https://help.github.com/articles/github-flavored-markdown">GFM syntax</a> can be used
+ * for rich text representation.
+ *
+ * <p>
+ * The default value pulls the description from the <code>description</code> entry in the servlet resource bundle.
+ * (e.g. <js>"myMethod.res.[code].[category].[name] = foo"</js> or
+ * <js>"MyServlet.myMethod.res.[code].[category].[name] = foo"</js>).
+ */
+ String description() default "";
+
+ /**
+ * Determines whether this parameter is mandatory.
+ *
+ * <p>
+ * If the parameter is <code>in</code> <js>"path"</js>, this property is required and its value MUST be <jk>true</jk>.
+ * Otherwise, the property MAY be included and its default value is <jk>false</jk>.
+ */
+ boolean required() default false;
+
+ /**
+ * The schema defining the type used for the body parameter.
+ *
+ * <p>
+ * Only applicable for <code>in</code> of type <js>"body"</js>.
+ *
+ * <p>
+ * The schema is a JSON object specified <a class="doclink" href="http://swagger.io/specification/#schemaObject">here</a>.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * parameters={
+ * <ja>@Parameter</ja>(
+ * in=<js>"header"</js>,
+ * name=<js>"Foo"</js>,
+ * schema=<js>"{format:'string',title:'Foo header',description:'Header that contains the Foo value.'}"</js>)
+ * }
+ * )
+ * <jk>public void</jk> doAnything() {
+ * </p>
+ */
+ String schema() default "";
+
+ /**
+ * The type of the parameter.
+ *
+ * <p>
+ * The value MUST be one of <js>"string"</js>, <js>"number"</js>, <js>"integer"</js>, <js>"boolean"</js>,
+ * <js>"array"</js> or <js>"file"</js>.
+ * If type is <js>"file"</js>, the consumes MUST be either <js>"multipart/form-data"</js>,
+ * <js>"application/x-www-form-urlencoded"</js> or both and the parameter MUST be in <js>"formData"</js>.
+ */
+ String type() default "string";
+
+ /**
+ * The extending format for the previously mentioned <code>type</code>.
+ *
+ * <p>
+ * See <a class="doclink" href="http://swagger.io/specification/#dataTypeFormat">Data Type Formats</a> for further
+ * details.
+ */
+ String format() default "";
+
+ /**
+ * Sets the ability to pass empty-valued parameters.
+ *
+ * <p>
+ * This is valid only for either <code>query</code> or <code>formData</code> parameters and allows you to send a
+ * parameter with a name only or an empty value.
+ * Default value is <jk>false</jk>.
+ */
+ boolean allowEmptyValue() default false;
+
+ /**
+ * Required if <code>type</code> is <js>"array"</js>.
+ *
+ * <p>
+ * Describes the type of items in the array.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * parameters={
+ * <ja>@Parameter</ja>(
+ * in=<js>"header"</js>,
+ * name=<js>"Foo"</js>,
+ * type=<js>"array"</js>,
+ * items=<js>"{type:'string',collectionFormat:'csv'}"</js>)
+ * }
+ * )
+ * <jk>public void</jk> doAnything() {
+ * </p>
+ *
+ * <p>
+ * See <a class="doclink" href="http://swagger.io/specification/#itemsObject">Items Object</a> for further details.
+ */
+ String items() default "";
+
+ /**
+ * Determines the format of the array if type array is used.
+ *
+ * <p>
+ * Possible values are:
+ * <ul>
+ * <li><js>"csv"</js> - comma separated values <js>"foo,bar"</js>.
+ * <li><js>"ssv"</js> - space separated values <js>"foo bar"</js>.
+ * <li><js>"tsv"</js> - tab separated values <js>"foo\tbar"</js>.
+ * <li><js>"pipes"</js> - pipe separated values <js>"foo|bar"</js>.
+ * <li><js>"multi"</js> - corresponds to multiple parameter instances instead of multiple values for a single
+ * instance <js>"foo=bar&foo=baz"</js>.
+ * This is valid only for parameters <code>in</code> <js>"query"</js> or <js>"formData"</js>.
+ * </ul>
+ * Default value is <js>"csv"</js>.
+ */
+ String collectionFormat() default "";
+
+ /**
+ * Declares the value of the parameter that the server will use if none is provided.
+ *
+ * <p>
+ * For example a "count" to control the number of results per page might default to 100 if not supplied by the
+ * client in the request.
+ * (Note: "default" has no meaning for required parameters.)
+ * See <a class="doclink" href="http://json-schema.org/latest/json-schema-validation.html#anchor101">
+ * http://json-schema.org/latest/json-schema-validation.html#anchor101</a>.
+ * Unlike JSON Schema this value MUST conform to the defined <code>type</code> for this parameter.
+ */
+ String _default() default "";
+}
Propchange: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Parameter.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Path.java
==============================================================================
--- release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Path.java (added)
+++ release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Path.java Fri Sep 8 23:25:34 2017
@@ -0,0 +1,90 @@
+// ***************************************************************************************************************************
+// * 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.rest.annotation;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+/**
+ * Annotation that can be applied to a parameter of a {@link RestMethod} annotated method to identify it as a variable
+ * in a URL path pattern converted to a POJO.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>)
+ * <jk>public void</jk> doGet(RestRequest req, RestResponse res,
+ * <ja>@Path</ja> String foo, <ja>@Path</ja> <jk>int</jk> bar, <ja>@Path</ja> UUID baz) {
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * The <ja>@Path</ja> annotation is optional if the parameters are specified immediately following the
+ * <code>RestRequest</code> and <code>RestResponse</code> parameters, and are specified in the same order as the
+ * variables in the URL path pattern.
+ * The following example is equivalent to the previous example.
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>)
+ * <jk>public void</jk> doGet(RestRequest req, RestResponse res,
+ * String foo, <jk>int</jk> bar, UUID baz) {
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * If the order of parameters is not the default order shown above, the attribute names must be specified (since
+ * parameter names are lost during compilation).
+ * The following example is equivalent to the previous example, except the parameter order has been switched, requiring
+ * the use of the <ja>@Path</ja> annotations.
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>)
+ * <jk>public void</jk> doGet(RestRequest req, RestResponse res,
+ * <ja>@Path</ja>(<js>"baz"</js>) UUID baz, <ja>@Path</ja>(<js>"foo"</js>) String foo, <ja>@Path</ja>(<js>"bar"</js>) <jk>int</jk> bar) {
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * You can also use <code>{#}</code> notation to specify path parameters without specifying names.
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/myurl/{0}/{1}/{2}/*"</js>)
+ * <jk>public void</jk> doGet(RestRequest req, RestResponse res,
+ * <ja>@Path</ja> String foo, <ja>@Path</ja> <jk>int</jk> bar, <ja>@Path</ja> UUID baz) {
+ * ...
+ * }
+ * </p>
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Inherited
+public @interface Path {
+
+ /**
+ * URL path variable name.
+ *
+ * <p>
+ * Optional if the attributes are specified in the same order as in the URL path pattern.
+ */
+ String name() default "";
+
+ /**
+ * A synonym for {@link #name()}.
+ *
+ * <p>
+ * Allows you to use shortened notation if you're only specifying the name.
+ */
+ String value() default "";
+}
Propchange: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Path.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/PathRemainder.java
==============================================================================
--- release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/PathRemainder.java (added)
+++ release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/PathRemainder.java Fri Sep 8 23:25:34 2017
@@ -0,0 +1,46 @@
+// ***************************************************************************************************************************
+// * 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.rest.annotation;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+/**
+ * Annotation that can be applied to a parameter of a {@link RestMethod} annotated method to identify it as the URL
+ * parameter remainder after a path pattern match.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/foo/*"</js>)
+ * <jk>public void</jk> doGet(RestRequest req, RestResponse res, <ja>@PathRemainder</ja> String remainder) {
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * This is functionally equivalent to the following code...
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/foo/*"</js>)
+ * <jk>public void</jk> doGet(RestRequest req, RestResponse res) {
+ * String remainder = req.getPathRemainder();
+ * ...
+ * }
+ * </p>
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Inherited
+public @interface PathRemainder {}
Propchange: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/PathRemainder.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Properties.java
==============================================================================
--- release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Properties.java (added)
+++ release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Properties.java Fri Sep 8 23:25:34 2017
@@ -0,0 +1,67 @@
+// ***************************************************************************************************************************
+// * 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.rest.annotation;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+import org.apache.juneau.*;
+
+/**
+ * Annotation that can be applied to a parameter of a {@link RestMethod} annotated method to identify the
+ * request-duration properties object for the current request.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>)
+ * <jk>public Person</jk> doGetPerson(<ja>@Properties</ja> ObjectMap properties) {
+ * properties.put(<jsf>HTMLDOC_title</jsf>, <js>"This is a person"</js>);
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * This is functionally equivalent to the following code...
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>)
+ * <jk>public Person</jk> doGetPerson(RestResponse res) {
+ * ObjectMap properties = res.getProperties();
+ * properties.put(<jsf>HTMLDOC_title</jsf>, <js>"This is a person"</js>);
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * ...or this...
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>)
+ * <jk>public Person</jk> doGetPerson(RestResponse res) {
+ * res.setProperty(<jsf>HTMLDOC_title</jsf>, <js>"This is a person"</js>);
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * The parameter type can be one of the following:
+ * <ul>
+ * <li>{@link ObjectMap}
+ * <li><code>Map<String,Object></code>
+ * </ul>
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Inherited
+public @interface Properties {}
Propchange: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Properties.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Property.java
==============================================================================
--- release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Property.java (added)
+++ release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Property.java Fri Sep 8 23:25:34 2017
@@ -0,0 +1,62 @@
+// ***************************************************************************************************************************
+// * 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.rest.annotation;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+import org.apache.juneau.*;
+import org.apache.juneau.json.*;
+import org.apache.juneau.parser.*;
+import org.apache.juneau.serializer.*;
+import org.apache.juneau.xml.*;
+
+/**
+ * Property name/value pair used in the {@link RestResource#properties()} annotation.
+ *
+ * <p>
+ * Any of the following property names can be specified:
+ * <ul>
+ * <li>{@link BeanContext}
+ * <li>{@link SerializerContext}
+ * <li>{@link ParserContext}
+ * <li>{@link JsonSerializerContext}
+ * <li>{@link XmlSerializerContext}
+ * <li>{@link XmlParserContext}
+ * </ul>
+ *
+ * <p>
+ * Property values types that are not <code>Strings</code> will automatically be converted to the correct type
+ * (e.g. <code>Boolean</code>, etc...).
+ *
+ * <p>
+ * See {@link RestResource#properties} for more information.
+ */
+@Documented
+@Target(ANNOTATION_TYPE)
+@Retention(RUNTIME)
+@Inherited
+public @interface Property {
+
+ /**
+ * Property name.
+ */
+ String name();
+
+ /**
+ * Property value.
+ */
+ String value();
+}
Propchange: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Property.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Query.java
==============================================================================
--- release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Query.java (added)
+++ release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Query.java Fri Sep 8 23:25:34 2017
@@ -0,0 +1,114 @@
+// ***************************************************************************************************************************
+// * 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.rest.annotation;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+import org.apache.juneau.rest.*;
+
+/**
+ * Identical to {@link FormData @FormData}, but only retrieves the parameter from the URL string, not URL-encoded form
+ * posts.
+ *
+ * <p>
+ * Unlike {@link FormData @FormData}, using this annotation does not result in the servlet reading the contents of
+ * URL-encoded form posts.
+ * Therefore, this annotation can be used in conjunction with the {@link Body @Body} annotation or
+ * {@link RestRequest#getBody()} method for <code>application/x-www-form-urlencoded POST</code> calls.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>)
+ * <jk>public void</jk> doGet(RestRequest req, RestResponse res,
+ * <ja>@Query</ja>(<js>"p1"</js>) <jk>int</jk> p1, <ja>@Query</ja>(<js>"p2"</js>) String p2, <ja>@Query</ja>(<js>"p3"</js>) UUID p3) {
+ * ...
+ * }
+ * </p>
+ *
+ * <p>
+ * This is functionally equivalent to the following code...
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>)
+ * <jk>public void</jk> doGet(RestRequest req, RestResponse res) {
+ * <jk>int</jk> p1 = req.getQueryParameter(<jk>int</jk>.<jk>class</jk>, <js>"p1"</js>, 0);
+ * String p2 = req.getQueryParameter(String.<jk>class</jk>, <js>"p2"</js>);
+ * UUID p3 = req.getQueryParameter(UUID.<jk>class</jk>, <js>"p3"</js>);
+ * ...
+ * }
+ * </p>
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Inherited
+public @interface Query {
+
+ /**
+ * URL query parameter name.
+ */
+ String name() default "";
+
+ /**
+ * A synonym for {@link #name()}.
+ *
+ * <p>
+ * Allows you to use shortened notation if you're only specifying the name.
+ */
+ String value() default "";
+
+ /**
+ * Specify <jk>true</jk> if using multi-part parameters to represent collections and arrays.
+ *
+ * <p>
+ * Normally, we expect single parameters to be specified in UON notation for representing collections of values
+ * (e.g. <js>"&key=(1,2,3)"</js>.
+ * This annotation allows the use of multi-part parameters to represent collections
+ * (e.g. <js>"&key=1&key=2&key=3"</js>.
+ *
+ * <p>
+ * This setting should only be applied to Java parameters of type array or Collection.
+ */
+ boolean multipart() default false;
+
+ /**
+ * The expected format of the request parameter.
+ *
+ * <p>
+ * Possible values:
+ * <ul class='spaced-list'>
+ * <li>
+ * <js>"UON"</js> - URL-Encoded Object Notation.
+ * <br>This notation allows for request parameters to contain arbitrarily complex POJOs.
+ * <li>
+ * <js>"PLAIN"</js> - Plain text.
+ * <br>This treats request parameters as plain text.
+ * <br>Only POJOs directly convertible from <l>Strings</l> can be represented in parameters when using this mode.
+ * <li>
+ * <js>"INHERIT"</js> (default) - Inherit from the {@link RestContext#REST_paramFormat} property on the
+ * servlet method or class.
+ * </ul>
+ *
+ * <p>
+ * Note that the parameter value <js>"(foo)"</js> is interpreted as <js>"(foo)"</js> when using plain mode, but
+ * <js>"foo"</js> when using UON mode.
+ */
+ String format() default "INHERIT";
+
+ /**
+ * The default value for this query parameter if it's not present in the request.
+ */
+ String def() default "";
+}
Propchange: release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Query.java
------------------------------------------------------------------------------
svn:mime-type = text/plain