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/06/28 23:37:19 UTC
[02/11] incubator-juneau git commit: Clean up javadocs
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestLogger.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestLogger.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestLogger.java
index bc577e8..c307e11 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestLogger.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestLogger.java
@@ -26,9 +26,11 @@ import org.apache.juneau.rest.annotation.*;
/**
* Logging utility class.
+ *
* <p>
* Subclasses can override these methods to tailor logging of HTTP requests.
* Subclasses MUST implement a no-arg public constructor.
+ *
* <p>
* RestLoggers are associated with servlets/resources in one of the following ways:
* <ul>
@@ -40,6 +42,7 @@ public abstract class RestLogger {
/**
* Returns the Java logger used for logging.
+ *
* <p>
* Subclasses can provide their own logger.
* The default implementation returns the logger created using <code>Logger.getLogger(getClass())</code>.
@@ -50,6 +53,7 @@ public abstract class RestLogger {
/**
* Log a message to the logger.
+ *
* <p>
* Subclasses can override this method if they wish to log messages using a library other than Java Logging
* (e.g. Apache Commons Logging).
@@ -63,6 +67,7 @@ public abstract class RestLogger {
/**
* Log a message.
+ *
* <p>
* Equivalent to calling <code>log(level, <jk>null</jk>, msg, args);</code>
*
@@ -75,8 +80,8 @@ public abstract class RestLogger {
}
/**
- * Same as {@link #log(Level, String, Object...)} excepts runs the arguments through
- * {@link JsonSerializer#DEFAULT_LAX_READABLE}.
+ * Same as {@link #log(Level, String, Object...)} excepts runs the arguments through {@link JsonSerializer#DEFAULT_LAX_READABLE}.
+ *
* <p>
* Serialization of arguments do not occur if message is not logged, so it's safe to use this method from within
* debug log statements.
@@ -98,13 +103,15 @@ public abstract class RestLogger {
/**
* Callback method for logging errors during HTTP requests.
+ *
* <p>
* Typically, subclasses will override this method and log errors themselves.
+ *
* <p>
* The default implementation simply logs errors to the <code>RestServlet</code> logger.
+ *
* <p>
* Here's a typical implementation showing how stack trace hashing can be used to reduce log file sizes...
- * </p>
* <p class='bcode'>
* <jk>protected void</jk> onError(HttpServletRequest req, HttpServletResponse res, RestException e, <jk>boolean</jk> noTrace) {
* String qs = req.getQueryString();
@@ -148,8 +155,10 @@ public abstract class RestLogger {
/**
* Returns <jk>true</jk> if the specified exception should be logged.
+ *
* <p>
* Subclasses can override this method to provide their own logic for determining when exceptions are logged.
+ *
* <p>
* The default implementation will return <jk>false</jk> if <js>"noTrace=true"</js> is passed in the query string
* or <code>No-Trace: true</code> is specified in the header.
@@ -167,12 +176,13 @@ public abstract class RestLogger {
/**
* Returns <jk>true</jk> if a stack trace should be logged for this exception.
+ *
* <p>
* Subclasses can override this method to provide their own logic for determining when stack traces are logged.
+ *
* <p>
* The default implementation will only log a stack trace if {@link RestException#getOccurrence()} returns
* <code>1</code> and the exception is not one of the following:
- * </p>
* <ul>
* <li>{@link HttpServletResponse#SC_UNAUTHORIZED}
* <li>{@link HttpServletResponse#SC_FORBIDDEN}
@@ -206,6 +216,7 @@ public abstract class RestLogger {
/**
* NO-OP logger.
+ *
* <p>
* Disables all logging.
*
@@ -224,6 +235,7 @@ public abstract class RestLogger {
/**
* Default logger.
+ *
* <p>
* Logs all messages to the logger returned by <code>Logger.<jsm>getLogger</jsm>(getClass().getName())</code>
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestMatcher.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestMatcher.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestMatcher.java
index 612d9d1..4967193 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestMatcher.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestMatcher.java
@@ -16,14 +16,17 @@ import org.apache.juneau.rest.annotation.*;
/**
* Class used for defining method-level matchers using the {@link RestMethod#matchers()} annotation.
+ *
* <p>
* Matchers are used to allow multiple Java methods to handle requests assigned to the same URL path pattern, but
* differing based on some request attribute, such as a specific header value.
* For example, matchers can be used to provide two different methods for handling requests from two different client
* versions.
+ *
* <p>
* Java methods with matchers associated with them are always attempted before Java methods without matchers.
* This allows a 'default' method to be defined to handle requests where no matchers match.
+ *
* <p>
* When multiple matchers are specified on a method, only one matcher is required to match.
* This is opposite from the {@link RestMethod#guards()} annotation, where all guards are required to match in order to
@@ -64,6 +67,7 @@ public abstract class RestMatcher {
/**
* Returns <jk>true</jk> if this matcher is required to match in order for the method to be invoked.
+ *
* <p>
* If <jk>false</jk>, then only one of the matchers must match.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestMatcherReflecting.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestMatcherReflecting.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestMatcherReflecting.java
index 5678d1d..9469226 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestMatcherReflecting.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestMatcherReflecting.java
@@ -16,6 +16,7 @@ import java.lang.reflect.*;
/**
* Subclass of {@link RestMatcher} that gives access to the servlet/resource and Java method it's applied to.
+ *
* <p>
* Essentially the same as {@link RestMatcher} except has a constructor where the Java method is passed in so that you
* can access annotations defined on it to tailor the behavior of the matcher.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestParam.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestParam.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestParam.java
index 840f9f7..1002013 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestParam.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestParam.java
@@ -18,8 +18,10 @@ import org.apache.juneau.rest.annotation.*;
/**
* REST java method parameter resolver.
+ *
* <p>
* Used to resolve instances of classes being passed to Java REST methods.
+ *
* <p>
* This class is associated with REST classes via the {@link RestResource#paramResolvers()} annotation and
* {@link RestConfig#addParamResolvers(Class...)} method.
@@ -34,8 +36,9 @@ public abstract class RestParam {
* Constructor.
*
* @param paramType The Swagger parameter type.
- * @param name The parameter name.
- * Can be <jk>null</jk> if parameter doesn't have a name (e.g. the request body).
+ * @param name
+ * The parameter name.
+ * Can be <jk>null</jk> if parameter doesn't have a name (e.g. the request body).
* @param type The object type to convert the parameter to.
*/
protected RestParam(RestParamType paramType, String name, Type type) {
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestRequest.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestRequest.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestRequest.java
index 9a2f9d2..161c578 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestRequest.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestRequest.java
@@ -42,8 +42,10 @@ import org.apache.juneau.utils.*;
/**
* Represents an HTTP request for a REST resource.
+ *
* <p>
* Equivalent to {@link HttpServletRequest} except with some additional convenience methods.
+ *
* <p>
* For reference, given the URL <js>"http://localhost:9080/contextRoot/servletPath/foo?bar=baz#qux"</js>, the
* following methods return the following values....
@@ -57,6 +59,7 @@ import org.apache.juneau.utils.*;
* <tr><td>{@code getRequestURL()}</td><td>{@code http://localhost:9080/contextRoot/servletPath/foo}</td></tr>
* <tr><td>{@code getServletPath()}</td><td>{@code /servletPath}</td></tr>
* </table>
+ *
* <p>
* Refer to <a class="doclink" href="package-summary.html#TOC">REST Servlet API</a> for information about using this
* class.
@@ -241,6 +244,7 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Retrieve the properties active for this request.
+ *
* <p>
* These properties can be modified by the request.
*
@@ -362,9 +366,11 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Equivalent to {@link #getParameterMap()}, but only looks for query parameters in the URL, not form posts.
+ *
* <p>
* This method can be used to retrieve query parameters without triggering the underlying servlet API to load and
* parse the request body.
+ *
* <p>
* This object is modifiable.
*
@@ -455,9 +461,11 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the HTTP body content as a {@link Reader}.
+ *
* <p>
* If {@code allowHeaderParams} init parameter is true, then first looks for {@code &body=xxx} in the URL query
* string.
+ *
* <p>
* Automatically handles GZipped input streams.
*/
@@ -468,6 +476,7 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the HTTP body content as an {@link InputStream}.
+ *
* <p>
* Automatically handles GZipped input streams.
*
@@ -490,6 +499,7 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the URI context of the request.
+ *
* <p>
* The URI context contains all the information about the URI of the request, such as the servlet URI, context
* path, etc...
@@ -536,6 +546,7 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the localized servlet title.
+ *
* <p>
* Equivalent to calling {@link RestInfoProvider#getTitle(RestRequest)} with this object.
*
@@ -547,6 +558,7 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the localized servlet description.
+ *
* <p>
* Equivalent to calling {@link RestInfoProvider#getDescription(RestRequest)} with this object.
*
@@ -558,6 +570,7 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the localized method summary.
+ *
* <p>
* Equivalent to calling {@link RestInfoProvider#getMethodSummary(String, RestRequest)} with this object.
*
@@ -569,6 +582,7 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the localized method description.
+ *
* <p>
* Equivalent to calling {@link RestInfoProvider#getMethodDescription(String, RestRequest)} with this object.
*
@@ -603,6 +617,7 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the method of this request.
+ *
* <p>
* If <code>allowHeaderParams</code> init parameter is <jk>true</jk>, then first looks for
* <code>&method=xxx</code> in the URL query string.
@@ -614,6 +629,7 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the HTTP 1.1 method name of the request as an enum.
+ *
* <p>
* Note that non-RFC2616 method names resolve as {@link HttpMethod#OTHER}.
*
@@ -634,9 +650,11 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns <jk>true</jk> if <code>&plainText=true</code> was specified as a URL parameter.
+ *
* <p>
* This indicates that the <code>Content-Type</code> of the output should always be set to <js>"text/plain"</js>
* to make it easy to render in a browser.
+ *
* <p>
* This feature is useful for debugging.
*
@@ -668,6 +686,7 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the servlet handling the request.
+ *
* <p>
* Can be used to access servlet-init parameters or annotations during requests, such as in calls to
* {@link RestGuard#guard(RestRequest, RestResponse)}..
@@ -680,6 +699,7 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the java method handling the request.
+ *
* <p>
* Can be used to access the method name or method annotations during requests, such as in calls to
* {@link RestGuard#guard(RestRequest, RestResponse)}.
@@ -732,8 +752,9 @@ public final class RestRequest extends HttpServletRequestWrapper {
* classpath.
*
* @param name The name of the resource (i.e. the value normally passed to {@link Class#getResourceAsStream(String)}.
- * @param resolveVars If <jk>true</jk>, any {@link org.apache.juneau.rest.annotation.Parameter} variables will be
- * resolved by the variable resolver returned by {@link #getVarResolverSession()}.
+ * @param resolveVars
+ * If <jk>true</jk>, any {@link org.apache.juneau.rest.annotation.Parameter} variables will be
+ * resolved by the variable resolver returned by {@link #getVarResolverSession()}.
* @param mediaType The value to set as the <js>"Content-Type"</js> header for this object.
* @return A new reader resource, or <jk>null</jk> if resource could not be found.
* @throws IOException
@@ -753,8 +774,9 @@ public final class RestRequest extends HttpServletRequestWrapper {
* constructed using {@link RestConfig#addMimeTypes(String...)} to determine the media type.
*
* @param name The name of the resource (i.e. the value normally passed to {@link Class#getResourceAsStream(String)}.
- * @param resolveVars If <jk>true</jk>, any {@link org.apache.juneau.rest.annotation.Parameter} variables will be
- * resolved by the variable resolver returned by {@link #getVarResolverSession()}.
+ * @param resolveVars
+ * If <jk>true</jk>, any {@link org.apache.juneau.rest.annotation.Parameter} variables will be
+ * resolved by the variable resolver returned by {@link #getVarResolverSession()}.
* @return A new reader resource, or <jk>null</jk> if resource could not be found.
* @throws IOException
*/
@@ -776,8 +798,9 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the config file associated with the servlet.
*
- * @return The config file associated with the servlet, or <jk>null</jk> if servlet does not have a config file
- * associated with it.
+ * @return
+ * The config file associated with the servlet, or <jk>null</jk> if servlet does not have a config file
+ * associated with it.
*/
public ConfigFile getConfigFile() {
if (cf == null)
@@ -788,8 +811,9 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the localized swagger associated with the servlet.
*
- * @return The swagger associated with the servlet.
- * Never <jk>null</jk>.
+ * @return
+ * The swagger associated with the servlet.
+ * Never <jk>null</jk>.
*/
public Swagger getSwagger() {
if (swagger == null)
@@ -800,8 +824,9 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the widgets used for resolving <js>"$W{...}"</js> string variables.
*
- * @return The widgets used for resolving <js>"$W{...}"</js> string variables.
- * Never <jk>null</jk>.
+ * @return
+ * The widgets used for resolving <js>"$W{...}"</js> string variables.
+ * Never <jk>null</jk>.
*/
public Map<String,Widget> getWidgets() {
return widgets;
@@ -809,9 +834,11 @@ public final class RestRequest extends HttpServletRequestWrapper {
/**
* Returns the localized Swagger from the file system.
+ *
* <p>
* Looks for a file called <js>"{ServletClass}_{locale}.json"</js> in the same package as this servlet and returns
* it as a parsed {@link Swagger} object.
+ *
* <p>
* Returned objects are cached for later quick-lookup.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestResourceResolver.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestResourceResolver.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestResourceResolver.java
index ddbdf18..308eba0 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestResourceResolver.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestResourceResolver.java
@@ -20,8 +20,10 @@ import org.apache.juneau.rest.annotation.*;
/**
* Class used to resolve {@link Class} objects to instances.
+ *
* <p>
* Used to convert classes defined via {@link RestResource#children() @RestResource.children()} into child instances.
+ *
* <p>
* Subclasses can be created to provide customized resource resolution.
* These can be associated with REST resources in one of the following ways:
@@ -30,15 +32,19 @@ import org.apache.juneau.rest.annotation.*;
* <li>{@link RestConfig#setResourceResolver(Class)}/{@link RestConfig#setResourceResolver(RestResourceResolver)}
* methods.
* </ul>
+ *
* <p>
* The default implementation simply instantiates the class using one of the following constructors:
* <ul>
* <li><code><jk>public</jk> T(RestConfig)</code>
* <li><code><jk>public</jk> T()</code>
* </ul>
+ *
+ * <p>
* The former constructor can be used to get access to the {@link RestConfig} object to get access to the
* config file and initialization information or make programmatic modifications to the resource before
* full initialization.
+ *
* <p>
* Non-<code>RestServlet</code> classes can also add the following two methods to get access to the
* {@link RestConfig} and {@link RestContext} objects:
@@ -56,8 +62,10 @@ public class RestResourceResolver {
/**
* Resolves the specified class to a resource object.
+ *
* <p>
* Subclasses can override this method to provide their own custom resolution.
+ *
* <p>
* The default implementation simply creates a new class instance using {@link Class#newInstance()}.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestResponse.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestResponse.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestResponse.java
index e0d2f69..1d85c9e 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestResponse.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestResponse.java
@@ -34,9 +34,11 @@ import org.apache.juneau.xml.*;
/**
* Represents an HTTP response for a REST resource.
+ *
* <p>
* Essentially an extended {@link HttpServletResponse} with some special convenience methods that allow you to easily
* output POJOs as responses.
+ *
* <p>
* Since this class extends {@link HttpServletResponse}, developers are free to use these convenience methods, or
* revert to using lower level methods like any other servlet response.
@@ -49,6 +51,7 @@ import org.apache.juneau.xml.*;
* .setOutput(<js>"Simple string response"</js>);
* }
* </p>
+ *
* <p>
* Refer to <a class="doclink" href="package-summary.html#TOC">REST Servlet API</a> for information about using this
* class.
@@ -151,8 +154,10 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* Sets the HTTP output on the response.
+ *
* <p>
* Calling this method is functionally equivalent to returning the object in the REST Java method.
+ *
* <p>
* Can be of any of the following types:
* <ul>
@@ -161,6 +166,7 @@ public final class RestResponse extends HttpServletResponseWrapper {
* <li> Any serializable type defined in <a class="doclink"
* href="../../../../overview-summary.html#Core.PojoCategories">POJO Categories</a>
* </ul>
+ *
* <p>
* If it's an {@link InputStream} or {@link Reader}, you must also specify the <code>Content-Type</code> using the
* {@link #setContentType(String)} method.
@@ -176,6 +182,7 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* Add a serializer property to send to the serializers to override a default value.
+ *
* <p>
* Can be any value specified in the following classes:
* <ul>
@@ -329,6 +336,8 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* Returns the writer to the response body.
+ *
+ * <p>
* This methods bypasses any specified encoders and returns a regular unbuffered writer.
* Use the {@link #getNegotiatedWriter()} method if you want to use the matched encoder (if any).
*/
@@ -339,6 +348,8 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* Convenience method meant to be used when rendering directly to a browser with no buffering.
+ *
+ * <p>
* Sets the header <js>"x-content-type-options=nosniff"</js> so that output is rendered immediately on IE and Chrome
* without any buffering for content-type sniffing.
*
@@ -394,6 +405,7 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* Redirects to the specified URI.
+ *
* <p>
* Relative URIs are always interpreted as relative to the context root.
* This is similar to how WAS handles redirect requests, and is different from how Tomcat handles redirect requests.
@@ -427,11 +439,14 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* Sets the HTML page title.
+ *
* <p>
* The format of this value is plain text.
+ *
* <p>
* It gets wrapped in a <code><xt><h3> <xa>class</xa>=<xs>'title'</xs>></xt></code> element and then added
* to the <code><xt><header></code> section on the page.
+ *
* <p>
* If not specified, the page title is pulled from one of the following locations:
* <ol>
@@ -441,11 +456,13 @@ public final class RestResponse extends HttpServletResponseWrapper {
* <li><code>{servletClass}.title</code> resource bundle value.
* <li><code>info/title</code> entry in swagger file.
* </ol>
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
- * <p>
+ *
* <ul class='doctree'>
* <li class='info'>
* In most cases, you'll simply want to use the <code>@RestResource(title)</code> annotation to specify the
@@ -453,10 +470,12 @@ public final class RestResponse extends HttpServletResponseWrapper {
* However, this annotation is provided in cases where you want the page title to be different that the one
* shown in the swagger document.
* </ul>
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#title() @HtmlDoc.title()} annotation.
*
- * @param value The HTML page title.
+ * @param value
+ * The HTML page title.
* Object will be converted to a string using {@link Object#toString()}.
* <p>
* <ul class='doctree'>
@@ -472,11 +491,14 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* Sets the HTML page description.
+ *
* <p>
* The format of this value is plain text.
+ *
* <p>
* It gets wrapped in a <code><xt><h5> <xa>class</xa>=<xs>'description'</xs>></xt></code> element and then
* added to the <code><xt><header></code> section on the page.
+ *
* <p>
* If not specified, the page title is pulled from one of the following locations:
* <ol>
@@ -488,11 +510,13 @@ public final class RestResponse extends HttpServletResponseWrapper {
* <li><code>{servletClass}.description</code> resource bundle value.
* <li><code>info/description</code> entry in swagger file.
* </ol>
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
- * <p>
+ *
* <ul class='doctree'>
* <li class='info'>
* In most cases, you'll simply want to use the <code>@RestResource(description)</code> or
@@ -500,10 +524,12 @@ public final class RestResponse extends HttpServletResponseWrapper {
* However, this annotation is provided in cases where you want the text to be different that the values shown
* in the swagger document.
* </ul>
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#description() @HtmlDoc.description()} annotation.
*
- * @param value The HTML page description.
+ * @param value
+ * The HTML page description.
* Object will be converted to a string using {@link Object#toString()}.
* <p>
* <ul class='doctree'>
@@ -519,19 +545,25 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* Sets the HTML page branding in the header section of the page generated by the default HTML doc template.
+ *
* <p>
* The format of this value is HTML.
+ *
* <p>
* This is arbitrary HTML that can be added to the header section to provide basic custom branding on the page.
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#branding() @HtmlDoc.branding()} annotation.
*
- * @param value The HTML page branding.
- * Object will be converted to a string using {@link Object#toString()}.
+ * @param value
+ * The HTML page branding.
+ * Object will be converted to a string using {@link Object#toString()}.
* @return This object (for method chaining).
*/
public RestResponse setHtmlBranding(Object value) {
@@ -540,29 +572,36 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* 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.
+ *
* <p>
* When a value is specified, the {@link #setHtmlTitle(Object)} and {@link #setHtmlDescription(Object)} values will
* be ignored.
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no header.
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#header() @HtmlDoc.header()} annotation.
*
- * @param value The HTML header section contents.
- * Object will be converted to a string using {@link Object#toString()}.
- * <p>
- * <ul class='doctree'>
- * <li class='info'>
- * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
- * waste string concatenation cycles on non-HTML views.
- * </ul>
+ * @param value
+ * The HTML header section contents.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
* @return This object (for method chaining).
*/
public RestResponse setHtmlHeader(Object value) {
@@ -571,28 +610,35 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* Sets the links in the HTML nav section.
+ *
* <p>
* The format of this value is a lax-JSON map of key/value pairs where the keys are the link text and the values are
* relative (to the servlet) or absolute URLs.
+ *
* <p>
* The page links are positioned immediately under the title and text.
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
+ *
* <p>
* This field can also use URIs of any support type in {@link UriResolver}.
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#links() @HtmlDoc.links()} annotation.
*
- * @param value The HTML nav section links links.
- * Object will be converted to a string using {@link Object#toString()}.
- * <p>
- * <ul class='doctree'>
- * <li class='info'>
- * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
- * waste string concatenation cycles on non-HTML views.
- * </ul>
+ * @param value
+ * The HTML nav section links links.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
* @return This object (for method chaining).
*/
public RestResponse setHtmlLinks(Object value) {
@@ -602,29 +648,37 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* 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.
+ *
* <p>
* When a value is specified, the {@link #setHtmlLinks(Object)} value will be ignored.
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#nav() @HtmlDoc.nav()} annotation.
*
- * @param value The HTML nav section contents.
- * Object will be converted to a string using {@link Object#toString()}.
- * <p>
- * <ul class='doctree'>
- * <li class='info'>
- * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
- * waste string concatenation cycles on non-HTML views.
- * </ul>
+ * @param value
+ * The HTML nav section contents.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
* @return This object (for method chaining).
*/
public RestResponse setHtmlNav(Object value) {
@@ -634,25 +688,31 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* 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.
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#aside() @HtmlDoc.aside()} annotation.
*
- * @param value The HTML aside section contents.
- * Object will be converted to a string using {@link Object#toString()}.
- * <p>
- * <ul class='doctree'>
- * <li class='info'>
- * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to waste
- * string concatenation cycles on non-HTML views.
- * </ul>
+ * @param value
+ * The HTML aside section contents.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to waste
+ * string concatenation cycles on non-HTML views.
+ * </ul>
* @return This object (for method chaining).
*/
public RestResponse setHtmlAside(Object value) {
@@ -662,25 +722,31 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* 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.
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#footer() @HtmlDoc.footer()} annotation.
*
- * @param value The HTML footer section contents.
- * Object will be converted to a string using {@link Object#toString()}.
- * <p>
- * <ul class='doctree'>
- * <li class='info'>
- * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
- * waste string concatenation cycles on non-HTML views.
- * </ul>
+ * @param value
+ * The HTML footer section contents.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
* @return This object (for method chaining).
*/
public RestResponse setHtmlFooter(Object value) {
@@ -690,23 +756,28 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* Sets the HTML CSS style section contents.
+ *
* <p>
* The format of this value is CSS.
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#css() @HtmlDoc.css()} annotation.
*
- * @param value The HTML CSS style section contents.
- * Object will be converted to a string using {@link Object#toString()}.
- * <p>
- * <ul class='doctree'>
- * <li class='info'>
- * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
- * waste string concatenation cycles on non-HTML views.
- * </ul>
+ * @param value
+ * The HTML CSS style section contents.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
* @return This object (for method chaining).
*/
public RestResponse setHtmlCss(Object value) {
@@ -716,26 +787,32 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* 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.
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>) and can use URL protocols defined
* by {@link UriResolver}.
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#cssUrl() @HtmlDoc.cssUrl()} annotation.
*
- * @param value The CSS URL in the HTML CSS style section.
- * Object will be converted to a string using {@link Object#toString()}.
- * <p>
- * <ul class='doctree'>
- * <li class='info'>
- * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
- * waste string concatenation cycles on non-HTML views.
- * </ul>
+ * @param value
+ * The CSS URL in the HTML CSS style section.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
* @return This object (for method chaining).
*/
public RestResponse setHtmlCssUrl(Object value) {
@@ -745,6 +822,7 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* Shorthand method for forcing the rendered HTML content to be no-wrap.
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#nowrap() @HtmlDoc.nowrap()} annotation.
*
@@ -758,6 +836,7 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* Specifies the text to display when serializing an empty array or collection.
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#noResultsMessage() @HtmlDoc.noResultsMessage()}
* annotation.
@@ -772,9 +851,11 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* 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.
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#template() @HtmlDoc.template()} annotation.
*
@@ -788,9 +869,11 @@ public final class RestResponse extends HttpServletResponseWrapper {
/**
* 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.
+ *
* <p>
* This is the programmatic equivalent to the {@link HtmlDoc#template() @HtmlDoc.template()} annotation.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestServlet.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestServlet.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestServlet.java
index 37db4e0..52ab73c 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestServlet.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestServlet.java
@@ -28,6 +28,7 @@ import org.apache.juneau.utils.*;
/**
* Servlet implementation of a REST resource.
+ *
* <p>
* Refer to <a class="doclink" href="package-summary.html#TOC">REST Servlet API</a> for information about using this
* class.
@@ -76,14 +77,18 @@ public abstract class RestServlet extends HttpServlet {
/**
* Resource initialization method.
+ *
* <p>
* Identical to {@link Servlet#init(ServletConfig)} except the config object provides access to the external config
* file, configuration properties, and variable resolver defined for this resource.
+ *
* <p>
* Classes can also use {@link HttpServlet#init()} and {@link RestServlet#getServletConfig()} as well to perform
* initialization.
+ *
* <p>
* Note that if you override this method, you must first call <code><jk>super</jk>.init(servletConfig)</code>!
+ *
* <p>
* Resource classes that don't extend from {@link RestServlet} can add this method to their class to get access to
* the config object.
@@ -102,8 +107,10 @@ public abstract class RestServlet extends HttpServlet {
/**
* Convenience method if you want to perform initialization on your resource after all configuration settings
* have been made.
+ *
* <p>
* This allows you to get access to the {@link RestContext} object during initialization.
+ *
* <p>
* The default implementation does nothing.
*
@@ -128,6 +135,7 @@ public abstract class RestServlet extends HttpServlet {
/**
* The main service method.
+ *
* <p>
* Subclasses can optionally override this method if they want to tailor the behavior of requests.
*/
@@ -156,9 +164,11 @@ public abstract class RestServlet extends HttpServlet {
/**
* Returns the read-only context object that contains all the configuration information about this resource.
+ *
* <p>
* This object is <jk>null</jk> during the call to {@link #init(RestConfig)} but is populated by the time
* {@link #init()} is called.
+ *
* <p>
* Resource classes that don't extend from {@link RestServlet} can add the following method to their class to get
* access to this context object:
@@ -174,10 +184,13 @@ public abstract class RestServlet extends HttpServlet {
/**
* Callback method for listening for successful completion of requests.
+ *
* <p>
* Subclasses can override this method for gathering performance statistics.
+ *
* <p>
* The default implementation does nothing.
+ *
* <p>
* Resources that don't extend from {@link RestServlet} can implement an equivalent method by overriding the
* {@link RestCallHandler#onSuccess(RestRequest, RestResponse, long)} method.
@@ -190,9 +203,11 @@ public abstract class RestServlet extends HttpServlet {
/**
* Callback method that gets invoked right before the REST Java method is invoked.
+ *
* <p>
* Subclasses can override this method to override request headers or set request-duration properties before the
* Java method is invoked.
+ *
* <p>
* Resources that don't extend from {@link RestServlet} can implement an equivalent method by overriding the
* {@link RestCallHandler#onPreCall(RestRequest)} method.
@@ -205,9 +220,11 @@ public abstract class RestServlet extends HttpServlet {
/**
* Callback method that gets invoked right after the REST Java method is invoked, but before the serializer is
* invoked.
+ *
* <p>
* Subclasses can override this method to override request and response headers, or set/override properties used by
* the serializer.
+ *
* <p>
* Resources that don't extend from {@link RestServlet} can implement an equivalent method by overriding the
* {@link RestCallHandler#onPostCall(RestRequest,RestResponse)} method.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletDefault.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletDefault.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletDefault.java
index d5348e9..dc5f7ed 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletDefault.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletDefault.java
@@ -28,9 +28,9 @@ import org.apache.juneau.xml.*;
/**
* Subclass of {@link RestServlet} with default serializers and parsers defined.
+ *
* <p>
* Supports the following request <code>Accept</code> header values with the resulting response <code>Content-Type</code>:
- * </p>
* <table class='styled'>
* <tr>
* <th>Accept</th>
@@ -126,18 +126,22 @@ import org.apache.juneau.xml.*;
* <td>{@link PlainTextParser}</td>
* </tr>
* </table>
+ *
* <p>
* It should be noted that we do NOT add {@link JsoParser} to the list of parsers since this could cause security
* issues.
* Use caution when using this particular parser as it could inadvertently cause code execution security holes.
+ *
* <p>
* The list of serializers and parsers can be appended to using the
- * {@link RestResource#serializers() @RestResource.serializers()} and
- * {@link RestResource#parsers() @RestResource.parsers()} annotations on subclasses.
+ * {@link RestResource#serializers() @RestResource.serializers()} and
+ * {@link RestResource#parsers() @RestResource.parsers()} annotations on subclasses.
+ *
* <p>
* This subclass also provides a default OPTIONS page by implementing a {@link #getOptions(RestRequest)} that returns a
* POJO consisting of beans describing the class.
* <img class='bordered' src='doc-files/OptionsPage.png'>
+ *
* <p>
* The OPTIONS page can be modified or augmented by overriding this method and providing your own data.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletGroupDefault.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletGroupDefault.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletGroupDefault.java
index 0864d54..7376453 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletGroupDefault.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletGroupDefault.java
@@ -17,9 +17,11 @@ import org.apache.juneau.rest.labels.*;
/**
* Specialized subclass of {@link RestServletDefault} for showing "group" pages.
+ *
* <p>
* Group pages consist of simple lists of child resource URLs and their labels.
* They're meant to be used as jumping-off points for child resources.
+ *
* <p>
* Child resources are specified using the {@link RestResource#children()} annotation.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestUtils.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestUtils.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestUtils.java
index 0d3dddb..8c72906 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestUtils.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestUtils.java
@@ -90,6 +90,7 @@ public final class RestUtils {
/**
* Efficiently trims the path info part from a request URI.
+ *
* <p>
* The result is the URI of the servlet itself.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/StreamResource.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/StreamResource.java b/juneau-rest/src/main/java/org/apache/juneau/rest/StreamResource.java
index ebfa1be..420248a 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/StreamResource.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/StreamResource.java
@@ -24,10 +24,12 @@ import org.apache.juneau.rest.response.*;
/**
* Represents the contents of a byte stream file with convenience methods for adding HTTP response headers.
+ *
* <p>
* The purpose of this class is to maintain an in-memory reusable byte array of a streamed resource for the fastest
* possible streaming.
* Therefore, this object is designed to be reused and thread-safe.
+ *
* <p>
* This class is handled special by the {@link StreamableHandler} class.
* This allows these objects to be returned as responses by REST methods.
@@ -42,16 +44,17 @@ public class StreamResource implements Streamable {
* Constructor.
*
* @param mediaType The resource media type.
- * @param contents The resource contents.
- * <br>If multiple contents are specified, the results will be concatenated.
- * <br>Contents can be any of the following:
- * <ul>
- * <li><code><jk>byte</jk>[]</code>
- * <li><code>InputStream</code>
- * <li><code>Reader</code> - Converted to UTF-8 bytes.
- * <li><code>File</code>
- * <li><code>CharSequence</code> - Converted to UTF-8 bytes.
- * </ul>
+ * @param contents
+ * The resource contents.
+ * <br>If multiple contents are specified, the results will be concatenated.
+ * <br>Contents can be any of the following:
+ * <ul>
+ * <li><code><jk>byte</jk>[]</code>
+ * <li><code>InputStream</code>
+ * <li><code>Reader</code> - Converted to UTF-8 bytes.
+ * <li><code>File</code>
+ * <li><code>CharSequence</code> - Converted to UTF-8 bytes.
+ * </ul>
* @throws IOException
*/
public StreamResource(MediaType mediaType, Object...contents) throws IOException {
@@ -63,16 +66,17 @@ public class StreamResource implements Streamable {
*
* @param mediaType The resource media type.
* @param headers The HTTP response headers for this streamed resource.
- * @param contents The resource contents.
- * <br>If multiple contents are specified, the results will be concatenated.
- * <br>Contents can be any of the following:
- * <ul>
- * <li><code><jk>byte</jk>[]</code>
- * <li><code>InputStream</code>
- * <li><code>Reader</code> - Converted to UTF-8 bytes.
- * <li><code>File</code>
- * <li><code>CharSequence</code> - Converted to UTF-8 bytes.
- * </ul>
+ * @param contents
+ * The resource contents.
+ * <br>If multiple contents are specified, the results will be concatenated.
+ * <br>Contents can be any of the following:
+ * <ul>
+ * <li><code><jk>byte</jk>[]</code>
+ * <li><code>InputStream</code>
+ * <li><code>Reader</code> - Converted to UTF-8 bytes.
+ * <li><code>File</code>
+ * <li><code>CharSequence</code> - Converted to UTF-8 bytes.
+ * </ul>
* @throws IOException
*/
public StreamResource(MediaType mediaType, Map<String,Object> headers, Object...contents) throws IOException {
@@ -137,19 +141,21 @@ public class StreamResource implements Streamable {
/**
* Specifies the contents for this resource.
+ *
* <p>
* This method can be called multiple times to add more content.
*
- * @param contents The resource contents.
- * <br>If multiple contents are specified, the results will be concatenated.
- * <br>Contents can be any of the following:
- * <ul>
- * <li><code><jk>byte</jk>[]</code>
- * <li><code>InputStream</code>
- * <li><code>Reader</code> - Converted to UTF-8 bytes.
- * <li><code>File</code>
- * <li><code>CharSequence</code> - Converted to UTF-8 bytes.
- * </ul>
+ * @param contents
+ * The resource contents.
+ * <br>If multiple contents are specified, the results will be concatenated.
+ * <br>Contents can be any of the following:
+ * <ul>
+ * <li><code><jk>byte</jk>[]</code>
+ * <li><code>InputStream</code>
+ * <li><code>Reader</code> - Converted to UTF-8 bytes.
+ * <li><code>File</code>
+ * <li><code>CharSequence</code> - Converted to UTF-8 bytes.
+ * </ul>
* @return This object (for method chaining).
*/
public Builder contents(Object...contents) {
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/UrlPathPattern.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/UrlPathPattern.java b/juneau-rest/src/main/java/org/apache/juneau/rest/UrlPathPattern.java
index 41bc08d..2ed259e 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/UrlPathPattern.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/UrlPathPattern.java
@@ -21,6 +21,7 @@ import org.apache.juneau.rest.annotation.*;
/**
* A parsed path pattern constructed from a {@link RestMethod#path()} value.
+ *
* <p>
* Handles aspects of matching and precedence ordering.
*/
@@ -77,8 +78,9 @@ public final class UrlPathPattern implements Comparable<UrlPathPattern> {
* Returns a non-<jk>null</jk> value if the specified path matches this pattern.
*
* @param path The path to match against.
- * @return An array of values matched against <js>"{var}"</js> variable in the pattern, or an empty array if the
- * pattern matched but no vars were present, or <jk>null</jk> if the specified path didn't match the pattern.
+ * @return
+ * An array of values matched against <js>"{var}"</js> variable in the pattern, or an empty array if the
+ * pattern matched but no vars were present, or <jk>null</jk> if the specified path didn't match the pattern.
*/
protected String[] match(String path) {
@@ -111,6 +113,8 @@ public final class UrlPathPattern implements Comparable<UrlPathPattern> {
/**
* Comparator for this object.
+ *
+ * <p>
* The comparator is designed to order URL pattern from most-specific to least-specific.
* For example, the following patterns would be ordered as follows:
* <ol>
@@ -161,6 +165,8 @@ public final class UrlPathPattern implements Comparable<UrlPathPattern> {
/**
* Returns this path pattern as the compiled regular expression.
+ *
+ * <p>
* Useful for debugging.
*
* @return The path pattern.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Body.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Body.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Body.java
index 2022bf6..5457265 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Body.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Body.java
@@ -29,9 +29,9 @@ import java.lang.annotation.*;
* ...
* }
* </p>
+ *
* <p>
* This is functionally equivalent to the following code...
- * </p>
* <p class='bcode'>
* <ja>@RestMethod</ja>(name=<js>"POST"</js>)
* <jk>public void</jk> doPostPerson(RestRequest req, RestResponse res) {
@@ -39,10 +39,10 @@ import java.lang.annotation.*;
* ...
* }
* </p>
+ *
* <p>
* {@link Reader Readers} and {@link InputStream InputStreams} can also be specified as content parameters.
* When specified, any registered parsers are bypassed.
- * </p>
* <p class='bcode'>
* <ja>@RestMethod</ja>(name=<js>"POST"</js>)
* <jk>public void</jk> doPostPerson(<ja>@Header</ja>(<js>"Content-Type"</js>) String mediaType, <ja>@Body</ja> InputStream input) {
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/FormData.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/FormData.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/FormData.java
index 1cfa491..95405b0 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/FormData.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/FormData.java
@@ -31,9 +31,9 @@ import org.apache.juneau.rest.*;
* ...
* }
* </p>
+ *
* <p>
* This is functionally equivalent to the following code...
- * </p>
* <p class='bcode'>
* <ja>@RestMethod</ja>(name=<js>"POST"</js>)
* <jk>public void</jk> doPost(RestRequest req, RestResponse res) {
@@ -45,10 +45,11 @@ import org.apache.juneau.rest.*;
* </p>
*
* <h6 class='topic'>Important note concerning FORM posts</h6>
- * <p>
+ *
* This annotation should not be combined with the {@link Body @Body} annotation or {@link RestRequest#getBody()} method
* for <code>application/x-www-form-urlencoded POST</code> posts, since it will trigger the underlying servlet
* API to parse the body content as key-value pairs resulting in empty content.
+ *
* <p>
* The {@link Query @Query} annotation can be used to retrieve a URL parameter in the URL string without triggering the
* servlet to drain the body content.
@@ -66,6 +67,7 @@ public @interface FormData {
/**
* A synonym for {@link #name()}.
+ *
* <p>
* Allows you to use shortened notation if you're only specifying the name.
*/
@@ -73,11 +75,13 @@ public @interface FormData {
/**
* 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>.
+ * 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.
*/
@@ -85,6 +89,7 @@ public @interface FormData {
/**
* The expected format of the request parameter.
+ *
* <p>
* Possible values:
* <ul class='spaced-list'>
@@ -99,9 +104,10 @@ public @interface FormData {
* <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.
+ * <js>"foo"</js> when using UON mode.
*/
String format() default "INHERIT";
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HasFormData.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HasFormData.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HasFormData.java
index 150c2fb..76078cc 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HasFormData.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HasFormData.java
@@ -22,6 +22,7 @@ import org.apache.juneau.rest.*;
/**
* Annotation that can be applied to a parameter of a {@link RestMethod} annotated method to identify whether or not
* the request has the specified multipart form POST parameter.
+ *
* <p>
* Note that this can be used to detect the existence of a parameter when it's not set to a particular value.
*
@@ -32,9 +33,9 @@ import org.apache.juneau.rest.*;
* ...
* }
* </p>
+ *
* <p>
* This is functionally equivalent to the following code...
- * </p>
* <p class='bcode'>
* <ja>@RestMethod</ja>(name=<js>"POST"</js>)
* <jk>public void</jk> doPost(RestRequest req) {
@@ -42,6 +43,7 @@ import org.apache.juneau.rest.*;
* ...
* }
* </p>
+ *
* <p>
* The following table shows the behavioral differences between <code>@HasFormData</code> and <code>@FormData</code>...
* <table class='styled'>
@@ -73,10 +75,11 @@ import org.apache.juneau.rest.*;
* </table>
*
* <h6 class='topic'>Important note concerning FORM posts</h6>
- * <p>
+ *
* This annotation should not be combined with the {@link Body @Body} annotation or {@link RestRequest#getBody()} method
* for <code>application/x-www-form-urlencoded POST</code> posts, since it will trigger the underlying servlet API to
* parse the body content as key-value pairs, resulting in empty content.
+ *
* <p>
* The {@link HasQuery @HasQuery} annotation can be used to check for the existing of a URL parameter in the URL string
* without triggering the servlet to drain the body content.
@@ -94,6 +97,7 @@ public @interface HasFormData {
/**
* A synonym for {@link #name()}.
+ *
* <p>
* Allows you to use shortened notation if you're only specifying the name.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HasQuery.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HasQuery.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HasQuery.java
index d874a95..f355ebd 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HasQuery.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HasQuery.java
@@ -22,6 +22,7 @@ import org.apache.juneau.rest.*;
/**
* Identical to {@link HasFormData @HasFormData}, but only checks the existing of the parameter in the URL string, not
* URL-encoded form posts.
+ *
* <p>
* Unlike {@link HasFormData @HasFormData}, using this annotation does not result in the servlet reading the contents
* of URL-encoded form posts.
@@ -35,9 +36,9 @@ import org.apache.juneau.rest.*;
* ...
* }
* </p>
+ *
* <p>
* This is functionally equivalent to the following code...
- * </p>
* <p class='bcode'>
* <ja>@RestMethod</ja>(name=<js>"GET"</js>)
* <jk>public void</jk> doGet(RestRequest req) {
@@ -59,6 +60,7 @@ public @interface HasQuery {
/**
* A synonym for {@link #name()}.
+ *
* <p>
* Allows you to use shortened notation if you're only specifying the name.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Header.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Header.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Header.java
index 6f0ee4f..d7758b1 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Header.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Header.java
@@ -28,9 +28,9 @@ import java.lang.annotation.*;
* ...
* }
* </p>
+ *
* <p>
* This is functionally equivalent to the following code...
- * </p>
* <p class='bcode'>
* <ja>@RestMethod</ja>(name=<js>"GET"</js>)
* <jk>public void</jk> doPostPerson(RestRequest req, RestResponse res) {
@@ -52,6 +52,7 @@ public @interface Header {
/**
* A synonym for {@link #name()}.
+ *
* <p>
* Allows you to use shortened notation if you're only specifying the name.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HtmlDoc.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HtmlDoc.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HtmlDoc.java
index ec2fe87..8b4fbb9 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HtmlDoc.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HtmlDoc.java
@@ -18,12 +18,15 @@ import org.apache.juneau.rest.*;
/**
* 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'>
@@ -39,6 +42,7 @@ import org.apache.juneau.rest.*;
* )
* )
* </p>
+ *
* <p>
* The purpose of these annotation is to populate the HTML document view which by default consists of the following
* structure:
@@ -75,11 +79,14 @@ public @interface HtmlDoc {
/**
* Sets the HTML page title in the header section of the page generated by the default HTML doc template.
+ *
* <p>
* The format of this value is HTML (phrasing content only).
+ *
* <p>
* It gets wrapped in a <code><xt><h3> <xa>class</xa>=<xs>'title'</xs>></xt></code> element and then added
* to the <code><xt><header></code> section on the page.
+ *
* <p>
* If not specified, the page title is pulled from one of the following locations:
* <ol>
@@ -89,11 +96,13 @@ public @interface HtmlDoc {
* <li><code>{servletClass}.title</code> resource bundle value.
* <li><code>info/title</code> entry in swagger file.
* </ol>
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
- * <p>
+ *
* <ul class='doctree'>
* <li class='info'>
* In most cases, you'll simply want to use the <code>@RestResource(title)</code> annotation to specify the
@@ -104,6 +113,7 @@ public @interface HtmlDoc {
* The entire header section can be rendered with arbitrary HTML using {@link #header()}.
* This annotation is ignored when the {@link #header()} annotation is specified.
* </ul>
+ *
* <p>
* The programmatic equivalent to this annotation are the
* {@link RestConfig#setHtmlTitle(String)}/{@link RestResponse#setHtmlTitle(Object)} methods.
@@ -112,11 +122,14 @@ public @interface HtmlDoc {
/**
* Sets the HTML page subtitle in the header section of the page generated by the default HTML doc template.
+ *
* <p>
* The format of this value is HTML (phrasing content only).
+ *
* <p>
* It gets wrapped in a <code><xt><h5> <xa>class</xa>=<xs>'description'</xs>></xt></code> element and then
* added to the <code><xt><header></code> section on the page.
+ *
* <p>
* If not specified, the page title is pulled from one of the following locations:
* <ol>
@@ -128,11 +141,13 @@ public @interface HtmlDoc {
* <li><code>{servletClass}.description</code> resource bundle value.
* <li><code>info/description</code> entry in swagger file.
* </ol>
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
- * <p>
+ *
* <ul class='doctree'>
* <li class='info'>
* In most cases, you'll simply want to use the <code>@RestResource(description)</code> or
@@ -143,6 +158,7 @@ public @interface HtmlDoc {
* The entire header section can be rendered with arbitrary HTML using {@link #header()}.
* This annotation is ignored when the {@link #header()} annotation is specified.
* </ul>
+ *
* <p>
* The programmatic equivalent to this annotation are the
* {@link RestConfig#setHtmlDescription(String)}/{@link RestResponse#setHtmlDescription(Object)} methods.
@@ -151,14 +167,19 @@ public @interface HtmlDoc {
/**
* Sets the HTML page branding in the header section of the page generated by the default HTML doc template.
+ *
* <p>
* The format of this value is HTML.
+ *
* <p>
* This is arbitrary HTML that can be added to the header section to provide basic custom branding on the page.
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
+ *
* <p>
* The programmatic equivalent to this annotation are the
* {@link RestConfig#setHtmlBranding(String)}/{@link RestResponse#setHtmlBranding(Object)} methods.
@@ -167,8 +188,10 @@ 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.
@@ -181,12 +204,16 @@ public @interface HtmlDoc {
* )
* )
* </p>
+ *
* <p>
* When a value is specified, the {@link #title()} and {@link #description()} values will be ignored.
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no header.
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* The programmatic equivalent to this annotation are the
* {@link RestConfig#setHtmlHeader(String)}/{@link RestResponse#setHtmlHeader(Object)} methods.
@@ -195,9 +222,11 @@ public @interface HtmlDoc {
/**
* Sets the links in the HTML nav section.
+ *
* <p>
* The format of this value is a lax-JSON map of key/value pairs where the keys are the link text and the values are
* relative (to the servlet) or absolute URLs.
+ *
* <p>
* The page links are positioned immediately under the title and text.
*
@@ -209,12 +238,16 @@ public @interface HtmlDoc {
* )
* )
* </p>
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
+ *
* <p>
* This field can also use URIs of any support type in {@link UriResolver}.
+ *
* <p>
* The programmatic equivalent to this annotation are the
* {@link RestConfig#setHtmlLinks(String)}/{@link RestResponse#setHtmlLinks(Object)} methods.
@@ -223,10 +256,13 @@ public @interface HtmlDoc {
/**
* 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.
*
@@ -238,12 +274,16 @@ public @interface HtmlDoc {
* )
* )
* </p>
+ *
* <p>
* When a value is specified, the {@link #links()} value will be ignored.
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
+ *
* <p>
* The programmatic equivalent to this annotation are the
* {@link RestConfig#setHtmlNav(String)}/{@link RestResponse#setHtmlNav(Object)} methods.
@@ -252,8 +292,10 @@ public @interface HtmlDoc {
/**
* 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.
*
@@ -265,10 +307,13 @@ public @interface HtmlDoc {
* )
* )
* </p>
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
+ *
* <p>
* The programmatic equivalent to this annotation are the
* {@link RestConfig#setHtmlAside(String)}/{@link RestResponse#setHtmlAside(Object)} methods.
@@ -277,8 +322,10 @@ public @interface HtmlDoc {
/**
* 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.
*
@@ -290,10 +337,13 @@ public @interface HtmlDoc {
* )
* )
* </p>
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
+ *
* <p>
* The programmatic equivalent to this annotation are the
* {@link RestConfig#setHtmlFooter(String)}/{@link RestResponse#setHtmlFooter(Object)} methods.
@@ -302,6 +352,7 @@ public @interface HtmlDoc {
/**
* Sets the HTML CSS style section contents.
+ *
* <p>
* The format of this value is CSS.
*
@@ -313,10 +364,13 @@ public @interface HtmlDoc {
* )
* )
* </p>
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ *
* <p>
* A value of <js>"NONE"</js> can be used to force no value.
+ *
* <p>
* The programmatic equivalent to this annotation are the
* {@link RestConfig#setHtmlCss(String)}/{@link RestResponse#setHtmlCss(Object)} methods.
@@ -325,10 +379,13 @@ public @interface HtmlDoc {
/**
* 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.
*
@@ -340,9 +397,11 @@ public @interface HtmlDoc {
* )
* )
* </p>
+ *
* <p>
* This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>) and can use URL protocols defined
* by {@link UriResolver}.
+ *
* <p>
* The programmatic equivalent to this annotation are the
* {@link RestConfig#setHtmlCssUrl(String)}/{@link RestResponse#setHtmlCssUrl(Object)} methods.
@@ -351,6 +410,7 @@ public @interface HtmlDoc {
/**
* Shorthand method for forcing the rendered HTML content to be no-wrap.
+ *
* <p>
* This only applies to the rendered data portion of the page.
*/
@@ -363,9 +423,11 @@ public @interface HtmlDoc {
/**
* 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.
+ *
* <p>
* The programmatic equivalent to this annotation are the
* {@link RestConfig#setHtmlTemplate(Class)}/{@link RestResponse#setHtmlTemplate(Class)} methods.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Messages.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Messages.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Messages.java
index 30e014a..921b0bc 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Messages.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Messages.java
@@ -23,6 +23,7 @@ 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}.
*
@@ -33,9 +34,9 @@ import org.apache.juneau.utils.*;
* <jk>return</jk> messages.getString(<js>"myLocalizedMessage"</js>);
* }
* </p>
+ *
* <p>
* This is functionally equivalent to the following code...
- * </p>
* <p class='bcode'>
* <ja>@RestMethod</ja>(name=<js>"GET"</js>)
* <jk>public</jk> String doGet(RestRequest req) {
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Method.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Method.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Method.java
index 327a70c..3af46e2 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Method.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Method.java
@@ -20,6 +20,7 @@ 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).
*
@@ -30,9 +31,9 @@ import java.lang.annotation.*;
* ...
* }
* </p>
+ *
* <p>
* This is functionally equivalent to the following code...
- * </p>
* <p class='bcode'>
* <ja>@RestMethod</ja>(name=<js>"*"</js>)
* <jk>public void</jk> doAnything(RestRequest req, RestResponse res) {
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java
index b63fd8b..8aaa396 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java
@@ -19,8 +19,10 @@ 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'>
@@ -29,6 +31,7 @@ public @interface MethodSwagger {
* url: string
* }
* </p>
+ *
* <p>
* The default value pulls the description from the <code>(className.?)[javaMethodName].externalDocs</code> entry in
* the servlet resource bundle.
@@ -43,8 +46,10 @@ public @interface MethodSwagger {
* )
* )
* </p>
+ *
* <p>
* This field can contain variables (e.g. "$L{my.localized.variable}").
+ *
* <p>
* Corresponds to the swagger field <code>/paths/{path}/{method}/externalDocs</code>.
*/
@@ -52,11 +57,14 @@ public @interface MethodSwagger {
/**
* 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.
@@ -70,8 +78,10 @@ public @interface MethodSwagger {
* )
* )
* </p>
+ *
* <p>
* This field can contain variables (e.g. "$L{my.localized.variable}").
+ *
* <p>
* Corresponds to the swagger field <code>/paths/{path}/{method}/tags</code>.
*/
@@ -79,8 +89,10 @@ public @interface MethodSwagger {
/**
* 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.
@@ -94,8 +106,10 @@ public @interface MethodSwagger {
* )
* )
* </p>
+ *
* <p>
* This field can contain variables (e.g. "$L{my.localized.variable}").
+ *
* <p>
* Corresponds to the swagger field <code>/paths/{path}/{method}/deprecated</code>.
*/
@@ -103,6 +117,7 @@ public @interface MethodSwagger {
/**
* 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.
@@ -122,6 +137,8 @@ public @interface MethodSwagger {
* )
* )
* </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'>
@@ -130,11 +147,15 @@ public @interface MethodSwagger {
* <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>
* These annotations can contain variables (e.g. "$L{my.localized.variable}").
+ *
* <p>
* Corresponds to the swagger field <code>/paths/{path}/{method}/parameters</code>.
*/
@@ -142,6 +163,7 @@ public @interface MethodSwagger {
/**
* 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.
@@ -164,15 +186,20 @@ public @interface MethodSwagger {
* )
* )
* </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>
* These annotations can contain variables (e.g. "$L{my.localized.variable}").
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Parameter.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Parameter.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Parameter.java
index 3c1d935..834bf74 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Parameter.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Parameter.java
@@ -44,6 +44,7 @@ public @interface Parameter {
/**
* The location of the parameter.
+ *
* <p>
* Possible values are:
* <ul>
@@ -58,6 +59,7 @@ public @interface Parameter {
/**
* 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
@@ -71,11 +73,13 @@ public @interface Parameter {
/**
* 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
@@ -85,6 +89,7 @@ public @interface Parameter {
/**
* 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>.
@@ -93,11 +98,12 @@ public @interface Parameter {
/**
* 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>.
+ * 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'>
@@ -116,6 +122,7 @@ public @interface Parameter {
/**
* 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>.
@@ -126,6 +133,7 @@ public @interface Parameter {
/**
* 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.
@@ -134,6 +142,7 @@ public @interface Parameter {
/**
* 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.
@@ -143,6 +152,7 @@ public @interface Parameter {
/**
* Required if <code>type</code> is <js>"array"</js>.
+ *
* <p>
* Describes the type of items in the array.
*
@@ -159,6 +169,7 @@ public @interface Parameter {
* )
* <jk>public void</jk> doAnything() {
* </p>
+ *
* <p>
* See <a class="doclink" href="http://swagger.io/specification/#itemsObject">Items Object</a> for further details.
*/
@@ -166,6 +177,7 @@ public @interface Parameter {
/**
* Determines the format of the array if type array is used.
+ *
* <p>
* Possible values are:
* <ul>
@@ -183,6 +195,7 @@ public @interface Parameter {
/**
* 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.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Path.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Path.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Path.java
index 9a09497..212f290 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Path.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Path.java
@@ -29,12 +29,12 @@ import java.lang.annotation.*;
* ...
* }
* </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>
* <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,
@@ -42,12 +42,12 @@ import java.lang.annotation.*;
* ...
* }
* </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>
* <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,
@@ -55,8 +55,9 @@ import java.lang.annotation.*;
* ...
* }
* </p>
- * You can also use <code>{#}</code> notation to specify path parameters without specifying names.
+ *
* <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,
@@ -73,6 +74,7 @@ public @interface Path {
/**
* URL path variable name.
+ *
* <p>
* Optional if the attributes are specified in the same order as in the URL path pattern.
*/
@@ -80,6 +82,7 @@ public @interface Path {
/**
* A synonym for {@link #name()}.
+ *
* <p>
* Allows you to use shortened notation if you're only specifying the name.
*/