http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/0d913b38/juneau-rest/src/main/java/org/apache/juneau/rest/package.html ---------------------------------------------------------------------- diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/package.html b/juneau-rest/src/main/java/org/apache/juneau/rest/package.html index 7c04791..0e0940c 100644 --- a/juneau-rest/src/main/java/org/apache/juneau/rest/package.html +++ b/juneau-rest/src/main/java/org/apache/juneau/rest/package.html @@ -95,7 +95,7 @@ <li><p><a class='doclink' href='#RestServlets.Headers'>Default Headers</a></p> <li><p><a class='doclink' href='#RestServlets.Errors'>Handling Errors / Logging</a></p> <li><p><a class='doclink' href='#RestServlets.ConfigFile'>Configuration Files</a></p> - <li><p><a class='doclink' href='#RestServlets.Inheritence'>Annotation Inheritence</a></p> + <li><p><a class='doclink' href='#RestServlets.Inheritence'>Annotation Inheritance</a></p> <li><p><a class='doclink' href='#RestServlets.HttpStatusCodes'>HTTP Status Codes</a></p> <li><p><a class='doclink' href='#RestServlets.OverloadedHttpMethods'>Overloaded HTTP Methods</a></p> <li><p><a class='doclink' href='#RestServlets.BuildInParams'>Built-In Parameters</a></p> @@ -104,7 +104,7 @@ <li><p><a class='doclink' href='#RestServlets.OtherNotes'>Other Notes</a></p> </ol> <li><p><a class='doclink' href='#Osgi'>Using with OSGi</a></p> - <li><p><a class='doclink' href='#PojosConvertableFromString'>POJOs Convertable From Strings</a></p> + <li><p><a class='doclink' href='#PojosConvertableFromString'>POJOs Convertible From Strings</a></p> <li><p><a class='doclink' href='#AddressBookResource'>Address Book Resource</a></p> </ol> @@ -113,79 +113,93 @@ <h2 class='topic' onclick='toggle(this)'>1 - Introduction</h2> <div class='topic'> <p> - The <l>juneau-rest.jar</l> library allows you to quickly wrap POJOs and expose them as full-fledged REST resources served up in a servlet container using a bare-minimum amount of code. - The primary goal for Juneau was to make it as easy as possible to implement easy-to-read and self-documenting REST resources using very little code. + The <l>juneau-rest.jar</l> library allows you to quickly wrap POJOs and expose them as full-fledged REST + resources served up in a servlet container using a bare-minimum amount of code. + The primary goal for Juneau was to make it as easy as possible to implement easy-to-read and self-documenting + REST resources using very little code. </p> <p> - One of the biggest advantages of the Juneau REST framework over similar architectures is that it hides the serialization layer from the developer. - The developer can work entirely with POJOs and let the Juneau framework handle all the serialization and parsing work. - The developer need never know what the <l>Accept</l> or <l>Content-Type</l> or <l>Accept-Encoding</l> (etc...) header values are because those details are all handled by the framework. + One of the biggest advantages of the Juneau REST framework over similar architectures is that it hides the + serialization layer from the developer. + The developer can work entirely with POJOs and let the Juneau framework handle all the serialization and + parsing work. + The developer need never know what the <l>Accept</l> or <l>Content-Type</l> or <l>Accept-Encoding</l> (etc...) + header values are because those details are all handled by the framework. </p> <p> The API builds upon the existing JEE Servlet API. - The root class, {@link org.apache.juneau.rest.RestServlet} is nothing but a specialized {@link javax.servlet.http.HttpServlet}, and the - {@link org.apache.juneau.rest.RestRequest} and {@link org.apache.juneau.rest.RestResponse} classes are nothing more than specialized {@link javax.servlet.http.HttpServletRequest} and - {@link javax.servlet.http.HttpServletResponse} objects. - This allows maximum flexibility for the developer since you can let Juneau handle operations such as serialization, or you can revert - to the existing servlet APIs to do low-level processing of requests yourself. + The root class, {@link org.apache.juneau.rest.RestServlet} is nothing but a specialized + {@link javax.servlet.http.HttpServlet}, and the {@link org.apache.juneau.rest.RestRequest} and + {@link org.apache.juneau.rest.RestResponse} classes are nothing more than specialized + {@link javax.servlet.http.HttpServletRequest} and {@link javax.servlet.http.HttpServletResponse} objects. + This allows maximum flexibility for the developer since you can let Juneau handle operations such as + serialization, or you can revert to the existing servlet APIs to do low-level processing of requests yourself. It also means you need nothing more than a Servlet container such as Jetty to use the REST framework. </p> + <h6 class='topic'>Features</h6> <ul class='spaced-list'> - <li>Serializes POJOs to JSON, XML, HTML, URL-Encoding, UON, RDF/XML, N-Triple, Turtle, N3, SOAP, or Java-serialized-object based on - value of <l>Accept</l> header. <br> - No user code is required to handle these types. - <br> + <li> + Serializes POJOs to JSON, XML, HTML, URL-Encoding, UON, RDF/XML, N-Triple, Turtle, N3, SOAP, or + Java-serialized-object based on value of <l>Accept</l> header. + <br>No user code is required to handle these types. <ul> - <li>Extensible design that provides ability to override existing content type handlers, or add the ability to handle other kinds of content types. + <li>Extensible design that provides ability to override existing content type handlers, or add the + ability to handle other kinds of content types. </ul> - <br> - <li>Parses content of POST/PUT request bodies to POJOs. - <br><br> - <li>Automatic built-in ability to serialize POJO metadata to JSON+SCHEMA, XML+SCHEMA, or HTML+SCHEMA based on <l>Accept</l> header. - <br><br> - <li>Automatic negotiation of output Writer based on HTTP headers. - <br> + <li> + Parses content of POST/PUT request bodies to POJOs. + <li> + Automatic built-in ability to serialize POJO metadata to JSON+SCHEMA, XML+SCHEMA, or HTML+SCHEMA based on + <l>Accept</l> header. + <li> + Automatic negotiation of output Writer based on HTTP headers. <ul> <li>Automatic handling of <l>Accept-Charset</l> header for all character sets supported by the JVM. <li>Automatic handling of <l>Accept-Encoding</l> header with registered encoders. </ul> - <br> - <li>Automatic error handling. - <br> + <li> + Automatic error handling. <ul> <li>Automatic 401 errors (Unauthorized) on failed guards. <li>Automatic 404 errors (Not Found) on unmatched path patterns. <li>Automatic 405 errors (Method Not Implemented) on unimplemented methods. - <li>Automatic 406 errors (Not Acceptable) when no matching serializer was found to handle the <l>Accept</l> header. + <li>Automatic 406 errors (Not Acceptable) when no matching serializer was found to handle the + <l>Accept</l> header. <li>Automatic 412 errors (Precondition Failed) when all matchers failed to match. - <li>Automatic 415 errors (Unsupported Media Type) when no matching parser was found was found to handle the <l>Content-Type</l> header. + <li>Automatic 415 errors (Unsupported Media Type) when no matching parser was found was found to handle + the <l>Content-Type</l> header. <li>Automatic 500 errors on uncaught exceptions. </ul> - <br> - <li>Self-documenting REST interfaces. - <br> - <li>Various useful debugging features that make debugging using a browser extremely simple... - <br> + <li> + Self-documenting REST interfaces. + <li> + Various useful debugging features that make debugging using a browser extremely simple... <ul> <li>Ability to pass HTTP header values as URL GET parameters (e.g. <l>&Accept=text/xml</l>). - <li>Ability to pass HTTP content on PUT/POST requests as a URL GET parameter (e.g. <l>&content={foo:"bar"}</l>). - <li>Ability to simulate non-GET requests using a <l>&method</l> GET parameter (e.g. <l>&method=POST</l>). + <li>Ability to pass HTTP content on PUT/POST requests as a URL GET parameter + (e.g. <l>&content={foo:"bar"}</l>). + <li>Ability to simulate non-GET requests using a <l>&method</l> GET parameter + (e.g. <l>&method=POST</l>). <li>Ability to force <js>"text/plain"</js> on response using GET parameter <l>&plainText=true</l>. </ul> - <br> - <li>Ability to implement overloaded HTTP methods through the use of the <l>&method</l> attribute (e.g. <l>&method=FOO</l>). - <br><br> - <li>Ability to match URL patterns (e.g. <l>/foo/{fooId}/bar/{barId}</l>) against URLs (e.g. <l>/foo/123/bar/456/bing</l>). - <br><br> - <li>Ability to associate guards at the resource or method levels through annotations.<br> - Typically useful for security, but can be used for a variety of purposes. - <br><br> - <li>Ability to associate converters at the resource or method levels through annotations.<br> - Typically useful for performing conversions on input and output, such as for supporting older input and output formats. + <li> + Ability to implement overloaded HTTP methods through the use of the <l>&method</l> attribute + (e.g. <l>&method=FOO</l>). + <li> + Ability to match URL patterns (e.g. <l>/foo/{fooId}/bar/{barId}</l>) against URLs + (e.g. <l>/foo/123/bar/456/bing</l>). + <li> + Ability to associate guards at the resource or method levels through annotations. + <br>Typically useful for security, but can be used for a variety of purposes. + <li> + Ability to associate converters at the resource or method levels through annotations. + <br>Typically useful for performing conversions on input and output, such as for supporting older input and + output formats. </ul> <p> - Many of the examples in this document are pulled directly from the <l>microservice-samples-project.zip</l> project. + Many of the examples in this document are pulled directly from the <l>microservice-samples-project.zip</l> + project. </p> </div> @@ -194,7 +208,8 @@ <h2 class='topic' onclick='toggle(this)'>2 - Hello World Example</h2> <div class='topic'> <p> - A REST resource is an implementation of {@link org.apache.juneau.rest.RestServlet}, which itself is simply an extension of {@link javax.servlet.http.HttpServlet}. + A REST resource is an implementation of {@link org.apache.juneau.rest.RestServlet}, which itself is simply an + extension of {@link javax.servlet.http.HttpServlet}. </p> <p> In this example, we define a resource called <l>HelloWorldResource</l>. @@ -252,12 +267,15 @@ </p> <p> It doesn't much simpler than that. - In this case, we're simply returning a string that will be converted to any of the supported languages (e.g. JSON, XML, HTML, ...). + In this case, we're simply returning a string that will be converted to any of the supported languages (e.g. + JSON, XML, HTML, ...). However, we could have returned any POJO consisting of beans, maps, collections, etc... </p> <p> - The {@link org.apache.juneau.rest.RestServletDefault} class that we're using here is a subclass of {@link org.apache.juneau.rest.RestServlet} that provides default support for a variety of content types. - Implementers can choose to use this class, or create their own subclass of {@link org.apache.juneau.rest.RestServlet} with their own specialized serializers and parsers. + The {@link org.apache.juneau.rest.RestServletDefault} class that we're using here is a subclass of + {@link org.apache.juneau.rest.RestServlet} that provides default support for a variety of content types. + Implementers can choose to use this class, or create their own subclass of + {@link org.apache.juneau.rest.RestServlet} with their own specialized serializers and parsers. </p> <p> If you were to start up this servlet and view it with a browser, you would see this: @@ -268,12 +286,15 @@ Therefore, several built-in features are provided for making it easy to do so. Specifically, we'll be using these available URL parameters... </p> - <ul class='normal'> - <li><l>&plainText=true</l> - If specified, then the <l>Content-Type</l> on the response is always <l>"text/plain"</l> regardless of the data format. - <br><br> - <li><l>&Accept=X</l> - Specify the content type of the response. - In a browser, <l>"text/html"</l> is the default content type, but this parameter can be used to override the content type on the response.<br> - Note: The behavior is identical to setting the <l>Accept</l> header on the request. + <ul class='spaced-list'> + <li> + <l>&plainText=true</l> - If specified, then the <l>Content-Type</l> on the response is always + <l>"text/plain"</l> regardless of the data format. + <li> + <l>&Accept=X</l> - Specify the content type of the response. + In a browser, <l>"text/html"</l> is the default content type, but this parameter can be used to override + the content type on the response. + <br>Note: The behavior is identical to setting the <l>Accept</l> header on the request. In fact, Juneau allows ANY HTTP request headers to be specified as URL parameters for debugging purposes. </ul> <p> @@ -285,10 +306,12 @@ It is possible to specify your own stylesheet, but the default styles will usually suffice for most purposes. </p> <p> - When accessed through a browser, the content type will default to HTML (based on the value of the <l>Accept</l> HTTP header). + When accessed through a browser, the content type will default to HTML (based on the value of the <l>Accept</l> + HTTP header). </p> <p> - Let's use the <l>&Accept</l> URL paramter to override the <l>Accept</l> HTTP header to view this servlet in other formats... + Let's use the <l>&Accept</l> URL parameter to override the <l>Accept</l> HTTP header to view this servlet + in other formats... </p> <p> In the case of <l>JSON</l>, we're serialize a single string, so it gets rendered as a JSON fragment.... @@ -309,7 +332,7 @@ The OPTIONS page is a serialized Swagger DTO bean populated by introspection of the class itself combined with labels in the messages properties file and annotations. It's composed of a POJO that gets serialized just like any other POJO. - Therefore, the POJO can be searialized to any of the supported languages, like Swagger JSON. + Therefore, the POJO can be serialized to any of the supported languages, like Swagger JSON. </p> <img class='bordered' src="doc-files/HelloWorldResourceOptionsJson.png"> </div> @@ -322,81 +345,107 @@ The class hierarchy for the REST servlet class is shown below: </p> <ul class='doctree'> - <li class='jac'>{@link javax.servlet.http.HttpServlet javax.servlet.http.HttpServlet} - <ul> - <li class='jac'>{@link org.apache.juneau.rest.RestServlet org.apache.juneau.rest.RestServlet} - <br>Contains all the main logic. + <li class='jac'> + {@link javax.servlet.http.HttpServlet javax.servlet.http.HttpServlet} <ul> - <li class='jac'>{@link org.apache.juneau.rest.RestServletDefault org.apache.juneau.rest.RestServletDefault} - <br>Provides a default set of serializers, parsers, options page, stylesheet, and other common settings. - <br><b>Developers will typically subclass this when creating REST resources in JEE environments.</b> - <ul> - <li class='jac'>{@link org.apache.juneau.microservice.Resource org.apache.juneau.microservice.Resource} - <br>Subclass intented to be used in REST microservices. - <br><b>Developers will typically subclass this when creating microservices.</b> - <li class='jac'>{@link org.apache.juneau.rest.RestServletGroupDefault org.apache.juneau.rest.RestServletGroupDefault} - <br>A default implementation for "router" pages. + <li class='jac'> + {@link org.apache.juneau.rest.RestServlet org.apache.juneau.rest.RestServlet} + <br>Contains all the main logic. <ul> - <li class='jac'>{@link org.apache.juneau.microservice.ResourceGroup org.apache.juneau.microservice.ResourceGroup} - <br>Subclass intented to be used in REST microservices. + <li class='jac'> + {@link org.apache.juneau.rest.RestServletDefault org.apache.juneau.rest.RestServletDefault} + <br>Provides a default set of serializers, parsers, options page, stylesheet, and other common settings. + <br><b>Developers will typically subclass this when creating REST resources in JEE environments.</b> + <ul> + <li class='jac'> + {@link org.apache.juneau.microservice.Resource org.apache.juneau.microservice.Resource} + <br>Subclass intended to be used in REST microservices. + <br><b>Developers will typically subclass this when creating microservices.</b> + <li class='jac'> + {@link org.apache.juneau.rest.RestServletGroupDefault org.apache.juneau.rest.RestServletGroupDefault} + <br>A default implementation for "router" pages. + <ul> + <li class='jac'> + {@link org.apache.juneau.microservice.ResourceGroup org.apache.juneau.microservice.ResourceGroup} + <br>Subclass intended to be used in REST microservices. + </ul> + </li> + <li class='jc'> + {@link org.apache.juneau.rest.remoteable.RemoteableServlet org.apache.juneau.rest.remoteable.RemoteableServlet} + <br>REST servlet for implementing remoteable proxy interfaces. + </ul> + </li> + <li class='jac'> + {@link org.apache.juneau.rest.jena.RestServletJenaDefault org.apache.juneau.rest.jena.RestServletJenaDefault} + <br>Same as {@link org.apache.juneau.rest.RestServletDefault}, but adds RDF support. + <ul> + <li class='jac'> + {@link org.apache.juneau.microservice.ResourceJena org.apache.juneau.microservice.ResourceJena} + <br>Subclass intended to be used in REST microservices. + <li class='jac'> + {@link org.apache.juneau.rest.jena.RestServletJenaGroupDefault org.apache.juneau.rest.jena.RestServletJenaGroupDefault} + <br>Same as {@link org.apache.juneau.rest.RestServletGroupDefault}, but adds RDF support. + </ul> + </li> </ul> - <li class='jc'>{@link org.apache.juneau.rest.remoteable.RemoteableServlet org.apache.juneau.rest.remoteable.RemoteableServlet} - <br>REST servlet for implementing remoteable proxy interfaces. - </ul> - <li class='jac'>{@link org.apache.juneau.rest.jena.RestServletJenaDefault org.apache.juneau.rest.jena.RestServletJenaDefault} - <br>Same as {@link org.apache.juneau.rest.RestServletDefault}, but adds RDF support. - <ul> - <li class='jac'>{@link org.apache.juneau.microservice.ResourceJena org.apache.juneau.microservice.ResourceJena} - <br>Subclass intented to be used in REST microservices. - <li class='jac'>{@link org.apache.juneau.rest.jena.RestServletJenaGroupDefault org.apache.juneau.rest.jena.RestServletJenaGroupDefault} - <br>Same as {@link org.apache.juneau.rest.RestServletGroupDefault}, but adds RDF support. - </ul> + </li> </ul> - </ul> + </li> </ul> <p> The servlets with RDF support require Jena on the classpath. All other serializers and parsers do not have any external library dependencies. - For this reason, we have separate servlets for supporting RDF so that you don't need Jena if you don't need to support RDF. + For this reason, we have separate servlets for supporting RDF so that you don't need Jena if you don't need to + support RDF. </p> <p> - The {@link org.apache.juneau.rest.RestRequest} and {@link org.apache.juneau.rest.RestResponse} classes described later also extend from their servlet equivalents: + The {@link org.apache.juneau.rest.RestRequest} and {@link org.apache.juneau.rest.RestResponse} classes + described later also extend from their servlet equivalents: </p> <ul class='doctree'> - <li class='jic'>{@link javax.servlet.http.HttpServletRequest javax.servlet.http.HttpServletRequest} - <ul> - <li class='jc'>{@link org.apache.juneau.rest.RestRequest org.apache.juneau.rest.RestRequest} - Augmented with specialized REST methods. - </ul> - <li class='jic'>{@link javax.servlet.http.HttpServletResponse javax.servlet.http.HttpServletResponse} - <ul> - <li class='jc'>{@link org.apache.juneau.rest.RestResponse org.apache.juneau.rest.RestResponse} - Augmented with specialized REST methods. - </ul> + <li class='jic'> + {@link javax.servlet.http.HttpServletRequest javax.servlet.http.HttpServletRequest} + <ul> + <li class='jc'> + {@link org.apache.juneau.rest.RestRequest org.apache.juneau.rest.RestRequest} + - Augmented with specialized REST methods. + </ul> + </li> + <li class='jic'> + {@link javax.servlet.http.HttpServletResponse javax.servlet.http.HttpServletResponse} + <ul> + <li class='jc'> + {@link org.apache.juneau.rest.RestResponse org.apache.juneau.rest.RestResponse} + - Augmented with specialized REST methods. + </ul> + </li> </ul> </div> - <!-- ======================================================================================================== --> +<!-- ======================================================================================================== --> <a id="RestResources"></a> <h2 class='topic' onclick='toggle(this)'>4 - REST Servlets</h2> - <div class='topic'> - <p> - Since REST servlets are subclasses of <l>HttpServlet</l>, they can be deployed in a J2EE - container like any other servlet, typically inside a <l>web.xml</l> file. - The REST servlet framework does not depend on any classloader scanning or external setup - other than registering the servlet with the J2EE container. - </p> - <p> +<div class='topic'> + <p> + Since REST servlets are subclasses of <l>HttpServlet</l>, they can be deployed in a J2EE container like any + other servlet, typically inside a <l>web.xml</l> file. + The REST servlet framework does not depend on any classloader scanning or external setup other than + registering the servlet with the J2EE container. + </p> + <p> REST servlets can also be deployed by declaring them as children of other REST servlets (described later). - </p> - <p> - A REST servlet consists of an instance of {@link org.apache.juneau.rest.RestServlet} - annotated with {@link org.apache.juneau.rest.annotation.RestResource @RestResource} containing - public Java methods annotated with {@link org.apache.juneau.rest.annotation.RestMethod @RestMethod}. - </p> - <p> + </p> + <p> + A REST servlet consists of an instance of {@link org.apache.juneau.rest.RestServlet} annotated with + {@link org.apache.juneau.rest.annotation.RestResource @RestResource} containing public Java methods + annotated with {@link org.apache.juneau.rest.annotation.RestMethod @RestMethod}. + </p> + <p> Developers will typically subclass directly from {@link org.apache.juneau.rest.RestServletDefault} - since it provides a default set of serializers and parsers for a variety of - <l>Accept</l> and <l>Content-Type</l> types. - </p> + since it provides a default set of serializers and parsers for a variety of <l>Accept</l> and + <l>Content-Type</l> types. + </p> + <h6 class='figure'>Valid Accept headers for RestServletDefault</h6> <table class='styled'> <tr> @@ -465,6 +514,7 @@ <td>{@link org.apache.juneau.jso.JsoSerializer}</td> </tr> </table> + <h6 class='figure'>Valid Content-Type headers for RestServletDefault</h6> <table class='styled'> <tr> @@ -498,15 +548,17 @@ </table> <p> {@link org.apache.juneau.rest.RestServletDefault} also provides a default OPTIONS page by implementing - a {@link org.apache.juneau.rest.RestServletDefault#getOptions(RestRequest)} method that returns a POJO consisting - of beans describing the class. + a {@link org.apache.juneau.rest.RestServletDefault#getOptions(RestRequest)} method that returns a POJO + consisting of beans describing the class. This is what produces the output for the OPTIONS page on the Hello World sample above. - </p> + </p> <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jac'>{@link org.apache.juneau.rest.RestServletDefault} - <li class='jac'>{@link org.apache.juneau.rest.jena.RestServletJenaDefault} + <li class='jac'> + {@link org.apache.juneau.rest.RestServletDefault} + <li class='jac'> + {@link org.apache.juneau.rest.jena.RestServletJenaDefault} </ul> <!-- ======================================================================================================== --> @@ -514,7 +566,8 @@ <h3 class='topic' onclick='toggle(this)'>4.1 - REST Java Method Signature</h3> <div class='topic'> <p> - REST Java methods are identified on REST servlets using the {@link org.apache.juneau.rest.annotation.RestMethod @RestMethod} annotation. + REST Java methods are identified on REST servlets using the + {@link org.apache.juneau.rest.annotation.RestMethod @RestMethod} annotation. The annotation allows the framework to identify the available REST methods through reflection. </p> <p class='bcode'> @@ -524,20 +577,26 @@ <jk>return</jk> <js>"Hello world!"</js>; } </p> + <h6 class='topic'>Method Name</h6> <p> There are no restrictions on the name of the Java method. However, if you plan on making use of the - {@link org.apache.juneau.rest.annotation.RestResource#messages() @RestResource.messages()} - annotation (described later), the method names must be unique to make it possible to identify unique keys for labels in the resource bundle. - Therefore, you should not define two identically-named <l>doFoo(...)</l> methods that differ only by parameters. + {@link org.apache.juneau.rest.annotation.RestResource#messages() @RestResource.messages()} annotation + (described later), the method names must be unique to make it possible to identify unique keys for labels + in the resource bundle. + Therefore, you should not define two identically-named <l>doFoo(...)</l> methods that differ only by + parameters. If you're not using messages for NLS support, then name them whatever you want! </p> + <h6 class='topic'>Method Return Type</h6> <p> - The return type can be any serializable POJO as defined in <a class='doclink' href='../../../../overview-summary.html#Core.PojoCategories'>POJO Categories</a>. - It can also be <jk>void</jk> if the method is not sending any output (e.g. a request redirect) or - is setting the output using the {@link org.apache.juneau.rest.RestResponse#setOutput(Object)} method. - Calling the {@link org.apache.juneau.rest.RestResponse#setOutput(Object)} method is functionally equivalent to returning a value. + The return type can be any serializable POJO as defined in <a class='doclink' + href='../../../../overview-summary.html#Core.PojoCategories'>POJO Categories</a>. + It can also be <jk>void</jk> if the method is not sending any output (e.g. a request redirect) or is + setting the output using the {@link org.apache.juneau.rest.RestResponse#setOutput(Object)} method. + Calling the {@link org.apache.juneau.rest.RestResponse#setOutput(Object)} method is functionally equivalent + to returning a value. </p> <p class='bcode'> <jc>// Equivalent method 1</jc> @@ -556,30 +615,43 @@ The return type can also be any of the following special object types: </p> <ul class='doctree'> - <li class='jc'>{@link java.io.InputStream} - <br>The contents are simply piped to the output stream returned by {@link org.apache.juneau.rest.RestResponse#getNegotiatedOutputStream()}. - <br>Note that you should call {@link org.apache.juneau.rest.RestResponse#setContentType(String)} to set the <l>Content-Type</l> header if you use this object type. - <li class='jc'>{@link java.io.Reader} - <br>The contents are simply piped to the output stream returned by {@link org.apache.juneau.rest.RestResponse#getNegotiatedWriter()}. - <br>Note that you should call {@link org.apache.juneau.rest.RestResponse#setContentType(String)} to set the <l>Content-Type</l> header if you use this object type. - <li class='jc'>{@link org.apache.juneau.rest.Redirect} + <li class='jc'> + {@link java.io.InputStream} + <br>The contents are simply piped to the output stream returned by + {@link org.apache.juneau.rest.RestResponse#getNegotiatedOutputStream()}. + <br>Note that you should call {@link org.apache.juneau.rest.RestResponse#setContentType(String)} to set + the <l>Content-Type</l> header if you use this object type. + <li class='jc'> + {@link java.io.Reader} + <br>The contents are simply piped to the output stream returned by + {@link org.apache.juneau.rest.RestResponse#getNegotiatedWriter()}. + <br>Note that you should call {@link org.apache.juneau.rest.RestResponse#setContentType(String)} to set + the <l>Content-Type</l> header if you use this object type. + <li class='jc'> + {@link org.apache.juneau.rest.Redirect} <br>Represents an HTTP redirect response. - <li class='jic'>{@link org.apache.juneau.Streamable} + <li class='jic'> + {@link org.apache.juneau.Streamable} <br>Interface that identifies that an object can be serialized directly to an output stream. - <li class='jic'>{@link org.apache.juneau.Writable} + <li class='jic'> + {@link org.apache.juneau.Writable} <br>Interface that identifies that an object can be serialized directly to a writer. - <li class='jc'>{@link org.apache.juneau.utils.ZipFileList} + <li class='jc'> + {@link org.apache.juneau.utils.ZipFileList} <br>Special interface for sending zip files as responses. </ul> <p> - Additional "special types" can be defined through the {@link org.apache.juneau.rest.ResponseHandler} interface (described later). + Additional "special types" can be defined through the {@link org.apache.juneau.rest.ResponseHandler} + interface (described later). </p> + <h6 class='topic'>Method Parameters</h6> <p> The method can contain any of the following parameters in any order: </p> <ul class='spaced-list'> - <li>Parameters of the following class types: + <li> + Parameters of the following class types: <ul> <li>Request/response objects: <ul> @@ -654,7 +726,8 @@ <li>{@link org.apache.juneau.ini.ConfigFile} - The external config file for the resource. </ul> </ul> - <li>Annotated parameters: + <li> + Annotated parameters: <ul> <li>{@link org.apache.juneau.rest.annotation.Path @Path} - Variables in matched URL path patterns. <li>{@link org.apache.juneau.rest.annotation.FormData @FormData} - Multipart form post parameter values. @@ -694,8 +767,9 @@ } </p> <p> - All the annotated parameters (with the exception of <l>@Body</l>) can be any POJO type convertable from a <l>String</l>. - (See <a class='doclink' href='#PojosConvertableFromString'>POJOs Convertable From String</a>) + All the annotated parameters (with the exception of <l>@Body</l>) can be any POJO type convertible from a + <l>String</l>. + (See <a class='doclink' href='#PojosConvertableFromString'>POJOs Convertible From String</a>) </p> <p> For example, headers can be accessed as Strings or UUIDs... @@ -716,17 +790,17 @@ <h4 class='topic' onclick='toggle(this)'>4.1.1 - Path</h4> <div class='topic'> <p> - The {@link org.apache.juneau.rest.annotation.RestMethod#path() @RestMethod.path()} annotation - allows you to define URL path patterns to match against. + The {@link org.apache.juneau.rest.annotation.RestMethod#path() @RestMethod.path()} annotation allows + you to define URL path patterns to match against. These patterns can contain variables of the form <l>"{xxx}"</l> that can be passed in directly to the - Java methods as extra parameters. - </p> - <p> + Java methods as extra parameters. + </p> + <p> In the following example, 3 separate GET request handlers are defined with different path patterns. - Note how the variables are passed in as additional arguments on the method, and how those arguments are automatically - converted to the specified class type... - </p> - <p class='bcode'> + Note how the variables are passed in as additional arguments on the method, and how those arguments are + automatically converted to the specified class type... + </p> + <p class='bcode'> <jc>// Default method</jc> <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/*"</js>) <jk>public void</jk> doGetDefault() { @@ -744,12 +818,12 @@ <jk>public void</jk> doGetWithArgs(<ja>@Path</ja> String foo, <ja>@Path</ja> <jk>int</jk> bar, <ja>@Path</ja> MyEnum baz, <ja>@Path</ja> UUID bing) { ... } - </p> - <p> + </p> + <p> By default, path patterns are matched using a best-match heuristic. When overlaps occur, URLs are matched from most-specific to most-general order: - </p> - <p class='bcode'> + </p> + <p class='bcode'> <jc>// Try first </jc> <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/foo/bar"</js>) <jk>public void</jk> method1() { @@ -773,19 +847,22 @@ <jk>public void</jk> method4(...) { ... } - </p> - <p> - The match heuristic behavior can be overridden by the {@link org.apache.juneau.rest.annotation.RestMethod#priority() @RestMethod.priority()} annotation property. + </p> + <p> + The match heuristic behavior can be overridden by the + {@link org.apache.juneau.rest.annotation.RestMethod#priority() @RestMethod.priority()} annotation + property. However, in practice this is almost never needed. - </p> - <p> + </p> + <p> Paths that end with <js>"/*"</js> will do a prefix match on the incoming URL. - Any remainder after the match can be accessed through {@link org.apache.juneau.rest.RequestPathMatch#getRemainder()} - or parameters with the {@link org.apache.juneau.rest.annotation.PathRemainder @PathRemainder} annotation. - On the other hand, paths that don't end with <js>"/*"</js> (e.g. <js>"/"</js> or <js>"/foo"</js>) will require - an exact URL match, and if any remainder exists, a 404 (not found) error will be thrown. - </p> - <p> + Any remainder after the match can be accessed through + {@link org.apache.juneau.rest.RequestPathMatch#getRemainder()} or parameters with the + {@link org.apache.juneau.rest.annotation.PathRemainder @PathRemainder} annotation. + On the other hand, paths that don't end with <js>"/*"</js> (e.g. <js>"/"</js> or <js>"/foo"</js>) will + require an exact URL match, and if any remainder exists, a 404 (not found) error will be thrown. + </p> + <p> The following example shows the distinction. </p> <p class='bcode'> @@ -798,8 +875,8 @@ <jk>public void</jk> doPut() { <jc>// URL path pattern must match exactly and will cause a 404 error if a remainder exists.</jc> } - </p> - <p> + </p> + <p> Annotations are provided for easy access to URL parameters with automatic conversion to any parsable object type. For example, the following example can process the URL <l>"/urlWithParams?foo=foo&bar=[1,2,3]&baz=067e6162-3b6f-4ae2-a171-2470b63dff00"</l>... </p> @@ -809,16 +886,18 @@ <jk>public</jk> String doGetWithParams(<ja>@Query</ja>(<js>"foo"</js>) String foo, <ja>@Query</ja>(<js>"bar"</js>) <jk>int</jk> bar, <ja>@Query</ja>(<js>"baz"</js>) UUID baz) <jk>throws</jk> Exception { <jk>return</jk> <js>"GET /urlWithParams?foo="</js>+foo+<js>"&bar="</js>+bar+<js>"&baz="</js>+baz); } - </p> + </p> </div> <!-- ======================================================================================================== --> <a id="RestResources.MethodSignature.Matchers"></a> <h4 class='topic' onclick='toggle(this)'>4.1.2 - Matchers</h4> <div class='topic'> - <p> - {@link org.apache.juneau.rest.RestMatcher RestMatchers} are used to allow multiple Java methods to be tied to the same HTTP method and path, but - differentiated by some request attribute such as a specific header value. + <p> + {@link org.apache.juneau.rest.RestMatcher RestMatchers} are used to allow multiple Java methods to be + tied to the same HTTP method and path, but differentiated by some request attribute such as a specific + header value. + </p> <p class='bcode'> <jc>// GET method that gets invoked for administrators</jc> <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/*"</js>, matchers=IsAdminMatcher.<jk>class</jk>) @@ -831,8 +910,8 @@ <jk>public</jk> Object doGetForEveryoneElse() { ... } - </p> - <p> + </p> + <p> The interface for matchers is simple: </p> <p class='bcode'> @@ -842,18 +921,25 @@ <jk>return</jk> req.isUserInRole(<js>"ADMINS_GROUP"</js>); } } - </p> + </p> + <h6 class='topic'>Other Notes</h6> <ul class='spaced-list'> - <li>If no methods are found with a matching matcher, a <l>412 Precondition Failed</l> status is returned. - <li>If multiple matchers are specified on the same method, ONLY ONE matcher needs to match for the method to be invoked. - <li>Note that you CANNOT define identical paths on different methods UNLESS you use matchers. - <br>That includes paths that are only different in variable names (e.g. <l>"/foo/{bar}"</l> and <l>"/foo/{baz}"</l>). + <li> + If no methods are found with a matching matcher, a <l>412 Precondition Failed</l> status is returned. + <li> + If multiple matchers are specified on the same method, ONLY ONE matcher needs to match for the + method to be invoked. + <li> + Note that you CANNOT define identical paths on different methods UNLESS you use matchers. + <br>That includes paths that are only different in variable names (e.g. <l>"/foo/{bar}"</l> and + <l>"/foo/{baz}"</l>). <br>If you try to do so, a <l>ServletException</l> will be thrown on startup. - <li>Methods with matchers take precedence over methods without. + <li> + Methods with matchers take precedence over methods without. <br>Otherwise, methods are attempted in the order they appear in the class. </ul> - </div> + </div> </div> <!-- ======================================================================================================== --> @@ -874,8 +960,8 @@ </p> <p> The HTTP body of a request can be retrieved as a parsed POJO using either the - {@link org.apache.juneau.rest.RestRequest#getBody()} method, or a parameter - annotated with {@link org.apache.juneau.rest.annotation.Body @Body}. + {@link org.apache.juneau.rest.RestRequest#getBody()} method, or a parameter annotated with + {@link org.apache.juneau.rest.annotation.Body @Body}. </p> <p class='bcode'> <jc>// Equivalent method 1</jc> @@ -893,23 +979,24 @@ </p> <p> The Juneau framework will automatically determine the appropriate <l>Parser</l> to use based on the - <l>Content-Type</l> HTTP header. So the body content could be JSON or XML or any other supported parsing types. + <l>Content-Type</l> HTTP header. + So the body content could be JSON or XML or any other supported parsing types. </p> - <!-- ======================================================================================================== --> + <!-- ======================================================================================================== --> <a id="RestResources.RequestContent.FormPosts"></a> <h4 class='topic' onclick='toggle(this)'>4.2.1 - Form Posts</h4> - <div class='topic'> - <p> + <div class='topic'> + <p> URL-Encoded form posts require their own topic since they can be handled in multiple ways. </p> <p> The best way to handle a form post is by using an input bean. - The samples include a <l>UrlEncodedFormResource</l> class that takes in URL-Encoded - form post of the form <l>"aString=foo&aNumber=123&aDate=2001-07-04T15:30:45Z"</l>. + The samples include a <l>UrlEncodedFormResource</l> class that takes in URL-Encoded form post of the + form <l>"aString=foo&aNumber=123&aDate=2001-07-04T15:30:45Z"</l>. The code is shown here: - </p> - <p class='bcode'> + </p> + <p class='bcode'> <ja>@RestResource</ja>( path=<js>"/urlEncodedForm"</js> ) @@ -929,8 +1016,8 @@ <jk>public</jk> Calendar <jf>aDate</jf>; } } - </p> - <p> + </p> + <p> Another possibility is to access the form parameters individually: </p> <p class='bcode'> @@ -942,14 +1029,15 @@ </p> <p> The advantage to the form input bean is that it can handle any of the parsable types (e.g. JSON, XML...) - in addition to URL-Encoding. The latter approach only supports URL-Encoding. + in addition to URL-Encoding. The latter approach only supports URL-Encoding. </p> <ul class='doctree'> - <li class='severe'>If you're using form input beans, DO NOT use the <l>@FormData</l> attribute - or {@link org.apache.juneau.rest.RestRequest#getParameter(String)} method since this will - cause the underlying JEE servlet to parse the HTTP body as a form post. - <br>Your input bean will end up being null since there won't be any content left - after the servlet has parsed the body of the request. + <li class='severe'> + If you're using form input beans, DO NOT use the <l>@FormData</l> attribute or + {@link org.apache.juneau.rest.RestRequest#getParameter(String)} method since this will cause the + underlying JEE servlet to parse the HTTP body as a form post. + <br>Your input bean will end up being null since there won't be any content left after the servlet + has parsed the body of the request. <br>This applies to WHENEVER you use <l>@Body</l> or {@link org.apache.juneau.rest.RestRequest#getBody()} </ul> </div> @@ -958,13 +1046,13 @@ <a id="RestResources.RequestContent"></a> <h4 class='topic' onclick='toggle(this)'>4.2.2 - Multipart Form Posts</h4> <div class='topic'> - <p> + <p> The Juneau framework does not natively support multipart form posts. - However, it can be used in conjunction wih the Apache Commons File Upload library to do so. - </p> - <p> - The samples include a <l>TempDirResource</l> class that uses the File Upload library - to allow files to be uploaded as multipart form posts. + However, it can be used in conjunction with the Apache Commons File Upload library to do so. + </p> + <p> + The samples include a <l>TempDirResource</l> class that uses the File Upload library to allow files to + be uploaded as multipart form posts. </p> <p class='bcode'> <ja>@RestResource</ja>( @@ -998,7 +1086,7 @@ <jk>return</jk> contentType != <jk>null</jk> && contentType.startsWith(<js>"multipart/form-data"</js>); } } - </p> + </p> </div> </div> @@ -1010,11 +1098,15 @@ REST Java methods can generate output in any of the following ways: </p> <ul class='spaced-list'> - <li>By returning a serializable POJO, or any of the following: - <br>{@link java.io.Reader}, {@link java.io.InputStream}, {@link org.apache.juneau.Streamable}, {@link org.apache.juneau.Writable} - <li>By calling {@link org.apache.juneau.rest.RestResponse#setOutput(Object)} with any of the types above. - <li>By accessing the {@link java.io.Writer} directly by calling {@link org.apache.juneau.rest.RestResponse#getNegotiatedWriter()} and writing the output - yourself. + <li> + By returning a serializable POJO, or any of the following: + <br>{@link java.io.Reader}, {@link java.io.InputStream}, {@link org.apache.juneau.Streamable}, + {@link org.apache.juneau.Writable} + <li> + By calling {@link org.apache.juneau.rest.RestResponse#setOutput(Object)} with any of the types above. + <li> + By accessing the {@link java.io.Writer} directly by calling + {@link org.apache.juneau.rest.RestResponse#getNegotiatedWriter()} and writing the output yourself. </ul> <p class='bcode'> <jc>// Equivalent method 1</jc> @@ -1049,21 +1141,27 @@ <h3 class='topic' onclick='toggle(this)'>4.4 - OPTIONS Pages</h3> <div class='topic'> <p> - One of the most useful features of Juneau is that it can produce OPTIONS pages for self-documenting designs (i.e. REST interfaces that document themselves). + One of the most useful features of Juneau is that it can produce OPTIONS pages for self-documenting designs + (i.e. REST interfaces that document themselves). </p> + <h6 class='figure'>OPTIONS page for HelloWorld sample resource</h6> <img class='bordered' src='doc-files/HelloWorldResourceOptions.png'> <p> - This page is constructed through reflection on the servlet class and it's methods, combined with information provided in the following locations: + This page is constructed through reflection on the servlet class and it's methods, combined with + information provided in the following locations: </p> <ul> - <li>Annotations (i.e. {@link org.apache.juneau.rest.annotation.RestResource @RestResource} and {@link org.apache.juneau.rest.annotation.RestMethod @RestMethod}). + <li>Annotations (i.e. {@link org.apache.juneau.rest.annotation.RestResource @RestResource} and + {@link org.apache.juneau.rest.annotation.RestMethod @RestMethod}). <li>Resource bundle properties. <li>Swagger JSON files. </ul> <p> - Swagger JSON files are specified with the same name as the servlet (e.g. <code>MyResource.java</code> -> <code>MyResource.json</code>). - Localized versions of Swagger JSON files can be specified by appending the locale to the file name (e.g. <code>MyResource_ja_JP.json</code>). + Swagger JSON files are specified with the same name as the servlet + (e.g. <code>MyResource.java</code> -> <code>MyResource.json</code>). + Localized versions of Swagger JSON files can be specified by appending the locale to the file name + (e.g. <code>MyResource_ja_JP.json</code>). The existence of Swagger JSON files will override any auto-generation of the OPTIONS pages. This allows you to fully control the contents of the OPTIONS page with your own Swagger spec. </p> @@ -1073,9 +1171,10 @@ </p> <p> {@link org.apache.juneau.rest.RestServletDefault} provides a default OPTIONS page by implementing - a {@link org.apache.juneau.rest.RestServletDefault#getOptions(RestRequest)} method that returns a POJO consisting - of beans describing the class. - It uses the {@link org.apache.juneau.rest.RestRequest#getSwagger()} method that returns a localized swagger bean. + a {@link org.apache.juneau.rest.RestServletDefault#getOptions(RestRequest)} method that returns a POJO + consisting of beans describing the class. + It uses the {@link org.apache.juneau.rest.RestRequest#getSwagger()} method that returns a localized swagger + bean. </p> <p class='bcode'> <jd>/** @@ -1094,13 +1193,17 @@ <jk>return</jk> req.getSwagger(); } </p> + <h6 class='topic'>Title and Description</h6> <p> The title and description can be defined in the following ways. </p> <ul> - <li>Annotations: {@link org.apache.juneau.rest.annotation.RestResource#title()}, {@link org.apache.juneau.rest.annotation.RestResource#description()} - <li>By overriding methods on the servlet class: {@link org.apache.juneau.rest.RestInfoProvider#getTitle(RestRequest)}, {@link org.apache.juneau.rest.RestInfoProvider#getDescription(RestRequest)} + <li>Annotations: {@link org.apache.juneau.rest.annotation.RestResource#title()}, + {@link org.apache.juneau.rest.annotation.RestResource#description()} + <li>By overriding methods on the servlet class: + {@link org.apache.juneau.rest.RestInfoProvider#getTitle(RestRequest)}, + {@link org.apache.juneau.rest.RestInfoProvider#getDescription(RestRequest)} <li>By defining properties in the resource bundle. <li>By specifying them in a Swagger JSON file. </ul> @@ -1117,9 +1220,8 @@ </p> <p> The second approach which supports internationalization is to use the - {@link org.apache.juneau.rest.annotation.RestResource#messages() @RestResource.messages()} - annotation to point to a resource bundle, and then use predefined properties - that identify the label and description. + {@link org.apache.juneau.rest.annotation.RestResource#messages() @RestResource.messages()} annotation to + point to a resource bundle, and then use predefined properties that identify the label and description. </p> <p class='bcode'> <ja>@RestResource</ja>( @@ -1138,7 +1240,8 @@ <ck>description</ck> = <cv>This shows how to use labels and descriptions.</cv> </p> <p> - Message keys can optionally be prefixed by the short class name if the resource bundle is shared by multiple servlets: + Message keys can optionally be prefixed by the short class name if the resource bundle is shared by + multiple servlets: </p> <p class='bcode'> <cc>#-------------------------------------------------------------------------------- @@ -1154,12 +1257,16 @@ The localized label and description are also available through the following methods: </p> <ul class='doctree'> - <li class='jm'>{@link org.apache.juneau.rest.RestRequest#getServletTitle()} - <li class='jm'>{@link org.apache.juneau.rest.RestRequest#getServletDescription()} + <li class='jm'> + {@link org.apache.juneau.rest.RestRequest#getServletTitle()} + <li class='jm'> + {@link org.apache.juneau.rest.RestRequest#getServletDescription()} </ul> <p> - They are also made available as the request string variables <js>"$R{servletTitle}"</js> and <js>"$R{servletDescription}"</js>. - These variable facilitate the localized label and descriptions on the HTML pages when using {@link org.apache.juneau.rest.RestServletDefault}: + They are also made available as the request string variables <js>"$R{servletTitle}"</js> and + <js>"$R{servletDescription}"</js>. + These variable facilitate the localized label and descriptions on the HTML pages when using + {@link org.apache.juneau.rest.RestServletDefault}: </p> <p class='bcode'> <ja>@RestResource</ja>( @@ -1170,7 +1277,8 @@ </p> <p> The title and description annotations support string variables. - So in theory, you could also provide localized messages using <js>"$L"</js> variables pointing to your own resource bundle properties: + So in theory, you could also provide localized messages using <js>"$L"</js> variables pointing to your own + resource bundle properties: </p> <p class='bcode'> <ja>@RestResource</ja>( @@ -1183,13 +1291,14 @@ </p> <p> Another option is to override the {@link org.apache.juneau.rest.RestInfoProvider#getTitle(RestRequest)} - and {@link org.apache.juneau.rest.RestInfoProvider#getDescription(RestRequest)} methods. - </p> + and {@link org.apache.juneau.rest.RestInfoProvider#getDescription(RestRequest)} methods. + </p> + <h6 class='topic'>Method Description, Input, and Responses</h6> <p> The <l>methods</l> field in the OPTIONS page is mostly populated through reflection. - However, the description, input, and responses field can be specified through either - annotations or resource properties. + However, the description, input, and responses field can be specified through either annotations or + resource properties. </p> <p> For example, the <l>AddressBookResource</l> has a <l>getPerson()</l> method @@ -1197,9 +1306,10 @@ </p> <img class='bordered' src='doc-files/Options2.png'> <p> - This method is described through the {@link org.apache.juneau.rest.annotation.RestMethod#description() @RestMethod.description()}, - {@link org.apache.juneau.rest.annotation.RestMethod#swagger() @RestMethod.swagger()}, - and {@link org.apache.juneau.rest.annotation.MethodSwagger @MethodSwagger} annotations. + This method is described through the + {@link org.apache.juneau.rest.annotation.RestMethod#description() @RestMethod.description()}, + {@link org.apache.juneau.rest.annotation.RestMethod#swagger() @RestMethod.swagger()}, + and {@link org.apache.juneau.rest.annotation.MethodSwagger @MethodSwagger} annotations. </p> <p class='bcode'> <ja>@RestMethod</ja>( @@ -1311,11 +1421,15 @@ <td>{@link org.apache.juneau.rest.annotation.MethodSwagger#responses() @MethodSwagger.responses()}</td> </tr> </table> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='ja'>{@link org.apache.juneau.rest.annotation.RestMethod#description() @RestMethod.description()} - <li class='ja'>{@link org.apache.juneau.rest.annotation.MethodSwagger#parameters() @MethodSwagger.parameters()} - <li class='ja'>{@link org.apache.juneau.rest.annotation.MethodSwagger#responses() @MethodSwagger.responses()} + <li class='ja'> + {@link org.apache.juneau.rest.annotation.RestMethod#description() @RestMethod.description()} + <li class='ja'> + {@link org.apache.juneau.rest.annotation.MethodSwagger#parameters() @MethodSwagger.parameters()} + <li class='ja'> + {@link org.apache.juneau.rest.annotation.MethodSwagger#responses() @MethodSwagger.responses()} </ul> </div> @@ -1324,20 +1438,27 @@ <h3 class='topic' onclick='toggle(this)'>4.5 - Serializers</h3> <div class='topic'> <p> - REST servlets use the {@link org.apache.juneau.serializer.Serializer} API for defining serializers for serializing response POJOs. + REST servlets use the {@link org.apache.juneau.serializer.Serializer} API for defining serializers for + serializing response POJOs. </p> <p> The servlet will pick which serializer to use by matching the request <l>Accept</l> header with the - media types defined through the {@link org.apache.juneau.serializer.Serializer#getMediaTypes()} method - (which itself usually comes from the {@link org.apache.juneau.annotation.Produces @Produces} annotation). + media types defined through the {@link org.apache.juneau.serializer.Serializer#getMediaTypes()} method + (which itself usually comes from the {@link org.apache.juneau.annotation.Produces @Produces} annotation). </p> <p> Serializers can be associated with REST servlets in the following ways: </p> <ul class='doctree'> - <li class='ja'>{@link org.apache.juneau.rest.annotation.RestResource#serializers() @RestResource.serializers()} - Annotation on servlet class. - <li class='ja'>{@link org.apache.juneau.rest.annotation.RestMethod#serializers() @RestMethod.serializers()} - Annotation on individual servlet methods. - <li class='jm'>{@link org.apache.juneau.rest.RestConfig#addSerializers(Class[])} - Override method to set the serializers programmatically. + <li class='ja'> + {@link org.apache.juneau.rest.annotation.RestResource#serializers() @RestResource.serializers()} + - Annotation on servlet class. + <li class='ja'> + {@link org.apache.juneau.rest.annotation.RestMethod#serializers() @RestMethod.serializers()} + - Annotation on individual servlet methods. + <li class='jm'> + {@link org.apache.juneau.rest.RestConfig#addSerializers(Class[])} + - Override method to set the serializers programmatically. </ul> <p> The following are equivalent ways of defining serializers used by a servlet... @@ -1369,13 +1490,15 @@ </p> <ul class='doctree'> <li class='info'> - When debugging the output from REST servlets, it's almost always easier to bypass the REST servlet and try to serialize - the POJOs using the serializers directly using the {@link org.apache.juneau.serializer.WriterSerializer#toString(Object)} method. + When debugging the output from REST servlets, it's almost always easier to bypass the REST servlet and + try to serialize the POJOs using the serializers directly using the + {@link org.apache.juneau.serializer.WriterSerializer#toString(Object)} method. </ul> <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='ja'>{@link org.apache.juneau.rest.annotation.RestMethod#serializersInherit() @RestMethod.serializersInherit()} + <li class='ja'> + {@link org.apache.juneau.rest.annotation.RestMethod#serializersInherit() @RestMethod.serializersInherit()} <br>Controls how serializers are inherited from the servlet class. </ul> </div> @@ -1385,20 +1508,27 @@ <h3 class='topic' onclick='toggle(this)'>4.6 - Parsers</h3> <div class='topic'> <p> - REST servlets use the {@link org.apache.juneau.parser.Parser} API for defining parsers for parsing request body content and converting them into POJOs. + REST servlets use the {@link org.apache.juneau.parser.Parser} API for defining parsers for parsing request + body content and converting them into POJOs. </p> <p> The servlet will pick which parser to use by matching the request <l>Content-Type</l> header with the - media types defined through the {@link org.apache.juneau.parser.Parser#getMediaTypes()} method (which itself - usually comes from the {@link org.apache.juneau.annotation.Consumes @Consumes} annotation). + media types defined through the {@link org.apache.juneau.parser.Parser#getMediaTypes()} method (which itself + usually comes from the {@link org.apache.juneau.annotation.Consumes @Consumes} annotation). </p> <p> Parsers can be associated with REST servlets in the following ways: </p> <ul class='doctree'> - <li class='ja'>{@link org.apache.juneau.rest.annotation.RestResource#parsers() @RestResource.parsers()} - Annotation on servlet class. - <li class='ja'>{@link org.apache.juneau.rest.annotation.RestMethod#parsers() @RestMethod.parsers()} - Annotation on individual servlet methods. - <li class='jm'>{@link org.apache.juneau.rest.RestConfig#addParsers(Class[])} - Override method to set the parsers programmatically. + <li class='ja'> + {@link org.apache.juneau.rest.annotation.RestResource#parsers() @RestResource.parsers()} + - Annotation on servlet class. + <li class='ja'> + {@link org.apache.juneau.rest.annotation.RestMethod#parsers() @RestMethod.parsers()} + - Annotation on individual servlet methods. + <li class='jm'> + {@link org.apache.juneau.rest.RestConfig#addParsers(Class[])} + - Override method to set the parsers programmatically. </ul> <p> The following are equivalent ways of defining parsers used by a servlet... @@ -1428,9 +1558,11 @@ .append(JsonParser.<jk>class</jk>, XmlParser.<jk>class</jk>); } </p> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='ja'>{@link org.apache.juneau.rest.annotation.RestMethod#parsersInherit() @RestMethod.parsersInherit()} + <li class='ja'> + {@link org.apache.juneau.rest.annotation.RestMethod#parsersInherit() @RestMethod.parsersInherit()} <br>Controls how parsers are inherited from the servlet class. </ul> </div> @@ -1445,13 +1577,14 @@ </p> <p> There are several ways of defining properties in the REST API. - The most common way is going to be through the {@link org.apache.juneau.rest.annotation.RestResource#properties() @RestResource.properties()} + The most common way is going to be through the + {@link org.apache.juneau.rest.annotation.RestResource#properties() @RestResource.properties()} and {@link org.apache.juneau.rest.annotation.RestMethod#properties() @RestMethod.properties()} annotations. </p> <p> - The {@link org.apache.juneau.rest.annotation.RestResource#properties() @RestResource.properties()} annotation - can be used as a convenient way to set various serializer and parser - properties to all serializers and parsers registered with the servlet. + The {@link org.apache.juneau.rest.annotation.RestResource#properties() @RestResource.properties()} + annotation can be used as a convenient way to set various serializer and parser properties to all + serializers and parsers registered with the servlet. </p> <p class='bcode'> <jk>import static</jk> org.apache.juneau.SerializerContext.*; @@ -1482,7 +1615,8 @@ </p> <p> The {@link org.apache.juneau.rest.annotation.RestMethod#properties() @RestMethod.properties()} annotation - can be used to define method-level properties that can alter the behavior of serializers and parsers at the method level only. + can be used to define method-level properties that can alter the behavior of serializers and parsers at the + method level only. </p> <p class='bcode'> <jc>// GET method with method-level properties</jc> @@ -1508,26 +1642,32 @@ } </p> <p> - In particular, the {@link org.apache.juneau.rest.RestContext} class has a variety of properties - for controlling the behavior of the {@link org.apache.juneau.rest.RestServlet} class itself. + In particular, the {@link org.apache.juneau.rest.RestContext} class has a variety of properties for + controlling the behavior of the {@link org.apache.juneau.rest.RestServlet} class itself. </p> <p> There are also ways to provide properties programmatically. </p> <ul class='spaced-list'> - <li>By overriding the {@link org.apache.juneau.rest.RestConfig#setProperties(Map)} method. - <li>By overriding the {@link org.apache.juneau.rest.RestConfig#addSerializers(Class[])} and + <li> + By overriding the {@link org.apache.juneau.rest.RestConfig#setProperties(Map)} method. + <li> + By overriding the {@link org.apache.juneau.rest.RestConfig#addSerializers(Class[])} and {@link org.apache.juneau.rest.RestConfig#addParsers(Class[])} methods and setting properties on the serializers and parsers directly. </ul> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jc'>{@link org.apache.juneau.rest.RestContext} + <li class='jc'> + {@link org.apache.juneau.rest.RestContext} <br>Properties associated with the {@link org.apache.juneau.rest.RestServlet} class. - <li class='ja'>{@link org.apache.juneau.rest.annotation.RestMethod#serializersInherit @RestMethod.serializersInherit()} + <li class='ja'> + {@link org.apache.juneau.rest.annotation.RestMethod#serializersInherit @RestMethod.serializersInherit()} <br>Controls how serializers inherit properties from the servlet class. - <li class='ja'>{@link org.apache.juneau.rest.annotation.RestMethod#parsersInherit @RestMethod.parsersInheritInherit()} + <li class='ja'> + {@link org.apache.juneau.rest.annotation.RestMethod#parsersInherit @RestMethod.parsersInheritInherit()} <br>Controls how parsers inherit properties from the servlet class. </ul> </div> @@ -1568,24 +1708,30 @@ </p> <p> {@link org.apache.juneau.rest.annotation.RestMethod#beanFilters() @RestMethod.beanFilters()} and - {@link org.apache.juneau.rest.annotation.RestMethod#pojoSwaps() @RestMethod.pojoSwaps()} - are the equivalent annotations for individual Java methods. + {@link org.apache.juneau.rest.annotation.RestMethod#pojoSwaps() @RestMethod.pojoSwaps()} + are the equivalent annotations for individual Java methods. </p> <p> Transforms can also be defined programmatically through the following: </p> <ul class='spaced-list'> - <li>By overriding the {@link org.apache.juneau.rest.RestConfig#addBeanFilters(Class[])} and {@link org.apache.juneau.rest.RestConfig#addPojoSwaps(Class[])} methods. - <li>By overriding the {@link org.apache.juneau.rest.RestConfig#addSerializers(Class[])} and + <li> + By overriding the {@link org.apache.juneau.rest.RestConfig#addBeanFilters(Class[])} and + {@link org.apache.juneau.rest.RestConfig#addPojoSwaps(Class[])} methods. + <li> + By overriding the {@link org.apache.juneau.rest.RestConfig#addSerializers(Class[])} and {@link org.apache.juneau.rest.RestConfig#addParsers(Class[])} methods and setting transforms on the serializers and parsers directly. </ul> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='ja'>{@link org.apache.juneau.rest.annotation.RestMethod#serializersInherit @RestMethod.serializersInherit()} + <li class='ja'> + {@link org.apache.juneau.rest.annotation.RestMethod#serializersInherit @RestMethod.serializersInherit()} <br>Controls how serializers inherit transforms (bean filters and POJO swaps) from the servlet class. - <li class='ja'>{@link org.apache.juneau.rest.annotation.RestMethod#parsersInherit @RestMethod.parsersInherit()} + <li class='ja'> + {@link org.apache.juneau.rest.annotation.RestMethod#parsersInherit @RestMethod.parsersInherit()} <br>Controls how parsers inherit transforms from the servlet class. </ul> </div> @@ -1599,7 +1745,8 @@ </p> <p> The {@link org.apache.juneau.rest.annotation.RestResource#guards @RestResource.guards()} annotation - can be used to associate one or more class-level {@link org.apache.juneau.rest.RestGuard RestGuards} with a servlet. + can be used to associate one or more class-level {@link org.apache.juneau.rest.RestGuard RestGuards} with a + servlet. </p> <p class='bcode'> <jc>// Servlet with class-level guard applied</jc> @@ -1638,18 +1785,23 @@ </p> <p> A guard failure results in an <l>HTTP 401 Unauthorized</l> response. - However, this can be configured by overriding the {@link org.apache.juneau.rest.RestGuard#guard(RestRequest,RestResponse)} - and processing the response yourself. + However, this can be configured by overriding the + {@link org.apache.juneau.rest.RestGuard#guard(RestRequest,RestResponse)} and processing the response + yourself. </p> <p> - When guards are associated at the class-level, it's equivalent to associating guards on all Java methods on the servlet. + When guards are associated at the class-level, it's equivalent to associating guards on all Java methods on + the servlet. </p> <p> - Class-level guards can also be created programmatically by overriding the {@link org.apache.juneau.rest.RestConfig#addGuards(Class[])} method. + Class-level guards can also be created programmatically by overriding the + {@link org.apache.juneau.rest.RestConfig#addGuards(Class[])} method. </p> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jac'>{@link org.apache.juneau.rest.RestGuard} + <li class='jac'> + {@link org.apache.juneau.rest.RestGuard} </ul> </div> @@ -1662,8 +1814,8 @@ </p> <p> The {@link org.apache.juneau.rest.annotation.RestResource#converters @RestResource.converters()} annotation - can be used as a convenient way to add {@link org.apache.juneau.rest.RestConverter RestConverters} to - all Java REST methods on a servlet. + can be used as a convenient way to add {@link org.apache.juneau.rest.RestConverter RestConverters} to + all Java REST methods on a servlet. </p> <p class='bcode'> <jc>// Associate the Traversable converter to all Java REST methods in this servlet</jc> @@ -1674,7 +1826,7 @@ </p> <p> The {@link org.apache.juneau.rest.annotation.RestMethod#converters() @RestMethod.converters()} annotation - can be used to associate converters on individual methods. + can be used to associate converters on individual methods. </p> <p class='bcode'> <jc>// GET person request handler.</jc> @@ -1689,10 +1841,12 @@ } </p> <p> - The following converter is used to provide support for addressing child nodes in a POJO tree with - URL path remainders. - <br>In this code, the 3rd parameter is the object that was returned by the Java method (or set through <l>request.setObject(o);</l>). - <br>The converter uses the {@link org.apache.juneau.utils.PojoRest} wrapper class to address nodes in the tree. + The following converter is used to provide support for addressing child nodes in a POJO tree with URL path + remainders. + <br>In this code, the 3rd parameter is the object that was returned by the Java method (or set through + <l>request.setObject(o);</l>). + <br>The converter uses the {@link org.apache.juneau.utils.PojoRest} wrapper class to address nodes in the + tree. </p> <p class='bcode'> <jd>/** @@ -1725,18 +1879,26 @@ Juneau defines the following converters out-of-the-box: </p> <ul class='doctree'> - <li class='jic'>{@link org.apache.juneau.rest.RestConverter} + <li class='jic'> + {@link org.apache.juneau.rest.RestConverter} <ul> - <li class='jc'>{@link org.apache.juneau.rest.converters.Queryable} - <br>Provides query parameters that can be used to transform the response (i.e. search/view/sort the POJO response before being serialized). - <li class='jc'>{@link org.apache.juneau.rest.converters.Traversable} - <br>Allows nodes in the POJO response tree to be individually accessed through additional path info on the request. - <li class='jc'>{@link org.apache.juneau.rest.converters.Introspectable} - <br>Allows method calls to be made on the response POJO, and for the result of that method call to be serialized as the response. + <li class='jc'> + {@link org.apache.juneau.rest.converters.Queryable} + <br>Provides query parameters that can be used to transform the response (i.e. search/view/sort the + POJO response before being serialized). + <li class='jc'> + {@link org.apache.juneau.rest.converters.Traversable} + <br>Allows nodes in the POJO response tree to be individually accessed through additional path info on + the request. + <li class='jc'> + {@link org.apache.juneau.rest.converters.Introspectable} + <br>Allows method calls to be made on the response POJO, and for the result of that method call to be + serialized as the response. </ul> </ul> <p> - Class-level converters can be created programmatically by overriding the {@link org.apache.juneau.rest.RestConfig#addConverters(Class[])} method. + Class-level converters can be created programmatically by overriding the + {@link org.apache.juneau.rest.RestConfig#addConverters(Class[])} method. </p> <p> Note that from the example above, you can specify more than one converter. @@ -1744,9 +1906,11 @@ (e.g. first the results will be traversed, then the resulting node will be searched/sorted). </p> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jic'>{@link org.apache.juneau.rest.RestConverter} + <li class='jic'> + {@link org.apache.juneau.rest.RestConverter} </ul> </div> @@ -1756,7 +1920,7 @@ <div class='topic'> <p> Child Resources are REST servlets that are linked to parent servlets through the - {@link org.apache.juneau.rest.annotation.RestResource#children() @RestResource.children()} annnotation. + {@link org.apache.juneau.rest.annotation.RestResource#children() @RestResource.children()} annotation. </p> <p class='bcode'> <jd>/** Parent Resource */</jd> @@ -1776,7 +1940,8 @@ ... </p> <p> - A HUGE advantage of using child resources is that they do not need to be declared in the JEE <l>web.xml</l> file. + A HUGE advantage of using child resources is that they do not need to be declared in the JEE <l>web.xml</l> + file. Initialization of and access to the child resources occurs through the parent resource. Children can be nested arbitrary deep to create complex REST interfaces with a single top-level REST servlet. </p> @@ -1786,7 +1951,7 @@ </p> <p> The {@link org.apache.juneau.rest.RestServletGroupDefault} class provides a default "router" page for - child resources when a parent resource is nothing more than a grouping of child resources. + child resources when a parent resource is nothing more than a grouping of child resources. </p> <p> The <l>RootResources</l> class in the Samples project is an example of a router page: @@ -1828,10 +1993,9 @@ <img class='bordered' src="doc-files/Samples_RootResources.png"/> <p> The <l>RestServletGroupDefault</l> class is nothing more than a subclass of - {@link org.apache.juneau.rest.RestServletDefault} with a <l>getChildren()</l> - method mapped to the servlet root path. - The method returns a POJO with is just a linked-list of beans with name/description - properties. + {@link org.apache.juneau.rest.RestServletDefault} with a <l>getChildren()</l> method mapped to the servlet + root path. + The method returns a POJO with is just a linked-list of beans with name/description properties. </p> <p class='bcode'> <jk>public class</jk> RestServletGroupDefault <jk>extends</jk> RestServletDefault { @@ -1852,11 +2016,15 @@ Children can also be defined programmatically by overriding any of the following methods: </p> <ul class='doctree'> - <li class='jac'>{@link org.apache.juneau.rest.RestConfig} + <li class='jac'> + {@link org.apache.juneau.rest.RestConfig} <ul> - <li class='jm'>{@link org.apache.juneau.rest.RestConfig#addChildResource(String,Object)} - <li class='jm'>{@link org.apache.juneau.rest.RestConfig#addChildResources(Class[])} - <li class='jm'>{@link org.apache.juneau.rest.RestConfig#addChildResources(Object[])} + <li class='jm'> + {@link org.apache.juneau.rest.RestConfig#addChildResource(String,Object)} + <li class='jm'> + {@link org.apache.juneau.rest.RestConfig#addChildResources(Class[])} + <li class='jm'> + {@link org.apache.juneau.rest.RestConfig#addChildResources(Object[])} </ul> </ul> </div> @@ -1866,7 +2034,8 @@ <h3 class='topic' onclick='toggle(this)'>4.12 - Localized Messages</h3> <div class='topic'> <p> - The {@link org.apache.juneau.rest.annotation.RestResource#messages @RestResource.messages()} annotation can be used to associate a resource bundle with a servlet class. + The {@link org.apache.juneau.rest.annotation.RestResource#messages @RestResource.messages()} annotation can + be used to associate a resource bundle with a servlet class. </p> <p class='bcode'> <jc>// Servlet with associated resource bundle</jc> @@ -1880,7 +2049,8 @@ } </p> <p> - The resource bundle can also be passed into the method by using the {@link org.apache.juneau.rest.annotation.Messages @Messages} annotation: + The resource bundle can also be passed into the method by using the + {@link org.apache.juneau.rest.annotation.Messages @Messages} annotation: </p> <p class='bcode'> <ja>@RestMethod</ja>(name=<js>"GET"</js>) @@ -1889,7 +2059,8 @@ } </p> <p> - If a resource bundle is shared by multiple servlets, the label and description can be prefixed by the class name: + If a resource bundle is shared by multiple servlets, the label and description can be prefixed by the class + name: </p> <p class='bcode'> <cc>#-------------------------------------------------------------------------------- @@ -1910,10 +2081,12 @@ <h3 class='topic' onclick='toggle(this)'>4.13- Encoders</h3> <div class='topic'> <p> - The {@link org.apache.juneau.rest.annotation.RestResource#encoders @RestResource.encoders()} annotation can be used to associate character encoders with a servlet class. - Encoders can be used to enable various kinds of compression (e.g. <l>"gzip"</l>) on requests and responses based on the request <l>Accept-Encoding</l> - and <l>Content-Encoding</l> headers. + The {@link org.apache.juneau.rest.annotation.RestResource#encoders @RestResource.encoders()} annotation can + be used to associate character encoders with a servlet class. + Encoders can be used to enable various kinds of compression (e.g. <l>"gzip"</l>) on requests and responses + based on the request <l>Accept-Encoding</l> and <l>Content-Encoding</l> headers. </p> + <h6 class='figure'>Example:</h6> <p class='bcode'> <jc>// Servlet with automated support for GZIP compression</jc> @@ -1926,10 +2099,13 @@ Juneau defines the following encoders out-of-the-box: </p> <ul class='doctree'> - <li class='jac'>{@link org.apache.juneau.encoders.Encoder} + <li class='jac'> + {@link org.apache.juneau.encoders.Encoder} <ul> - <li class='jc'>{@link org.apache.juneau.encoders.GzipEncoder} - <li class='jc'>{@link org.apache.juneau.encoders.IdentityEncoder} + <li class='jc'> + {@link org.apache.juneau.encoders.GzipEncoder} + <li class='jc'> + {@link org.apache.juneau.encoders.IdentityEncoder} </ul> </ul> </div> @@ -1940,7 +2116,7 @@ <div class='topic'> <p> In the previous examples, there were several cases where embedded variables were contained within - annotation values: + annotation values: </p> <p class='bcode'> <ja>@RestResource</ja>( @@ -1955,16 +2131,20 @@ Features include: </p> <ul class='spaced-list'> - <li>Variables can be nested arbitrarily deep (e.g. <l>"$X{$Y{foo}}"</l>). - <li>Variables can contain arguments (e.g. <l>"$L{my.label,arg1,arg2}"</l>). - <li>Variables are recursively resolved. - <br>i.e., if a variable results to a value with another variable in it, that - variable will also be resolved. + <li> + Variables can be nested arbitrarily deep (e.g. <l>"$X{$Y{foo}}"</l>). + <li> + Variables can contain arguments (e.g. <l>"$L{my.label,arg1,arg2}"</l>). + <li> + Variables are recursively resolved. + <br>i.e., if a variable results to a value with another variable in it, that variable will also be + resolved. </ul> <p> String variables are implemented through the {@link org.apache.juneau.svl.VarResolver} class and one or more - {@link org.apache.juneau.svl.Var Vars}. + {@link org.apache.juneau.svl.Var Vars}. </p> + <h6 class='figure'>Example:</h6> <p class='bcode'> <jc>// Create a variable that resolves system properties (e.g. "$S{java.home}")</jc> @@ -1990,21 +2170,26 @@ The methods that define the var resolver on a servlet are: </p> <ul class='doctree'> - <li class='jac'>{@link org.apache.juneau.rest.RestServlet} - <ul> - <li class='jm'>{@link org.apache.juneau.rest.RestContext#getVarResolver()} - <br>Returns the <l>VarResolver</l> associated with a servlet. - <li class='jm'>{@link org.apache.juneau.rest.RestConfig#addVars(Class[])} - <br>The method used to create the servlet <l>VarResolver</l>. - <br>Subclasses can override this method to provide their own resolver. - <li class='jm'>{@link org.apache.juneau.rest.RestCallHandler#getSessionObjects(RestRequest)} - <br>Defines the session objects for the var resolver. - <br>Subclasses can override this method to provide additional session objects. - </ul> + <li class='jac'> + {@link org.apache.juneau.rest.RestServlet} + <ul> + <li class='jm'> + {@link org.apache.juneau.rest.RestContext#getVarResolver()} + <br>Returns the <l>VarResolver</l> associated with a servlet. + <li class='jm'> + {@link org.apache.juneau.rest.RestConfig#addVars(Class[])} + <br>The method used to create the servlet <l>VarResolver</l>. + <br>Subclasses can override this method to provide their own resolver. + <li class='jm'> + {@link org.apache.juneau.rest.RestCallHandler#getSessionObjects(RestRequest)} + <br>Defines the session objects for the var resolver. + <br>Subclasses can override this method to provide additional session objects. + </ul> + </li> </ul> <p> - The default {@link org.apache.juneau.rest.RestContext#getVarResolver()} method provides - support the following string variable types: + The default {@link org.apache.juneau.rest.RestContext#getVarResolver()} method provides support the + following string variable types: </p> <table class='styled'> <tr> @@ -2039,6 +2224,7 @@ <p> Subclasses can augment this list by adding their own variables. </p> + <h6 class='figure'>Example:</h6> <p class='bcode'> <ja>@Override</ja> <jc>/* RestServlet */</jc> @@ -2079,14 +2265,16 @@ </tr> <tr> <td><ck>$L{key}</ck><br><ck>$L{key,args...}</ck></td> - <td>Localized strings pulled from resource bundle. + <td> + Localized strings pulled from resource bundle. <br>Resolves to the value returned by {@link org.apache.juneau.rest.RestRequest#getMessage(String, Object...)}. <br>Can include message arguments (e.g. <l>"$L{my.localized.string, foo, bar}"</l>) </td> </tr> <tr> <td><ck>$R{key}</ck></td> - <td>Request-specific variables. + <td> + Request-specific variables. <br>Possible values: <ul> <li><ck>$R{attribute.X}</ck> - Value returned by {@link org.apache.juneau.rest.RestRequest#getAttribute(String)} converted to a string. @@ -2111,24 +2299,27 @@ </tr> <tr> <td><ck>$UE{...}</ck></td> - <td>URL-Encode the specified value. - <br>Takes the contents inside the varible and replaces it with a URL-encoded string. + <td> + URL-Encode the specified value. + <br>Takes the contents inside the variable and replaces it with a URL-encoded string. </td> </tr> </table> <p> - In addition to being used in annotation values, string variables can also be embedded in resource files retrieved - through the {@link org.apache.juneau.rest.RestRequest#getReaderResource(String,boolean)} method. + In addition to being used in annotation values, string variables can also be embedded in resource files + retrieved through the {@link org.apache.juneau.rest.RestRequest#getReaderResource(String,boolean)} method. This can often be useful for embedding localized strings inside HTML form pages. </p> <p> The <l>UrlEncodedFormResource</l> class in the Samples shows an example of using an HTML form page with - localized variables. When you bring it up in a browser, you see the following: + localized variables. + When you bring it up in a browser, you see the following: </p> <img class='bordered' src='doc-files/UrlEncodedForm.png'> <p> This HTML page is a static file located in the <l>org.apache.juneau.rest.samples</l> package. </p> + <h6 class='figure'>Contents of org/apache/juneau/server/samples/UrlEncodedForm.html</h6> <p class='bcode'> <xt><html></xt> @@ -2164,6 +2355,7 @@ <xt></body></xt> <xt></html></xt> </p> + <h6 class='figure'>Contents of UrlEncodedFormResource.java</h6> <p class='bcode'> <jd>/** @@ -2202,6 +2394,7 @@ } } </p> + <h6 class='figure'>Contents of UrlEncodedFormResource.properties</h6> <p class='bcode'> <cc>#-------------------------------------------------------------------------------- @@ -2217,9 +2410,12 @@ <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jc'>{@link org.apache.juneau.rest.ReaderResource} - <li class='jm'>{@link org.apache.juneau.rest.RestRequest#getReaderResource(String,boolean)} - <li class='jp'><a class='doclink' href='../svl/package-summary.html#TOC'>org.apache.juneau.svl</a> + <li class='jc'> + {@link org.apache.juneau.rest.ReaderResource} + <li class='jm'> + {@link org.apache.juneau.rest.RestRequest#getReaderResource(String,boolean)} + <li class='jp'> + <a class='doclink' href='../svl/package-summary.html#TOC'>org.apache.juneau.svl</a> </ul> </div> @@ -2228,12 +2424,15 @@ <h3 class='topic' onclick='toggle(this)'>4.15 - Static Files</h3> <div class='topic'> <p> - The {@link org.apache.juneau.rest.annotation.RestResource#staticFiles @RestResource.staticFiles()} annotation - is used to define paths and locations of statically-served files such as images or HTML documents. + The {@link org.apache.juneau.rest.annotation.RestResource#staticFiles @RestResource.staticFiles()} + annotation is used to define paths and locations of statically-served files such as images or HTML + documents. </p> <p> - The value is a JSON map of paths to packages/directories located on either the classpath or working directory. + The value is a JSON map of paths to packages/directories located on either the classpath or working + directory. </p> + <h6 class='figure'>Example:</h6> <p class='bcode'> <jk>package</jk> com.foo.mypackage; @@ -2250,18 +2449,24 @@ If not found, then an attempt is made to find the class in the Java working directory. </p> <p> - In the example above, given a GET request to <l>/myresource/htdocs/foobar.html</l>, the servlet will attempt to find the <l>foobar.html</l> file - in the following ordered locations: + In the example above, given a GET request to <l>/myresource/htdocs/foobar.html</l>, the servlet will + attempt to find the <l>foobar.html</l> file in the following ordered locations: </p> <ol> <li><l>com.foo.mypackage.docs</l> package. - <li><l>org.apache.juneau.rest.docs</l> package (since <l>RestServletDefault</l> is in <l>org.apache.juneau.rest</l>). + <li><l>org.apache.juneau.rest.docs</l> package (since <l>RestServletDefault</l> is in + <l>org.apache.juneau.rest</l>). <li><l>[working-dir]/docs</l> directory. </ol> + <h6 class='topic'>Notes:</h6> <ul class='spaced-list'> - <li>Mappings are cumulative from parent to child. Child resources can override mappings made on parent resources. - <li>The media type on the response is determined by the {@link org.apache.juneau.rest.RestContext#getMediaTypeForName(String)} method. + <li> + Mappings are cumulative from parent to child. Child resources can override mappings made on parent + resources. + <li> + The media type on the response is determined by the + {@link org.apache.juneau.rest.RestContext#getMediaTypeForName(String)} method. </ul> </div> @@ -2270,21 +2475,27 @@ <h3 class='topic' onclick='toggle(this)'>4.16 - Listener Methods</h3> <div class='topic'> <p> - Various convenience listener methods are provided on the {@link org.apache.juneau.rest.RestCallHandler} class - that subclasses can use to intercept requests: + Various convenience listener methods are provided on the {@link org.apache.juneau.rest.RestCallHandler} + class that subclasses can use to intercept requests: </p> <ul class='doctree'> - <li class='jac'>{@link org.apache.juneau.rest.RestCallHandler} - <ul> - <li class='jm'>{@link org.apache.juneau.rest.RestCallHandler#onPreCall(RestRequest) onPreCall(RestRequest)} - <br>Callback method that gets invoked right before the REST Java method is invoked. - <li class='jm'>{@link org.apache.juneau.rest.RestCallHandler#onPostCall(RestRequest,RestResponse) onPostCall(RestRequest,RestResponse)} - <br>Callback method that gets invoked right after the REST Java method is invoked, but before the serializer is invoked. - <li class='jm'>{@link org.apache.juneau.rest.RestCallHandler#onSuccess(RestRequest,RestResponse,long) onSuccess(RestRequest,RestResponse,long)} - <br>Callback method for listening for successful completion of requests. - <li class='jm'>{@link org.apache.juneau.rest.RestLogger#onError(HttpServletRequest,HttpServletResponse,RestException) onError(HttpServletRequest,HttpServletResponse,RestExce
<TRUNCATED>
