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:20 UTC
[03/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/ResponseHandler.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/ResponseHandler.java b/juneau-rest/src/main/java/org/apache/juneau/rest/ResponseHandler.java
index 43dbc4f..710f81c 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/ResponseHandler.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/ResponseHandler.java
@@ -22,9 +22,11 @@ import org.apache.juneau.rest.response.*;
/**
* Defines the interface for handlers that convert POJOs to appropriate HTTP responses.
+ *
* <p>
* The {@link RestServlet} API uses the concept of registered response handlers for converting objects returned by REST
* methods or set through {@link RestResponse#setOutput(Object)} into appropriate HTTP responses.
+ *
* <p>
* Response handlers can be associated with {@link RestServlet RestServlets} through the following ways:
* <ul class='spaced-list'>
@@ -34,6 +36,7 @@ import org.apache.juneau.rest.response.*;
* By calling the {@link RestConfig#addResponseHandlers(Class...)} and augmenting or creating your
* own list of handlers.
* </ul>
+ *
* <p>
* By default, {@link RestServlet RestServlets} are registered with the following response handlers:
* <ul class='spaced-list'>
@@ -52,9 +55,11 @@ import org.apache.juneau.rest.response.*;
* <li>
* {@link StreamableHandler} - Handles {@link Streamable} objects.
* </ul>
+ *
* <p>
* Response handlers can be used to process POJOs that cannot normally be handled through Juneau serializers, or
* because it's simply easier to define response handlers for special cases.
+ *
* <p>
* The following example shows how to create a response handler to handle special <code>Foo</code> objects outside the
* normal Juneau architecture.
@@ -96,10 +101,12 @@ public interface ResponseHandler {
* @param res The HTTP servlet response;
* @param output The POJO returned by the REST method that now needs to be sent to the response.
* @return true If this handler handled the response.
- * @throws IOException If low-level exception occurred on output stream.
- * Results in a {@link HttpServletResponse#SC_INTERNAL_SERVER_ERROR} error.
- * @throws RestException If some other exception occurred.
- * Can be used to provide an appropriate HTTP response code and message.
+ * @throws IOException
+ * If low-level exception occurred on output stream.
+ * Results in a {@link HttpServletResponse#SC_INTERNAL_SERVER_ERROR} error.
+ * @throws RestException
+ * If some other exception occurred.
+ * Can be used to provide an appropriate HTTP response code and message.
*/
boolean handle(RestRequest req, RestResponse res, Object output) throws IOException, RestException;
}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestCallHandler.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestCallHandler.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestCallHandler.java
index 663b184..3e8b6da 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestCallHandler.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestCallHandler.java
@@ -28,9 +28,11 @@ import org.apache.juneau.rest.vars.*;
/**
* Class that handles the basic lifecycle of an HTTP REST call.
+ *
* <p>
* Subclasses can override these methods to tailor how HTTP REST calls are handled.
* Subclasses MUST implement a public constructor that takes in a {@link RestContext} object.
+ *
* <p>
* RestCallHandlers are associated with servlets/resources in one of the following ways:
* <ul>
@@ -59,6 +61,7 @@ public class RestCallHandler {
/**
* Creates a {@link RestRequest} object based on the specified incoming {@link HttpServletRequest} object.
+ *
* <p>
* Subclasses may choose to override this method to provide a specialized request object.
*
@@ -73,6 +76,7 @@ public class RestCallHandler {
/**
* Creates a {@link RestResponse} object based on the specified incoming {@link HttpServletResponse} object
* and the request returned by {@link #createRequest(HttpServletRequest)}.
+ *
* <p>
* Subclasses may choose to override this method to provide a specialized response object.
*
@@ -87,6 +91,7 @@ public class RestCallHandler {
/**
* The main service method.
+ *
* <p>
* Subclasses can optionally override this method if they want to tailor the behavior of requests.
*
@@ -191,9 +196,11 @@ public class RestCallHandler {
/**
* The main method for serializing POJOs passed in through the {@link RestResponse#setOutput(Object)} method or
* returned by the Java method.
+ *
* <p>
* Subclasses may override this method if they wish to modify the way the output is rendered or support other output
* formats.
+ *
* <p>
* The default implementation simply iterates through the response handlers on this resource
* looking for the first one whose {@link ResponseHandler#handle(RestRequest, RestResponse, Object)} method returns
@@ -215,6 +222,7 @@ public class RestCallHandler {
/**
* Handle the case where a matching method was not found.
+ *
* <p>
* Subclasses can override this method to provide a 2nd-chance for specifying a response.
* The default implementation will simply throw an exception with an appropriate message.
@@ -240,9 +248,11 @@ public class RestCallHandler {
/**
* Method for handling response errors.
+ *
* <p>
* The default implementation logs the error and calls
* {@link #renderError(HttpServletRequest,HttpServletResponse,RestException)}.
+ *
* <p>
* Subclasses can override this method to provide their own custom error response handling.
*
@@ -259,9 +269,11 @@ public class RestCallHandler {
/**
* Method for rendering response errors.
+ *
* <p>
* The default implementation renders a plain text English message, optionally with a stack trace if
* {@link RestContext#REST_renderResponseStackTraces} is enabled.
+ *
* <p>
* Subclasses can override this method to provide their own custom error response handling.
*
@@ -302,8 +314,10 @@ public class RestCallHandler {
/**
* 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.
*
@@ -318,6 +332,7 @@ public class RestCallHandler {
/**
* 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.
@@ -333,6 +348,7 @@ public class RestCallHandler {
/**
* 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.
@@ -348,6 +364,7 @@ public class RestCallHandler {
/**
* Returns the session objects for the specified request.
+ *
* <p>
* The default implementation simply returns a single map containing <code>{'req':req}</code>.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestConfig.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestConfig.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestConfig.java
index 0e99c03..dee6d29 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestConfig.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestConfig.java
@@ -41,8 +41,10 @@ import org.apache.juneau.svl.vars.*;
/**
* Defines the initial configuration of a <code>RestServlet</code> or <code>@RestResource</code> annotated object.
+ *
* <p>
* An extension of the {@link ServletConfig} object used during servlet initialization.
+ *
* <p>
* Provides access to the following initialized resources:
* <ul>
@@ -50,10 +52,12 @@ import org.apache.juneau.svl.vars.*;
* <li>{@link #getProperties()} - The modifiable configuration properties for this resource.
* <li>{@link #getVarResolverBuilder()} - The variable resolver for this resource.
* </ul>
+ *
* <p>
* Methods are provided for overriding or augmenting the information provided by the <ja>@RestResource</ja> annotation.
* In general, most information provided in the <ja>@RestResource</ja> annotation can be specified programmatically
* through calls on this object.
+ *
* <p>
* To interact with this object, simply implement the following init method in your resource class:
* <p class='bcode'>
@@ -63,9 +67,11 @@ import org.apache.juneau.svl.vars.*;
* <jk>super</jk>.init(config); <jc>// Make sure this is the last line! (or just leave it out entirely)</jc>
* }
* </p>
+ *
* <p>
* Note that this method is identical to {@link HttpServlet#init(ServletConfig)} except you get access to
* this object instead. Also, this method can throw any exception, not just a {@link ServletException}.
+ *
* <p>
* The parent <code>init(RestServletConfig)</code> method will construct a read-only {@link RestContext} object
* that contains a snapshot of these settings. If you call <code><jk>super</jk>.init(RestServletConfig)</code> before
@@ -124,6 +130,7 @@ public class RestConfig implements ServletConfig {
/**
* Constructor.
+ *
* @param config The servlet config passed into the servlet by the servlet container.
* @param resource The class annotated with <ja>@RestResource</ja>.
* @throws ServletException Something bad happened.
@@ -273,9 +280,11 @@ public class RestConfig implements ServletConfig {
/**
* Adds the specified {@link Var} classes to this config.
+ *
* <p>
* These variables affect the variable resolver returned by {@link RestRequest#getVarResolverSession()} which is
* used to resolve string variables of the form <js>"$X{...}"</js>.
+ *
* <p>
* By default, this config includes the following variables:
* <ul>
@@ -285,6 +294,7 @@ public class RestConfig implements ServletConfig {
* <li>{@link IfVar}
* <li>{@link SwitchVar}
* </ul>
+ *
* <p>
* Later during the construction of {@link RestContext}, we add the following variables:
* <ul>
@@ -307,9 +317,11 @@ public class RestConfig implements ServletConfig {
/**
* Adds a var context object to this config.
+ *
* <p>
* Var context objects are read-only objects associated with the variable resolver for vars that require external
* information.
+ *
* <p>
* For example, the {@link ConfigFileVar} needs access to this resource's {@link ConfigFile} through the
* {@link ConfigFileVar#SESSION_config} object that can be specified as either a session object (temporary) or
@@ -330,6 +342,7 @@ public class RestConfig implements ServletConfig {
/**
* Overwrites the default config file with a custom config file.
+ *
* <p>
* By default, the config file is determined using the {@link RestResource#config() @RestResource.config()}
* annotation.
@@ -345,6 +358,7 @@ public class RestConfig implements ServletConfig {
/**
* Sets a property on this resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#properties()} annotation.
*
@@ -359,8 +373,10 @@ public class RestConfig implements ServletConfig {
/**
* Sets multiple properties on this resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#properties() @RestResource.properties()} annotation.
+ *
* <p>
* Values in the map are added to the existing properties and are overwritten if duplicates are found.
*
@@ -374,9 +390,11 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level bean filters to this resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#beanFilters() @RestResource.beanFilters()}
* annotation.
+ *
* <p>
* Values are added AFTER those found in the annotation and therefore take precedence over those defined via the
* annotation.
@@ -391,8 +409,10 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level pojo swaps to this resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#pojoSwaps() @RestResource.pojoSwaps()} annotation.
+ *
* <p>
* Values are added AFTER those found in the annotation and therefore take precedence over those defined via the
* annotation.
@@ -407,6 +427,7 @@ public class RestConfig implements ServletConfig {
/**
* Specifies the serializer listener class to use for listening to non-fatal serialization errors.
+ *
* <p>
* This is the programmatic equivalent to the
* {@link RestResource#serializerListener() @RestResource.serializerListener()} annotation.
@@ -422,6 +443,7 @@ public class RestConfig implements ServletConfig {
/**
* Specifies the parser listener class to use for listening to non-fatal parse errors.
+ *
* <p>
* This is the programmatic equivalent to the
* {@link RestResource#parserListener() @RestResource.parserListener()} annotation.
@@ -437,6 +459,7 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level parameter resolvers to this resource.
+ *
* <p>
* This is the programmatic equivalent to the
* {@link RestResource#paramResolvers() @RestResource.paramResolvers()} annotation.
@@ -451,9 +474,11 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level serializers to this resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#serializers() @RestResource.serializers()}
* annotation.
+ *
* <p>
* Values are added AFTER those found in the annotation and therefore take precedence over those defined via the
* annotation.
@@ -468,6 +493,7 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level serializers to this resource.
+ *
* <p>
* Same as {@link #addSerializers(Class...)} except allows you to pass in serializer instances.
* The actual serializer ends up being the result of this operation using the bean filters, pojo swaps, and
@@ -475,6 +501,7 @@ public class RestConfig implements ServletConfig {
* <p class='bcode'>
* serializer = serializer.builder().beanFilters(beanFilters).pojoSwaps(pojoSwaps).properties(properties).build();
* </p>
+ *
* <p>
* Values are added AFTER those found in the annotation and therefore take precedence over those defined via the
* annotation.
@@ -489,8 +516,10 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level parsers to this resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#parsers() @RestResource.parsers()} annotation.
+ *
* <p>
* Values are added AFTER those found in the annotation and therefore take precedence over those defined via the
* annotation.
@@ -505,6 +534,7 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level parsers to this resource.
+ *
* <p>
* Same as {@link #addParsers(Class...)} except allows you to pass in parser instances.
* The actual parser ends up being the result of this operation using the bean filters, pojo swaps, and properties
@@ -512,6 +542,7 @@ public class RestConfig implements ServletConfig {
* <p class='bcode'>
* parser = parser.builder().beanFilters(beanFilters).pojoSwaps(pojoSwaps).properties(properties).build();
* </p>
+ *
* <p>
* Values are added AFTER those found in the annotation and therefore take precedence over those defined via the
* annotation.
@@ -526,11 +557,14 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level encoders to this resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#encoders() @RestResource.encoders()} annotation.
+ *
* <p>
* Values are added AFTER those found in the annotation and therefore take precedence over those defined via the
* annotation.
+ *
* <p>
* By default, only the {@link IdentityEncoder} is included in this list.
*
@@ -544,6 +578,7 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level encoders to this resource.
+ *
* <p>
* Same as {@link #addEncoders(Class...)} except allows you to pass in encoder instances.
*
@@ -557,12 +592,15 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level converters to this resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#converters() @RestResource.converters()}
* annotation.
+ *
* <p>
* Values are added AFTER those found in the annotation and therefore take precedence over those defined via the
* annotation.
+ *
* <p>
* By default, this config includes the following converters:
* <ul>
@@ -584,6 +622,7 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level encoders to this resource.
+ *
* <p>
* Same as {@link #addConverters(Class...)} except allows you to pass in converter instances.
*
@@ -597,8 +636,10 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level guards to this resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#guards() @RestResource.guards()} annotation.
+ *
* <p>
* Values are added AFTER those found in the annotation and therefore take precedence over those defined via the
* annotation.
@@ -613,6 +654,7 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level guards to this resource.
+ *
* <p>
* Same as {@link #addGuards(Class...)} except allows you to pass in guard instances.
*
@@ -626,14 +668,17 @@ public class RestConfig implements ServletConfig {
/**
* Adds MIME-type definitions.
+ *
* <p>
* These definitions are used in the following locations for setting the media type on responses:
* <ul>
* <li>{@link RestRequest#getReaderResource(String)}
* <li>Static files resolved through {@link RestResource#staticFiles()}
* </ul>
+ *
* <p>
* Refer to {@link MimetypesFileTypeMap#addMimeTypes(String)} for an explanation of the format.
+ *
* <p>
* By default, this config includes the following mime-type definitions:
* <ul>
@@ -658,10 +703,12 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level default HTTP request headers to this resource.
+ *
* <p>
* Default request headers are default values for when HTTP requests do not specify a header value.
* For example, you can specify a default value for <code>Accept</code> if a request does not specify that header
* value.
+ *
* <p>
* This is the programmatic equivalent to the
* {@link RestResource#defaultRequestHeaders() @RestResource.defaultRequestHeaders()} annotation.
@@ -677,10 +724,12 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level default HTTP request headers to this resource.
+ *
* <p>
* Default request headers are default values for when HTTP requests do not specify a header value.
* For example, you can specify a default value for <code>Accept</code> if a request does not specify that header
* value.
+ *
* <p>
* This is the programmatic equivalent to the
* {@link RestResource#defaultRequestHeaders() @RestResource.defaultRequestHeaders()} annotation.
@@ -701,12 +750,15 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level default HTTP response headers to this resource.
+ *
* <p>
* Default response headers are headers that will be appended to all responses if those headers have not already been
* set on the response object.
+ *
* <p>
* This is the programmatic equivalent to the
* {@link RestResource#defaultResponseHeaders() @RestResource.defaultResponseHeaders()} annotation.
+ *
* <p>
* Values are added AFTER those found in the annotation and therefore take precedence over those defined via the
* annotation.
@@ -722,9 +774,11 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level default HTTP response headers to this resource.
+ *
* <p>
* Default response headers are headers that will be appended to all responses if those headers have not already been
* set on the response object.
+ *
* <p>
* This is the programmatic equivalent to the
* {@link RestResource#defaultResponseHeaders() @RestResource.defaultResponseHeaders()} annotation.
@@ -745,8 +799,10 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level response handler classes to this resource.
+ *
* <p>
* Response handlers are responsible for converting various POJOs returned by REST methods into actual HTTP responses.
+ *
* <p>
* By default, this config includes the following response handlers:
* <ul>
@@ -757,6 +813,7 @@ public class RestConfig implements ServletConfig {
* <li>{@link RedirectHandler}
* <li>{@link DefaultHandler}
* </ul>
+ *
* <p>
* This is the programmatic equivalent to the
* {@link RestResource#responseHandlers() @RestResource.responseHandlers()} annotation.
@@ -771,6 +828,7 @@ public class RestConfig implements ServletConfig {
/**
* Adds class-level response handlers to this resource.
+ *
* <p>
* Same as {@link #addResponseHandlers(Class...)} except allows you to pass in response handler instances.
*
@@ -784,8 +842,10 @@ public class RestConfig implements ServletConfig {
/**
* Adds a child resource to this resource.
+ *
* <p>
* Child resources are resources that are accessed under the path of the parent resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#children() @RestResource.children()} annotation.
*
@@ -800,8 +860,10 @@ public class RestConfig implements ServletConfig {
/**
* Add child resources to this resource.
+ *
* <p>
* Child resources are resources that are accessed under the path of the parent resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#children() @RestResource.children()} annotation.
*
@@ -816,8 +878,10 @@ public class RestConfig implements ServletConfig {
/**
* Add child resources to this resource.
+ *
* <p>
* Child resources are resources that are accessed under the path of the parent resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#children() @RestResource.children()} annotation.
*
@@ -832,8 +896,10 @@ public class RestConfig implements ServletConfig {
/**
* Specifies the list of supported <code>Accept</code> media types for this resource.
+ *
* <p>
* This overrides the media types inferred from the parsers on this resource.
+ *
* <p>
* There is no annotation equivalent to this method call.
*
@@ -849,8 +915,10 @@ public class RestConfig implements ServletConfig {
/**
* Specifies the list of supported <code>Accept</code> media types for this resource.
+ *
* <p>
* This overrides the media types inferred from the parsers on this resource.
+ *
* <p>
* There is no annotation equivalent to this method call.
*
@@ -864,8 +932,10 @@ public class RestConfig implements ServletConfig {
/**
* Specifies the list of supported <code>Content-Type</code> media types for this resource.
+ *
* <p>
* This overrides the media types inferred from the serializers on this resource.
+ *
* <p>
* There is no annotation equivalent to this method call.
*
@@ -881,8 +951,10 @@ public class RestConfig implements ServletConfig {
/**
* Specifies the list of supported <code>Content-Type</code> media types for this resource.
+ *
* <p>
* This overrides the media types inferred from the serializers on this resource.
+ *
* <p>
* There is no annotation equivalent to this method call.
*
@@ -896,8 +968,10 @@ public class RestConfig implements ServletConfig {
/**
* Specifies the stylesheets that make up the contents of the page <js>"/resource-path/styles.css"</js>.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#stylesheet() @RestResource.stylesheet()} annotation.
+ *
* <p>
* The object types can be any of the following:
* <ul>
@@ -907,6 +981,8 @@ public class RestConfig implements ServletConfig {
* <li>{@link CharSequence}
* <li><code><jk>byte</jk>[]</code>
* </ul>
+ *
+ * <p>
* The contents of all these stylesheets will be aggregated into a single page in the order they are specified in
* this list.
*
@@ -920,15 +996,18 @@ public class RestConfig implements ServletConfig {
/**
* Specifies the stylesheet that make up the contents of the page <js>"/resource-path/styles.css"</js>.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#stylesheet() @RestResource.stylesheet()} annotation.
+ *
* <p>
* Use this method to specify a resource located in the classpath.
* This call uses the {@link Class#getResourceAsStream(String)} method to retrieve the stylesheet contents.
*
* @param resourceClass The resource class used to resolve the resource stream.
- * @param resourcePath The path passed to the {@link Class#getResourceAsStream(String)} method.
- * Can also be a path starting with <js>"file://"</js> denoting a location to pull from the file system.
+ * @param resourcePath
+ * The path passed to the {@link Class#getResourceAsStream(String)} method.
+ * Can also be a path starting with <js>"file://"</js> denoting a location to pull from the file system.
* @return This object (for method chaining).
*/
public RestConfig setStyleSheet(Class<?> resourceClass, String resourcePath) {
@@ -939,6 +1018,7 @@ public class RestConfig implements ServletConfig {
/**
* Adds to the stylesheet that make up the contents of the page <js>"/resource-path/styles.css"</js>.
+ *
* <p>
* Same as {@link #setStyleSheet(Object...)} except appends to the existing list instead of replacing.
*
@@ -954,6 +1034,7 @@ public class RestConfig implements ServletConfig {
/**
* Adds to the stylesheet that make up the contents of the page <js>"/resource-path/styles.css"</js>.
+ *
* <p>
* Same as {@link #setStyleSheet(Class,String)} except appends to the existing list instead of replacing.
*
@@ -970,8 +1051,10 @@ public class RestConfig implements ServletConfig {
/**
* Specifies the icon contents that make up the contents of the page <js>"/resource-path/favicon.ico"</js>.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#favicon() @RestResource.favicon()} annotation.
+ *
* <p>
* The object type can be any of the following:
* <ul>
@@ -990,15 +1073,18 @@ public class RestConfig implements ServletConfig {
/**
* Specifies the icon contents that make up the contents of the page <js>"/resource-path/favicon.ico"</js>.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#favicon() @RestResource.favicon()} annotation.
+ *
* <p>
* Use this method to specify a resource located in the classpath.
* This call uses the {@link Class#getResourceAsStream(String)} method to retrieve the stylesheet contents.
*
* @param resourceClass The resource class used to resolve the resource stream.
- * @param resourcePath The path passed to the {@link Class#getResourceAsStream(String)} method.
- * Can also be a path starting with <js>"file://"</js> denoting a location to pull from the file system.
+ * @param resourcePath
+ * The path passed to the {@link Class#getResourceAsStream(String)} method.
+ * Can also be a path starting with <js>"file://"</js> denoting a location to pull from the file system.
* @return This object (for method chaining).
*/
public RestConfig setFavIcon(Class<?> resourceClass, String resourcePath) {
@@ -1008,17 +1094,20 @@ public class RestConfig implements ServletConfig {
/**
* Appends to the static files resource map.
+ *
* <p>
* Use this method to specify resources located in the classpath to be served up as static files.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#staticFiles() @RestResource.staticFiles()}
* annotation.
*
* @param resourceClass The resource class used to resolve the resource streams.
- * @param staticFilesString A JSON string denoting a map of child URLs to classpath subdirectories.
- * For example, if this string is <js>"{htdocs:'docs'}"</js> with class <code>com.foo.MyResource</code>,
- * then URLs of the form <js>"/resource-path/htdocs/..."</js> will resolve to files located in the
- * <code>com.foo.docs</code> package.
+ * @param staticFilesString
+ * A JSON string denoting a map of child URLs to classpath subdirectories.
+ * For example, if this string is <js>"{htdocs:'docs'}"</js> with class <code>com.foo.MyResource</code>,
+ * then URLs of the form <js>"/resource-path/htdocs/..."</js> will resolve to files located in the
+ * <code>com.foo.docs</code> package.
* @return This object (for method chaining).
*/
public RestConfig addStaticFiles(Class<?> resourceClass, String staticFilesString) {
@@ -1030,10 +1119,12 @@ public class RestConfig implements ServletConfig {
/**
* Overrides the default REST resource resolver.
+ *
* <p>
* The resource resolver is used to resolve instances from {@link Class} objects defined in the
* {@link RestResource#children()} annotation.
* The default value is the base class {@link RestResourceResolver}.
+ *
* <p>
* This is the programmatic equivalent to the
* {@link RestResource#resourceResolver() @RestResource.resourceResolver()} annotation.
@@ -1048,6 +1139,7 @@ public class RestConfig implements ServletConfig {
/**
* Overrides the default REST resource resolver.
+ *
* <p>
* Same as {@link #setResourceResolver(Class)} except allows you to specify an instance instead of a class.
*
@@ -1061,6 +1153,7 @@ public class RestConfig implements ServletConfig {
/**
* Sets the URL path of the resource <js>"/foobar"</js>.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#path() @RestResource.path()} annotation.
*
@@ -1076,6 +1169,7 @@ public class RestConfig implements ServletConfig {
/**
* Sets name of the header used to denote the client version on HTTP requests.
+ *
* <p>
* This is the programmatic equivalent to the
* {@link RestResource#clientVersionHeader() @RestResource.clientVersionHeader()} annotation.
@@ -1090,11 +1184,14 @@ public class RestConfig implements ServletConfig {
/**
* 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>
@@ -1104,11 +1201,13 @@ public class RestConfig implements ServletConfig {
* <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
@@ -1116,6 +1215,7 @@ public class RestConfig implements ServletConfig {
* 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.
*
@@ -1129,11 +1229,14 @@ public class RestConfig implements ServletConfig {
/**
* 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>
@@ -1145,11 +1248,13 @@ public class RestConfig implements ServletConfig {
* <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
@@ -1157,6 +1262,7 @@ public class RestConfig implements ServletConfig {
* 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.
*
@@ -1170,14 +1276,19 @@ public class RestConfig implements ServletConfig {
/**
* 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.
*
@@ -1191,18 +1302,24 @@ public class RestConfig implements ServletConfig {
/**
* 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(String)} and {@link #setHtmlDescription(String)} 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.
*
@@ -1216,17 +1333,23 @@ public class RestConfig implements ServletConfig {
/**
* 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.
*
@@ -1240,18 +1363,25 @@ public class RestConfig implements ServletConfig {
/**
* 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(String)} 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.
*
@@ -1265,14 +1395,19 @@ public class RestConfig implements ServletConfig {
/**
* 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.
*
@@ -1286,14 +1421,19 @@ public class RestConfig implements ServletConfig {
/**
* 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.
*
@@ -1307,12 +1447,16 @@ public class RestConfig implements ServletConfig {
/**
* 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.
*
@@ -1326,15 +1470,20 @@ public class RestConfig implements ServletConfig {
/**
* 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.
*
@@ -1348,6 +1497,7 @@ public class RestConfig implements ServletConfig {
/**
* 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.
*
@@ -1361,6 +1511,7 @@ public class RestConfig implements ServletConfig {
/**
* 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.
@@ -1375,10 +1526,11 @@ public class RestConfig implements ServletConfig {
/**
* 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.
+ * 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.
*
@@ -1392,9 +1544,11 @@ public class RestConfig implements ServletConfig {
/**
* 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.
*
@@ -1409,6 +1563,7 @@ public class RestConfig implements ServletConfig {
/**
* Defines widgets that can be used in conjunction with string variables of the form <js>"$W{name}"</js>to quickly
* generate arbitrary replacement text.
+ *
* <p>
* Widgets are inherited from parent to child, but can be overridden by reusing the widget name.
*
@@ -1423,6 +1578,7 @@ public class RestConfig implements ServletConfig {
/**
* Overrides the logger for the resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#logger() @RestResource.logger()} annotation.
*
@@ -1436,6 +1592,7 @@ public class RestConfig implements ServletConfig {
/**
* Overrides the logger for the resource.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#logger() @RestResource.logger()} annotation.
*
@@ -1449,9 +1606,11 @@ public class RestConfig implements ServletConfig {
/**
* Overrides the call handler for the resource.
+ *
* <p>
* The call handler is the object that handles execution of REST HTTP calls.
* Subclasses can be created that customize the behavior of how REST calls are handled.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#callHandler() @RestResource.callHandler()}
* annotation.
@@ -1466,9 +1625,11 @@ public class RestConfig implements ServletConfig {
/**
* Overrides the call handler for the resource.
+ *
* <p>
* The call handler is the object that handles execution of REST HTTP calls.
* Subclasses can be created that customize the behavior of how REST calls are handled.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#callHandler() @RestResource.callHandler()}
* annotation.
@@ -1483,9 +1644,11 @@ public class RestConfig implements ServletConfig {
/**
* Overrides the info provider for the resource.
+ *
* <p>
* The info provider provides all the various information about a resource such as the Swagger documentation.
* Subclasses can be created that customize the information.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#infoProvider() @RestResource.infoProvider()}
* annotation.
@@ -1500,9 +1663,11 @@ public class RestConfig implements ServletConfig {
/**
* Overrides the info provider for the resource.
+ *
* <p>
* The info provider provides all the various information about a resource such as the Swagger documentation.
* Subclasses can be created that customize the information.
+ *
* <p>
* This is the programmatic equivalent to the {@link RestResource#infoProvider() @RestResource.infoProvider()}
* annotation.
@@ -1531,14 +1696,17 @@ public class RestConfig implements ServletConfig {
/**
* Returns the external configuration file for this resource.
+ *
* <p>
* The configuration file location is determined via the {@link RestResource#config() @RestResource.config()}
* annotation on the resource.
+ *
* <p>
* The config file can be programmatically overridden by adding the following method to your resource:
* <p class='bcode'>
* <jk>public</jk> ConfigFile createConfigFile(ServletConfig servletConfig) <jk>throws</jk> ServletException;
* </p>
+ *
* <p>
* If a config file is not set up, then an empty config file will be returned that is not backed by any file.
*
@@ -1550,13 +1718,16 @@ public class RestConfig implements ServletConfig {
/**
* Returns the configuration properties for this resource.
+ *
* <p>
* The configuration properties are determined via the {@link RestResource#properties()} annotation on the resource.
+ *
* <p>
* The configuration properties can be augmented programmatically by adding the following method to your resource:
* <p class='bcode'>
* <jk>public</jk> ObjectMap createProperties(ServletConfig servletConfig) <jk>throws</jk> ServletException;
* </p>
+ *
* <p>
* These properties can be modified during servlet initialization.
* However, any modifications made after {@link RestServlet#init(RestConfig)} has been called will have no effect.
@@ -1569,6 +1740,7 @@ public class RestConfig implements ServletConfig {
/**
* Creates the variable resolver for this resource.
+ *
* <p>
* The variable resolver returned by this method can resolve the following variables:
* <ul>
@@ -1578,6 +1750,7 @@ public class RestConfig implements ServletConfig {
* <li>{@link IfVar}
* <li>{@link SwitchVar}
* </ul>
+ *
* <p>
* Note that the variables supported here are only a subset of those returned by
* {@link RestRequest#getVarResolverSession()}.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestContext.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestContext.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestContext.java
index 99b3335..bb6e970 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestContext.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestContext.java
@@ -50,6 +50,7 @@ import org.apache.juneau.utils.*;
/**
* Contains all the configuration on a REST resource and the entry points for handling REST calls.
+ *
* <p>
* See {@link PropertyStore} for more information about context properties.
*/
@@ -57,20 +58,24 @@ public final class RestContext extends Context {
/**
* <b>Configuration property:</b> Enable header URL parameters.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"RestServlet.allowHeaderParams"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* When enabled, headers such as <js>"Accept"</js> and <js>"Content-Type"</js> to be passed in as URL query
* parameters.
* For example: <js>"?Accept=text/json&Content-Type=text/json"</js>
+ *
* <p>
* Parameter names are case-insensitive.
+ *
* <p>
* Useful for debugging REST interface using only a browser.
+ *
* <p>
* Applicable to servlet class only.
*/
@@ -78,27 +83,32 @@ public final class RestContext extends Context {
/**
* <b>Configuration property:</b> Enable <js>"method"</js> URL parameter for specific HTTP methods.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"RestServlet.allowMethodParam"</js>
* <li><b>Data type:</b> <code>String</code>
* <li><b>Default:</b> <js>""</js>
* </ul>
+ *
* <p>
* When specified, the HTTP method can be overridden by passing in a <js>"method"</js> URL parameter on a regular
* GET request.
* For example: <js>"?method=OPTIONS"</js>
+ *
* <p>
* Format is a comma-delimited list of HTTP method names that can be passed in as a method parameter.
* Parameter name is case-insensitive.
* Use "*" to represent all methods.
* For backwards compatibility, "true" also means "*".
+ *
* <p>
* Note that per the <a class="doclink"
* href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html">HTTP specification</a>, special care should
* be taken when allowing non-safe (POST, PUT, DELETE) methods to be invoked through GET requests.
+ *
* <p>
* Applicable to servlet class only.
+ *
* <p>
* Example: <js>"HEAD,OPTIONS"</js>
*/
@@ -106,20 +116,24 @@ public final class RestContext extends Context {
/**
* <b>Configuration property:</b> Enable <js>"body"</js> URL parameter.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"RestServlet.allowBodyParam"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* When enabled, the HTTP body content on PUT and POST requests can be passed in as text using the <js>"body"</js>
* URL parameter.
* For example: <js>"?body={name:'John%20Smith',age:45}"</js>
+ *
* <p>
* Parameter name is case-insensitive.
+ *
* <p>
* Useful for debugging PUT and POST methods using only a browser.
+ *
* <p>
* Applicable to servlet class only.
*/
@@ -127,17 +141,20 @@ public final class RestContext extends Context {
/**
* <b>Configuration property:</b> Render stack traces.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"RestServlet.renderResponseStackTraces"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* </ul>
+ *
* <p>
* Render stack traces in HTTP response bodies when errors occur.
+ *
* <p>
* When enabled, Java stack traces will be rendered in the output response.
* Useful for debugging, although allowing stack traces to be rendered may cause security concerns.
+ *
* <p>
* Applicable to servlet class only.
*/
@@ -145,15 +162,17 @@ public final class RestContext extends Context {
/**
* <b>Configuration property:</b> Use stack trace hashes.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"RestServlet.useStackTraceHashes"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* When enabled, the number of times an exception has occurred will be determined based on stack trace hashsums,
* made available through the {@link RestException#getOccurrence()} method.
+ *
* <p>
* Applicable to servlet class only.
*/
@@ -161,14 +180,16 @@ public final class RestContext extends Context {
/**
* <b>Configuration property:</b> Default character encoding.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"RestServlet.defaultCharset"</js>
* <li><b>Data type:</b> <code>String</code>
* <li><b>Default:</b> <js>"utf-8"</js>
* </ul>
+ *
* <p>
* The default character encoding for the request and response if not specified on the request.
+ *
* <p>
* Applicable to servlet class and methods.
*/
@@ -176,7 +197,7 @@ public final class RestContext extends Context {
/**
* <b>Configuration property:</b> Expected format of request parameters.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"RestServlet.paramFormat"</js>
* <li><b>Data type:</b> <code>String</code>
@@ -194,12 +215,15 @@ public final class RestContext extends Context {
* <br>Only POJOs directly convertible from <l>Strings</l> can be represented in parameters when using this
* mode.
* </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.
+ *
* <p>
* The format can also be specified per-parameter using the {@link FormData#format() @FormData.format()} and
* {@link Query#format() @Query.format()} annotations.
+ *
* <p>
* Applicable to servlet class and methods.
*/
@@ -212,9 +236,11 @@ public final class RestContext extends Context {
/**
* The request servlet path.
+ *
* <p>
* Automatically added to properties returned by {@link SerializerSession#getProperty(String)} and
* {@link ParserSession#getProperty(String)}.
+ *
* <p>
* Equivalent to the value returned by {@link RestRequest#getServletPath()}
*/
@@ -222,6 +248,7 @@ public final class RestContext extends Context {
/**
* The request servlet URI.
+ *
* <p>
* Equivalent to the value returned by {@link UriContext#getRootRelativeServletPath()}
*/
@@ -229,9 +256,11 @@ public final class RestContext extends Context {
/**
* The request URI path info.
+ *
* <p>
* Automatically added to properties returned by {@link SerializerSession#getProperty(String)} and
* {@link ParserSession#getProperty(String)}.
+ *
* <p>
* Equivalent to the value returned by {@link RestRequest#getPathInfo()}
*/
@@ -239,9 +268,11 @@ public final class RestContext extends Context {
/**
* The request URI.
+ *
* <p>
* Automatically added to properties returned by {@link SerializerSession#getProperty(String)} and
* {@link ParserSession#getProperty(String)}.
+ *
* <p>
* Equivalent to the value returned by {@link RestRequest#getRequestURI()}
*/
@@ -249,9 +280,11 @@ public final class RestContext extends Context {
/**
* The request method.
+ *
* <p>
* Automatically added to properties returned by {@link SerializerSession#getProperty(String)} and
* {@link ParserSession#getProperty(String)}.
+ *
* <p>
* Equivalent to the value returned by {@link RestRequest#getMethod()}
*/
@@ -259,9 +292,11 @@ public final class RestContext extends Context {
/**
* The localized servlet title.
+ *
* <p>
* Automatically added to properties returned by {@link SerializerSession#getProperty(String)} and
* {@link ParserSession#getProperty(String)}.
+ *
* <p>
* Equivalent to the value returned by {@link RestRequest#getServletTitle()}
*/
@@ -269,9 +304,11 @@ public final class RestContext extends Context {
/**
* The localized servlet description.
+ *
* <p>
* Automatically added to properties returned by {@link SerializerSession#getProperty(String)} and
* {@link ParserSession#getProperty(String)}.
+ *
* <p>
* Equivalent to the value returned by {@link RestRequest#getServletDescription()}
*/
@@ -279,9 +316,11 @@ public final class RestContext extends Context {
/**
* The localized method summary.
+ *
* <p>
* Automatically added to properties returned by {@link SerializerSession#getProperty(String)} and
* {@link ParserSession#getProperty(String)}.
+ *
* <p>
* Equivalent to the value returned by {@link RestRequest#getMethodSummary()}
*/
@@ -289,9 +328,11 @@ public final class RestContext extends Context {
/**
* The localized method description.
+ *
* <p>
* Automatically added to properties returned by {@link SerializerSession#getProperty(String)} and
* {@link ParserSession#getProperty(String)}.
+ *
* <p>
* Equivalent to the value returned by {@link RestRequest#getMethodDescription()}
*/
@@ -779,6 +820,7 @@ public final class RestContext extends Context {
/**
* Returns the variable resolver for this servlet.
+ *
* <p>
* Variable resolvers are used to replace variables in property values.
*
@@ -797,9 +839,9 @@ public final class RestContext extends Context {
* )
* <jk>public class</jk> MyRestResource <jk>extends</jk> RestServletDefault {
* </p>
+ *
* <p>
* A typical usage pattern is using variables for resolving URL links when rendering HTML:
- * </p>
* <p class='bcode'>
* <ja>@RestMethod</ja>(
* name=<js>"GET"</js>, path=<js>"/{name}/*"</js>,
@@ -812,6 +854,7 @@ public final class RestContext extends Context {
* )
* <jk>public</jk> LoggerEntry getLogger(RestRequest req, <ja>@Path</ja> String name) <jk>throws</jk> Exception {
* </p>
+ *
* <p>
* Calls to <code>req.getProperties().getString(<js>"key"</js>)</code> returns strings with variables resolved.
*
@@ -823,6 +866,7 @@ public final class RestContext extends Context {
/**
* Returns the config file associated with this servlet.
+ *
* <p>
* The config file is identified via one of the following:
* <ul>
@@ -838,6 +882,7 @@ public final class RestContext extends Context {
/**
* Resolve a static resource file.
+ *
* <p>
* The location of static resources are defined via one of the following:
* <ul>
@@ -883,8 +928,10 @@ public final class RestContext extends Context {
/**
* Same as {@link Class#getResourceAsStream(String)} except if it doesn't find the resource on this class, searches
* up the parent hierarchy chain.
+ *
* <p>
* If the resource cannot be found in the classpath, then an attempt is made to look in the JVM working directory.
+ *
* <p>
* If the <code>locale</code> is specified, then we look for resources whose name matches that locale.
* For example, if looking for the resource <js>"MyResource.txt"</js> for the Japanese locale, we will look for
@@ -947,6 +994,7 @@ public final class RestContext extends Context {
/**
* Reads the input stream from {@link #getResource(String, Locale)} and parses it into a POJO using the parser
* matched by the specified media type.
+ *
* <p>
* Useful if you want to load predefined POJOs from JSON files in your classpath.
*
@@ -982,8 +1030,10 @@ public final class RestContext extends Context {
/**
* Returns the path for this resource as defined by the {@link RestResource#path()} annotation or
* {@link RestConfig#setPath(String)} method concatenated with those on all parent classes.
+ *
* <p>
* If path is not specified, returns <js>"/"</js>.
+ *
* <p>
* Path always starts with <js>"/"</js>.
*
@@ -995,6 +1045,7 @@ public final class RestContext extends Context {
/**
* The HTML page title.
+ *
* <p>
* Defined by the {@link HtmlDoc#title()} annotation or {@link RestConfig#setHtmlTitle(String)} method.
*
@@ -1006,6 +1057,7 @@ public final class RestContext extends Context {
/**
* The HTML page description.
+ *
* <p>
* Defined by the {@link HtmlDoc#description()} annotation or {@link RestConfig#setHtmlDescription(String)} method.
*
@@ -1017,6 +1069,7 @@ public final class RestContext extends Context {
/**
* The HTML page branding.
+ *
* <p>
* Defined by the {@link HtmlDoc#branding()} annotation or {@link RestConfig#setHtmlBranding(String)} method.
*
@@ -1028,6 +1081,7 @@ public final class RestContext extends Context {
/**
* The HTML page header contents.
+ *
* <p>
* Defined by the {@link HtmlDoc#header()} annotation or {@link RestConfig#setHtmlHeader(String)} method.
*
@@ -1039,6 +1093,7 @@ public final class RestContext extends Context {
/**
* The HTML page nav section links.
+ *
* <p>
* Defined by the {@link HtmlDoc#links()} annotation or {@link RestConfig#setHtmlLinks(String)} method.
*
@@ -1050,6 +1105,7 @@ public final class RestContext extends Context {
/**
* The HTML page nav section contents.
+ *
* <p>
* Defined by the {@link HtmlDoc#nav()} annotation or {@link RestConfig#setHtmlNav(String)} method.
*
@@ -1061,6 +1117,7 @@ public final class RestContext extends Context {
/**
* The HTML page aside section contents.
+ *
* <p>
* Defined by the {@link HtmlDoc#aside()} annotation or {@link RestConfig#setHtmlAside(String)} method.
*
@@ -1072,6 +1129,7 @@ public final class RestContext extends Context {
/**
* The HTML page footer section contents.
+ *
* <p>
* Defined by the {@link HtmlDoc#footer()} annotation or {@link RestConfig#setHtmlFooter(String)} method.
*
@@ -1083,6 +1141,7 @@ public final class RestContext extends Context {
/**
* The HTML page CSS URL.
+ *
* <p>
* Defined by the {@link HtmlDoc#cssUrl()} annotation or {@link RestConfig#setHtmlCssUrl(String)} method.
*
@@ -1094,6 +1153,7 @@ public final class RestContext extends Context {
/**
* The HTML page CSS contents.
+ *
* <p>
* Defined by the {@link HtmlDoc#css()} annotation or {@link RestConfig#setHtmlCss(String)} method.
*
@@ -1105,6 +1165,7 @@ public final class RestContext extends Context {
/**
* The HTML page nowrap setting.
+ *
* <p>
* Defined by the {@link HtmlDoc#nowrap()} annotation or {@link RestConfig#setHtmlNoWrap(boolean)} method.
*
@@ -1116,6 +1177,7 @@ public final class RestContext extends Context {
/**
* The HTML page template.
+ *
* <p>
* Defined by the {@link HtmlDoc#template()} annotation or {@link RestConfig#setHtmlTemplate(Class)} method.
*
@@ -1127,6 +1189,7 @@ public final class RestContext extends Context {
/**
* The HTML page no-results message.
+ *
* <p>
* Defined by the {@link HtmlDoc#noResultsMessage()} annotation or {@link RestConfig#setHtmlNoResultsMessage(String)}
* method.
@@ -1139,6 +1202,7 @@ public final class RestContext extends Context {
/**
* The widgets used for resolving <js>"$W{...}"<js> variables.
+ *
* <p>
* Defined by the {@link RestResource#widgets()} annotation or {@link RestConfig#addWidget(Class)} method.
*
@@ -1150,6 +1214,7 @@ public final class RestContext extends Context {
/**
* Returns the logger to use for this resource.
+ *
* <p>
* The logger for a resource is defined via one of the following:
* <ul>
@@ -1165,6 +1230,7 @@ public final class RestContext extends Context {
/**
* Returns the resource bundle used by this resource.
+ *
* <p>
* The resource bundle is defined via one of the following:
* <ul>
@@ -1179,6 +1245,7 @@ public final class RestContext extends Context {
/**
* Returns the REST information provider used by this resource.
+ *
* <p>
* The information provider is defined via one of the following:
* <ul>
@@ -1194,6 +1261,7 @@ public final class RestContext extends Context {
/**
* Returns the REST call handler used by this resource.
+ *
* <p>
* The call handler is defined via one of the following:
* <ul>
@@ -1218,6 +1286,7 @@ public final class RestContext extends Context {
/**
* Returns the resource object.
+ *
* <p>
* This is the instance of the class annotated with the {@link RestResource @RestResource} annotation, usually
* an instance of {@link RestServlet}.
@@ -1231,8 +1300,9 @@ public final class RestContext extends Context {
/**
* Returns the resource object as a {@link RestServlet}.
*
- * @return The resource object cast to {@link RestServlet}, or
- * <jk>null</jk> if the resource doesn't subclass from {@link RestServlet}
+ * @return
+ * The resource object cast to {@link RestServlet}, or <jk>null</jk> if the resource doesn't subclass from
+ * {@link RestServlet}
*/
public RestServlet getRestServlet() {
return resource instanceof RestServlet ? (RestServlet)resource : null;
@@ -1250,6 +1320,7 @@ public final class RestContext extends Context {
/**
* Returns the parent resource context (if this resource was initialized from a parent).
+ *
* <p>
* From this object, you can get access to the parent resource class itself using {@link #getResource()} or
* {@link #getRestServlet()}
@@ -1271,6 +1342,7 @@ public final class RestContext extends Context {
/**
* Returns the class-level properties associated with this servlet.
+ *
* <p>
* Properties at the class level are defined via one of the following:
* <ul>
@@ -1292,6 +1364,7 @@ public final class RestContext extends Context {
/**
* Returns the serializers registered with this resource.
+ *
* <p>
* Serializers at the class level are defined via one of the following:
* <ul>
@@ -1307,6 +1380,7 @@ public final class RestContext extends Context {
/**
* Returns the parsers registered with this resource.
+ *
* <p>
* Parsers at the class level are defined via one of the following:
* <ul>
@@ -1333,8 +1407,9 @@ public final class RestContext extends Context {
/**
* Returns the child resources associated with this servlet.
*
- * @return An unmodifiable map of child resources.
- * Keys are the {@link RestResource#path() @RestResource.path()} annotation defined on the child resource.
+ * @return
+ * An unmodifiable map of child resources.
+ * Keys are the {@link RestResource#path() @RestResource.path()} annotation defined on the child resource.
*/
public Map<String,RestContext> getChildResources() {
return Collections.unmodifiableMap(childResources);
@@ -1344,8 +1419,9 @@ public final class RestContext extends Context {
* Returns the number of times this exception was thrown based on a hash of its stacktrace.
*
* @param e The exception to check.
- * @return The number of times this exception was thrown, or <code>0</code> if <code>stackTraceHashes</code>
- * setting is not enabled.
+ * @return
+ * The number of times this exception was thrown, or <code>0</code> if <code>stackTraceHashes</code>
+ * setting is not enabled.
*/
protected int getStackTraceOccurrence(Throwable e) {
if (! useStackTraceHashes)
@@ -1402,8 +1478,10 @@ public final class RestContext extends Context {
/**
* Returns the name of the client version header name used by this resource.
+ *
* <p>
* The client version header is the name of the HTTP header on requests that identify a client version.
+ *
* <p>
* The client version header is defined via one of the following:
* <ul>
@@ -1429,6 +1507,7 @@ public final class RestContext extends Context {
/**
* Returns the bean filters associated with this resource.
+ *
* <p>
* Bean filters at the class level are defined via one of the following:
* <ul>
@@ -1444,6 +1523,7 @@ public final class RestContext extends Context {
/**
* Returns the POJO swaps associated with this resource.
+ *
* <p>
* POJO swaps at the class level are defined via one of the following:
* <ul>
@@ -1558,8 +1638,10 @@ public final class RestContext extends Context {
/**
* Returns the encoders associated with this resource.
+ *
* <p>
* Encoders are used to provide various types of encoding such as <code>gzip</code> encoding.
+ *
* <p>
* Encoders at the class level are defined via one of the following:
* <ul>
@@ -1576,6 +1658,7 @@ public final class RestContext extends Context {
/**
* Returns the explicit list of supported accept types for this resource.
+ *
* <p>
* By default, this is simply the list of accept types supported by the registered parsers, but
* can be overridden via the {@link RestConfig#setSupportedAcceptTypes(MediaType...)}/{@link RestConfig#setSupportedAcceptTypes(String...)}
@@ -1589,6 +1672,7 @@ public final class RestContext extends Context {
/**
* Returns the explicit list of supported content types for this resource.
+ *
* <p>
* By default, this is simply the list of content types supported by the registered serializers, but can be
* overridden via the {@link RestConfig#setSupportedContentTypes(MediaType...)}/{@link RestConfig#setSupportedContentTypes(String...)}
@@ -1602,8 +1686,10 @@ public final class RestContext extends Context {
/**
* Returns the default request headers for this resource.
+ *
* <p>
* These are headers automatically added to requests if not present.
+ *
* <p>
* Default request headers are defined via one of the following:
* <ul>
@@ -1619,8 +1705,10 @@ public final class RestContext extends Context {
/**
* Returns the default response headers for this resource.
+ *
* <p>
* These are headers automatically added to responses if not otherwise specified during the request.
+ *
* <p>
* Default response headers are defined via one of the following:
* <ul>
@@ -1637,8 +1725,10 @@ public final class RestContext extends Context {
/**
* Returns the converters associated with this resource at the class level.
+ *
* <p>
* Converters are used to 'convert' POJOs from one form to another before being passed of to the response handlers.
+ *
* <p>
* Converters at the class level are defined via one of the following:
* <ul>
@@ -1654,8 +1744,10 @@ public final class RestContext extends Context {
/**
* Returns the guards associated with this resource at the class level.
+ *
* <p>
* Guards are used to restrict access to resources.
+ *
* <p>
* Guards at the class level are defined via one of the following:
* <ul>
@@ -1671,8 +1763,10 @@ public final class RestContext extends Context {
/**
* Returns the response handlers associated with this resource.
+ *
* <p>
* Response handlers are used to convert POJOs returned by REST Java methods into actual HTTP responses.
+ *
* <p>
* Response handlers are defined via one of the following:
* <ul>
@@ -1689,6 +1783,7 @@ public final class RestContext extends Context {
/**
* Returns the media type for the specified file name.
+ *
* <p>
* The list of MIME-type mappings can be augmented through the {@link RestConfig#addMimeTypes(String...)} method.
* See that method for a description of predefined MIME-type mappings.
@@ -1702,8 +1797,10 @@ public final class RestContext extends Context {
/**
* Returns the favicon of the resource.
+ *
* <p>
* This is the icon served up under <js>"/favicon.ico"</jk> recognized by browsers.
+ *
* <p>
* The favicon is defined via one of the following:
* <ul>
@@ -1719,8 +1816,10 @@ public final class RestContext extends Context {
/**
* Returns the stylesheet for use in the HTML views of the resource.
+ *
* <p>
* This is the contents of the page served up under <js>"/styles.css"</jk>.
+ *
* <p>
* The stylesheet is defined via one of the following:
* <ul>
@@ -1736,8 +1835,10 @@ public final class RestContext extends Context {
/**
* Returns <jk>true</jk> if the specified path refers to a static file.
+ *
* <p>
* Static files are files pulled from the classpath and served up directly to the browser.
+ *
* <p>
* Static files are defined via one of the following:
* <ul>
@@ -1754,6 +1855,7 @@ public final class RestContext extends Context {
/**
* Returns the REST Java methods defined in this resource.
+ *
* <p>
* These are the methods annotated with the {@link RestMethod @RestMethod} annotation.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestConverter.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestConverter.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestConverter.java
index 4f85306..c60972a 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestConverter.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestConverter.java
@@ -19,9 +19,11 @@ import org.apache.juneau.serializer.*;
/**
* REST method response converter.
+ *
* <p>
* Implements a filter mechanism for REST method calls that allows response objects to be converted to some other POJO
* after invocation of the REST method.
+ *
* <p>
* Converters are associated with REST methods through the {@link RestMethod#converters()} annotation.
*
@@ -37,20 +39,22 @@ import org.apache.juneau.serializer.*;
* }
* }
* </p>
+ *
* <p>
* Converters can also be associated at the servlet level using the {@link RestResource#converters()} annotation.
* Applying converters at the resource level is equivalent to applying converters to each resource method individually.
*
* <h6 class='topic'>How to implement</h6>
- * <p>
+ *
* Implementers should simply implement the {@link #convert(RestRequest, Object, ClassMeta)} and return back a
* 'converted' object.
* It's up to the implementer to decide what this means.
+ *
* <p>
* Converters must implement a no-args constructor.
*
* <h6 class='topic'>Predefined converters</h6>
- * <p>
+ *
* The following converters are available by default.
* <ul class='spaced-list'>
* <li>
@@ -68,8 +72,9 @@ public interface RestConverter {
*
* @param req The servlet request.
* @param res The response object set by the REST method through the {@link RestResponse#setOutput(Object)} method.
- * @param cm The {@link ClassMeta} on the object from the bean context of the servlet.
- * Can be used to check if the object has any filters.
+ * @param cm
+ * The {@link ClassMeta} on the object from the bean context of the servlet.
+ * Can be used to check if the object has any filters.
* @return The converted object.
* @throws RestException Thrown if any errors occur during conversion.
* @throws SerializeException
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestException.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestException.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestException.java
index a8f4f6f..03e67bf 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestException.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestException.java
@@ -21,6 +21,7 @@ import org.apache.juneau.*;
/**
* Exception thrown to trigger an error HTTP status.
+ *
* <p>
* REST methods on subclasses of {@link RestServlet} can throw this exception to trigger an HTTP status other than the
* automatically-generated <code>404</code>, <code>405</code>, and <code>500</code> statuses.
@@ -70,6 +71,8 @@ public class RestException extends FormattedRuntimeException {
/**
* Returns the root cause of this exception.
+ *
+ * <p>
* The root cause is the first exception in the init-cause parent chain that's not one of the following:
* <ul>
* <li>{@link RestException}
@@ -90,11 +93,13 @@ public class RestException extends FormattedRuntimeException {
/**
* Returns all error messages from all errors in this stack.
+ *
* <p>
- * Typically useful if you want to render all the error messages in the stack, but don't
- * want to render all the stack traces too.
+ * Typically useful if you want to render all the error messages in the stack, but don't want to render all the
+ * stack traces too.
*
- * @param scrubForXssVulnerabilities If <jk>true</jk>, replaces <js>'<'</js>, <js>'>'</js>, and <js>'&'</js> characters with spaces.
+ * @param scrubForXssVulnerabilities
+ * If <jk>true</jk>, replaces <js>'<'</js>, <js>'>'</js>, and <js>'&'</js> characters with spaces.
* @return All error messages from all errors in this stack.
*/
public String getFullStackMessage(boolean scrubForXssVulnerabilities) {
@@ -138,10 +143,12 @@ public class RestException extends FormattedRuntimeException {
/**
* Returns the number of times this exception occurred on this servlet.
+ *
* <p>
* This only gets set if {@link RestContext#REST_useStackTraceHashes} is enabled on the servlet.
*
- * @return The occurrence number if {@link RestContext#REST_useStackTraceHashes} is enabled, or <code>0</code> otherwise.
+ * @return
+ * The occurrence number if {@link RestContext#REST_useStackTraceHashes} is enabled, or <code>0</code> otherwise.
*/
public int getOccurrence() {
return occurrence;
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestGuard.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestGuard.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestGuard.java
index f95b916..54d5f85 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestGuard.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestGuard.java
@@ -20,23 +20,27 @@ import org.apache.juneau.rest.annotation.*;
* REST method guard.
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* Implements a guard mechanism for REST method calls that allows requests to be rejected before invocation of the REST
* method.
* For example, guards can be used to ensure that only administrators can call certain methods.
+ *
* <p>
* Guards are applied to REST methods declaratively through the {@link RestResource#guards()} or
* {@link RestMethod#guards()} annotations.
+ *
* <p>
* If multiple guards are specified, ALL guards must pass in order for the request to proceed.
*
* <h6 class='topic'>How to implement</h6>
- * <p>
+ *
* Typically, guards will be used for permissions checking on the user making the request, but it can also be used for
* other purposes like pre-call validation of a request.
+ *
* <p>
* Implementers should simply throw a {@link RestException} from the {@link #guard(RestRequest, RestResponse)}
* method to abort processing on the current request.
+ *
* <p>
* Guards must implement a no-args constructor.
*
@@ -66,17 +70,20 @@ public abstract class RestGuard {
/**
* Checks the current HTTP request and throws a {@link RestException} if the guard does not permit the request.
+ *
* <p>
* By default, throws an <jsf>SC_FORBIDDEN</jsf> exception if {@link #isRequestAllowed(RestRequest)} returns
* <jk>false</jk>.
+ *
* <p>
* Subclasses are free to override this method to tailor the behavior of how to handle unauthorized requests.
*
* @param req The servlet request.
* @param res The servlet response.
* @throws RestException Thrown to abort processing on current request.
- * @return <jk>true</jk> if request can proceed.
- * Specify <jk>false</jk> if you're doing something like a redirection to a login page.
+ * @return
+ * <jk>true</jk> if request can proceed.
+ * Specify <jk>false</jk> if you're doing something like a redirection to a login page.
*/
public boolean guard(RestRequest req, RestResponse res) throws RestException {
if (! isRequestAllowed(req))
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-rest/src/main/java/org/apache/juneau/rest/RestInfoProvider.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestInfoProvider.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestInfoProvider.java
index b0aa412..2b506f9 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestInfoProvider.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestInfoProvider.java
@@ -28,9 +28,11 @@ import org.apache.juneau.svl.*;
/**
* Class that provides documentation and other related information about a REST resource.
+ *
* <p>
* Subclasses can override these methods to tailor how HTTP REST resources are documented.
* Subclasses MUST implement a public constructor that takes in a {@link RestContext} object.
+ *
* <p>
* RestInfoProviders are associated with servlets/resources in one of the following ways:
* <ul>
@@ -155,9 +157,11 @@ public class RestInfoProvider {
/**
* 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.
+ * 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.
*
@@ -180,11 +184,12 @@ public class RestInfoProvider {
/**
* Returns the localized summary of the specified java method on this servlet.
+ *
* <p>
* Subclasses can override this method to provide their own summary.
+ *
* <p>
* The default implementation returns the summary from the following locations (whichever matches first):
- * </p>
* <ol>
* <li>{@link RestMethod#summary() @RestMethod.summary()} annotation on the method.
* <li><ck>[ClassName].[javaMethodName].summary</ck> property in resource bundle identified by
@@ -206,11 +211,12 @@ public class RestInfoProvider {
/**
* Returns the localized description of the specified java method on this servlet.
+ *
* <p>
* Subclasses can override this method to provide their own description.
+ *
* <p>
* The default implementation returns the description from the following locations (whichever matches first):
- * </p>
* <ol>
* <li>{@link RestMethod#description() @RestMethod.description()} annotation on the method.
* <li><ck>[ClassName].[javaMethodName].description</ck> property in resource bundle identified by
@@ -232,11 +238,12 @@ public class RestInfoProvider {
/**
* Returns the localized title of this REST resource.
+ *
* <p>
* Subclasses can override this method to provide their own title.
+ *
* <p>
* The default implementation returns the description from the following locations (whichever matches first):
- * <p>
* <ol>
* <li>{@link RestResource#title() @RestResourcel.title()} annotation on this class, and then any parent classes.
* <li><ck>[ClassName].title</ck> property in resource bundle identified by
@@ -265,8 +272,10 @@ public class RestInfoProvider {
/**
* Returns the localized description of this REST resource.
+ *
* <p>
* Subclasses can override this method to provide their own description.
+ *
* <p>
* The default implementation returns the description from the following locations (whichever matches first):
* <ol>
@@ -297,8 +306,10 @@ public class RestInfoProvider {
/**
* Returns the localized contact information of this REST resource.
+ *
* <p>
* Subclasses can override this method to provide their own contact information.
+ *
* <p>
* The default implementation returns the contact information from the following locations (whichever matches first):
* <ol>
@@ -312,8 +323,8 @@ public class RestInfoProvider {
* </ol>
*
* @param req The current request.
- * @return The localized contact information of this REST resource, or <jk>null</jk> if no contact information was
- * found.
+ * @return
+ * The localized contact information of this REST resource, or <jk>null</jk> if no contact information was found.
*/
public Contact getContact(RestRequest req) {
VarResolverSession vr = req.getVarResolverSession();
@@ -335,8 +346,10 @@ public class RestInfoProvider {
/**
* Returns the localized license information of this REST resource.
+ *
* <p>
* Subclasses can override this method to provide their own license information.
+ *
* <p>
* The default implementation returns the license information from the following locations (whichever matches first):
* <ol>
@@ -350,8 +363,8 @@ public class RestInfoProvider {
* </ol>
*
* @param req The current request.
- * @return The localized contact information of this REST resource, or <jk>null</jk> if no contact information was
- * found.
+ * @return
+ * The localized contact information of this REST resource, or <jk>null</jk> if no contact information was found.
*/
public License getLicense(RestRequest req) {
VarResolverSession vr = req.getVarResolverSession();
@@ -373,8 +386,10 @@ public class RestInfoProvider {
/**
* Returns the terms-of-service information of this REST resource.
+ *
* <p>
* Subclasses can override this method to provide their own terms-of-service information.
+ *
* <p>
* The default implementation returns the terms-of-service information from the following locations (whichever
* matches first):
@@ -389,8 +404,8 @@ public class RestInfoProvider {
* </ol>
*
* @param req The current request.
- * @return The localized contact information of this REST resource, or <jk>null</jk> if no contact information was
- * found.
+ * @return
+ * The localized contact information of this REST resource, or <jk>null</jk> if no contact information was found.
*/
public String getTermsOfService(RestRequest req) {
VarResolverSession vr = req.getVarResolverSession();
@@ -407,8 +422,10 @@ public class RestInfoProvider {
/**
* Returns the version information of this REST resource.
+ *
* <p>
* Subclasses can override this method to provide their own version information.
+ *
* <p>
* The default implementation returns the version information from the following locations (whichever matches first):
* <ol>
@@ -422,8 +439,8 @@ public class RestInfoProvider {
* </ol>
*
* @param req The current request.
- * @return The localized contact information of this REST resource, or <jk>null</jk> if no contact information was
- * found.
+ * @return
+ * The localized contact information of this REST resource, or <jk>null</jk> if no contact information was found.
*/
public String getVersion(RestRequest req) {
VarResolverSession vr = req.getVarResolverSession();
@@ -440,8 +457,10 @@ public class RestInfoProvider {
/**
* Returns the version information of this REST resource.
+ *
* <p>
* Subclasses can override this method to provide their own version information.
+ *
* <p>
* The default implementation returns the version information from the following locations (whichever matches first):
* <ol>
@@ -455,8 +474,8 @@ public class RestInfoProvider {
* </ol>
*
* @param req The current request.
- * @return The localized contact information of this REST resource, or <jk>null</jk> if no contact information was
- * found.
+ * @return
+ * The localized contact information of this REST resource, or <jk>null</jk> if no contact information was found.
*/
public List<Tag> getTags(RestRequest req) {
VarResolverSession vr = req.getVarResolverSession();
@@ -478,8 +497,10 @@ public class RestInfoProvider {
/**
* Returns the version information of this REST resource.
+ *
* <p>
* Subclasses can override this method to provide their own version information.
+ *
* <p>
* The default implementation returns the version information from the following locations (whichever matches first):
* <ol>
@@ -493,8 +514,8 @@ public class RestInfoProvider {
* </ol>
*
* @param req The current request.
- * @return The localized contact information of this REST resource, or <jk>null</jk> if no contact information was
- * found.
+ * @return
+ * The localized contact information of this REST resource, or <jk>null</jk> if no contact information was found.
*/
public ExternalDocumentation getExternalDocs(RestRequest req) {
VarResolverSession vr = req.getVarResolverSession();