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();
