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. */
