juneau-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "John D. Ament" <johndam...@apache.org>
Subject Re: svn commit: r21540 [20/27] - in /release/incubator/juneau: juneau-rest-client/ juneau-rest-client/.settings/ juneau-rest-client/bin/ juneau-rest-client/src/ juneau-rest-client/src/main/ juneau-rest-client/src/main/java/ juneau-rest-client/src/main/java...
Date Sat, 09 Sep 2017 01:10:44 GMT
James,

Did you check these in by mistake?

John

On Fri, Sep 8, 2017 at 7:25 PM <jamesbognar@apache.org> wrote:

> Added:
> release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/package.html
>
> ==============================================================================
> ---
> release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/package.html
> (added)
> +++
> release/incubator/juneau/juneau-rest-server/src/main/java/org/apache/juneau/rest/package.html
> Fri Sep  8 23:25:34 2017
> @@ -0,0 +1,3860 @@
> +<!DOCTYPE HTML>
> +<!--
>
> +/***************************************************************************************************************************
> + * Licensed to the Apache Software Foundation (ASF) under one or more
> contributor license agreements.  See the NOTICE file
> + * distributed with this work for additional information regarding
> copyright ownership.  The ASF licenses this file
> + * to you under the Apache License, Version 2.0 (the "License"); you may
> not use this file except in compliance
> + * with the License.  You may obtain a copy of the License at
> + *
> + *  http://www.apache.org/licenses/LICENSE-2.0
> + *
> + * Unless required by applicable law or agreed to in writing, software
> distributed under the License is distributed on an
> + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
> express or implied.  See the License for the
> + * specific language governing permissions and limitations under the
> License.
> + *
> +
> ***************************************************************************************************************************/
> + -->
> +<html>
> +<head>
> +       <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
> +       <style type="text/css">
> +               /* For viewing in Page Designer */
> +               @IMPORT url("../../../../../javadoc.css");
> +
> +               /* For viewing in REST interface */
> +               @IMPORT url("../htdocs/javadoc.css");
> +               body {
> +                       margin: 20px;
> +               }
> +       </style>
> +       <script>
> +               /* Replace all @code and @link tags. */
> +               window.onload = function() {
> +                       document.body.innerHTML =
> document.body.innerHTML.replace(/\{\@code ([^\}]+)\}/g, '<code>$1</code>');
> +                       document.body.innerHTML =
> document.body.innerHTML.replace(/\{\@link (([^\}]+)\.)?([^\.\}]+)\}/g,
> '<code>$3</code>');
> +               }
> +       </script>
> +</head>
> +<body>
> +<p>REST Servlet API</p>
> +
> +<script>
> +       function toggle(x) {
> +               var div = x.nextSibling;
> +               while (div != null && div.nodeType != 1)
> +                       div = div.nextSibling;
> +               if (div != null) {
> +                       var d = div.style.display;
> +                       if (d == 'block' || d == '') {
> +                               div.style.display = 'none';
> +                               x.className += " closed";
> +                       } else {
> +                               div.style.display = 'block';
> +                               x.className =
> x.className.replace(/(?:^|\s)closed(?!\S)/g , '' );
> +                       }
> +               }
> +       }
> +</script>
> +
> +<p>
> +       Defines an API for defining REST resources as servlets.
> +</p>
> +
> +<a id='TOC'></a><h5 class='toc'>Table of Contents</h5>
> +<ol class='toc'>
> +       <li><p><a class='doclink' href='#Intro'>Introduction</a></p>
> +       <li><p><a class='doclink' href='#HelloWorldResource'>Hello World
> Example</a></p>
> +       <li><p><a class='doclink' href='#ClassHierarchy'>Class
> Hierarchy</a></p>
> +       <li><p><a class='doclink' href='#RestResources'>REST
> Servlets</a></p>
> +       <ol>
> +               <li><p><a class='doclink'
> href='#RestResources.MethodSignature'>REST Java Method Signature</a></p>
> +               <ol>
> +                       <li><p><a class='doclink'
> href='#RestResources.MethodSignature.Path'>Path</a></p>
> +                       <li><p><a class='doclink'
> href='#RestResources.MethodSignature.Matchers'>Matchers</a></p>
> +               </ol>
> +               <li><p><a class='doclink'
> href='#RestResources.RequestContent'>Request Content</a></p>
> +       <ol>
> +                       <li><p><a class='doclink'
> href='#RestResources.RequestContent.FormPosts'>Form Posts</a></p>
> +                       <li><p><a class='doclink'
> href='#RestResources.RequestContent'>Multipart Form Posts</a></p>
> +               </ol>
> +               <li><p><a class='doclink'
> href='#RestResources.ResponseContent'>Response Content</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.RestHooks'>Lifecycle Hooks</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.OptionsPages'>OPTIONS Pages</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Serializers'>Serializers</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Parsers'>Parsers</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Properties'>Properties</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Transforms'>Transforms</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Guards'>Guards</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Converters'>Converters</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Children'>Child Resources</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Labels'>Localized Messages</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Encoders'>Encoders</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.SvlVars'>SVL Vars</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.StaticFiles'>Static Files</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Listeners'>Listener Methods</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Stylesheet'>Stylesheet</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Headers'>Default Headers</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Errors'>Handling Errors / Logging</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.ConfigFile'>Configuration Files</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.Inheritence'>Annotation Inheritance</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.HttpStatusCodes'>HTTP Status Codes</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.OverloadedHttpMethods'>Overloaded HTTP Methods</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.BuildInParams'>Built-In Parameters</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.CustomSerializersParsers'>Defining your own
> serializers/parsers</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.ResponseHandlers'>Response Handlers</a></p>
> +               <li><p><a class='doclink'
> href='#RestResources.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
> Convertible From Strings</a></p>
> +       <li><p><a class='doclink' href='#AddressBookResource'>Address Book
> Resource</a></p>
> +</ol>
> +
> +<!--
> ========================================================================================================
> -->
> +<a id="Intro"></a>
> +<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.
> +       </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.
> +       </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.
> +               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.
> +                       <ul>
> +                               <li>Extensible design that provides
> ability to override existing content type handlers, or add the
> +                                       ability to handle other kinds of
> content types.
> +                       </ul>
> +               <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>
> +               <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 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 500 errors on uncaught
> exceptions.
> +                       </ul>
> +               <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>&amp;Accept=text/xml</l>).
> +                               <li>Ability to pass HTTP content on
> PUT/POST requests as a URL GET parameter
> +                                       (e.g.
> <l>&amp;content={foo:"bar"}</l>).
> +                               <li>Ability to simulate non-GET requests
> using a <l>&amp;method</l> GET parameter
> +                                       (e.g. <l>&amp;method=POST</l>).
> +                               <li>Ability to force <js>"text/plain"</js>
> on response using GET parameter <l>&amp;plainText=true</l>.
> +                       </ul>
> +               <li>
> +                       Ability to implement overloaded HTTP methods
> through the use of the <l>&amp;method</l> attribute
> +                       (e.g. <l>&amp;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.
> +       </p>
> +</div>
> +
> +<!--
> ========================================================================================================
> -->
> +<a id="HelloWorldResource"></a>
> +<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}.
> +       </p>
> +       <p>
> +               In this example, we define a resource called
> <l>HelloWorldResource</l>.
> +               This example is located in the
> <l>microservice-samples-project.zip</l> project.
> +               It's assumed the reader is familiar with defining servlets
> in web applications.
> +       </p>
> +       <p>
> +               Like any servlet, we could define our resource in the
> <l>web.xml</l> file of the web application like so...
> +       </p>
> +       <p class='bcode'>
> +       <xt>&lt;?xml</xt> <xa>version</xa>=<xs>"1.0"</xs>
> <xa>encoding</xa>=<xs>"UTF-8"</xs><xt>?&gt;</xt>
> +       <xt>&lt;web-app</xt> <xa>version</xa>=<xs>"2.3"</xs><xt>&gt;</xt>
> +               <xt>&lt;servlet&gt;</xt>
> +
>  <xt>&lt;servlet-name&gt;</xt>HelloWorldResource<xt>&lt;/servlet-name&gt;</xt>
> +
>  <xt>&lt;servlet-class&gt;</xt>com.foo.sample.HelloWorldResource<xt>&lt;/servlet-class&gt;</xt>
> +               <xt>&lt;/servlet&gt;</xt>
> +               <xt>&lt;servlet-mapping&gt;</xt>
> +
>  <xt>&lt;servlet-name&gt;</xt>HelloWorldResource<xt>&lt;/servlet-name&gt;</xt>
> +
>  <xt>&lt;url-pattern&gt;</xt>/*<xt>&lt;/url-pattern&gt;</xt>
> +               <xt>&lt;/servlet-mapping&gt;</xt>
> +       <xt>&lt;/web-app&gt;</xt>
> +       </p>
> +       <p>
> +               Our servlet code is shown below:
> +       </p>
> +       <p class='bcode'>
> +       <jd>/**
> +        * Sample REST resource that prints out a simple "Hello world!"
> message.
> +        */</jd>
> +       <ja>@RestResource</ja>(
> +               messages=<js>"nls/HelloWorldResource"</js>,
> +               htmldoc=<ja>@HtmlDoc</ja>(
> +                       links={
> +                               <js>"up: request:/.."</js>,
> +                               <js>"options:
> servlet:/?method=OPTIONS"</js>
> +                       }
> +               )
> +       )
> +       <jk>public class</jk> HelloWorldResource <jk>extends</jk> Resource
> {
> +
> +               <jd>/** GET request handler */</jd>
> +               <ja>@RestMethod</ja>(name=<js>"GET"</js>,
> path=<js>"/*"</js>)
> +               <jk>public</jk> String sayHello() {
> +                       <jk>return</jk> <js>"Hello world!"</js>;
> +               }
> +       }
> +       </p>
> +       <p>
> +               The <l>messages</l> annotation points to a properties file
> on the classpath whose contents are shown below:
> +       </p>
> +       <p class='bcode'>
> +
>  <cc>#--------------------------------------------------------------------------------
> +       # HelloWorldResource labels
> +
>  #--------------------------------------------------------------------------------</cc>
> +       <ck>label</ck> = <cv>Hello World sample resource</cv>
> +       <ck>description</ck> = <cv>Simplest possible resource</cv>
> +       <ck>sayHello</ck> = <cv>Responds with "Hello world!"</cv>
> +       </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, ...).
> +               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.
> +       </p>
> +       <p>
> +               If you were to start up this servlet and view it with a
> browser, you would see this:
> +       </p>
> +       <img class='bordered' src="doc-files/HelloWorldResource1.png">
> +       <p>
> +               The Juneau REST interface is designed to make it easy to
> interact with resources using nothing but a browser.
> +               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='spaced-list'>
> +               <li>
> +                       <l>&amp;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>&amp;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>
> +               Using the <l>plainText</l> parameter, we can view the HTML
> as plain text...
> +       </p>
> +       <img class='bordered' src="doc-files/HelloWorldResource2.png">
> +       <p>
> +               You'll notice that the HTML view has a simple stylesheet
> associated with it to improve the look of the interface.
> +               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).
> +       </p>
> +       <p>
> +               Let's use the <l>&amp;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....
> +       </p>
> +       <img class='bordered' src="doc-files/HelloWorldResource3.png">
> +       <p>
> +               ...or as <l>XML</l>...
> +       </p>
> +       <img class='bordered' src="doc-files/HelloWorldResource4.png">
> +       <p>
> +               ...or any of the other supported languages.
> +       </p>
> +       <p>
> +               If you click the OPTIONS link on the page, you'll see the
> results from an <l>HTTP OPTIONS</l> request:
> +       </p>
> +       <img class='bordered'
> src="doc-files/HelloWorldResourceOptions.png">
> +       <p>
> +               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 serialized to any of the
> supported languages, like Swagger JSON.
> +       </p>
> +       <img class='bordered'
> src="doc-files/HelloWorldResourceOptionsJson.png">
> +</div>
> +
> +<!--
> ========================================================================================================
> -->
> +<a id="ClassHierarchy"></a>
> +<h2 class='topic' onclick='toggle(this)'>3 - Class Hierarchy</h2>
> +<div class='topic'>
> +       <p>
> +               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.
> +                                       <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 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>
> +                                       </ul>
> +                               </li>
> +                       </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.
> +       </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:
> +       </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>
> +               <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>
> +               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>
> +               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>
> +
> +       <h6 class='figure'>Valid Accept headers for RestServletDefault</h6>
> +       <table class='styled'>
> +               <tr>
> +                       <th>Accept</th>
> +                       <th>Content-Type</th>
> +                       <th>Serializer</th>
> +               </tr>
> +               <tr>
> +                       <td class='code'>application/json<br>text/json</td>
> +                       <td class='code'>application/json</td>
> +                       <td>{@link
> org.apache.juneau.json.JsonSerializer}</td>
> +               </tr>
> +               <tr>
> +                       <td
> class='code'>application/json+simple<br>text/json+simple</td>
> +                       <td class='code'>application/json</td>
> +                       <td>{@link
> org.apache.juneau.json.JsonSerializer.Simple}</td>
> +               </tr>
> +               <tr>
> +                       <td
> class='code'>application/json+schema<br>text/json+schema</td>
> +                       <td class='code'>application/json</td>
> +                       <td>{@link
> org.apache.juneau.json.JsonSchemaSerializer}</td>
> +               </tr>
> +               <tr>
> +                       <td class='code'>text/xml</td>
> +                       <td class='code'>text/xml</td>
> +                       <td>{@link
> org.apache.juneau.xml.XmlDocSerializer}</td>
> +               </tr>
> +               <tr>
> +                       <td class='code'>text/xml+schema</td>
> +                       <td class='code'>text/xml</td>
> +                       <td>{@link
> org.apache.juneau.xml.XmlSchemaDocSerializer}</td>
> +               </tr>
> +               <tr>
> +                       <td class='code'>text/html</td>
> +                       <td class='code'>text/html</td>
> +                       <td>{@link
> org.apache.juneau.html.HtmlDocSerializer}</td>
> +               </tr>
> +               <tr>
> +                       <td class='code'>text/html+stripped</td>
> +                       <td class='code'>text/html</td>
> +                       <td>{@link
> org.apache.juneau.html.HtmlStrippedDocSerializer}</td>
> +               </tr>
> +               <tr>
> +                       <td class='code'>text/uon</td>
> +                       <td class='code'>text/uon</td>
> +                       <td>{@link
> org.apache.juneau.uon.UonSerializer}</td>
> +               </tr>
> +               <tr>
> +                       <td
> class='code'>application/x-www-form-urlencoded</td>
> +                       <td
> class='code'>application/x-www-form-urlencoded</td>
> +                       <td>{@link
> org.apache.juneau.urlencoding.UrlEncodingSerializer}</td>
> +               </tr>
> +               <tr>
> +                       <td class='code'>text/xml+soap</td>
> +                       <td class='code'>text/xml</td>
> +                       <td>{@link
> org.apache.juneau.soap.SoapXmlSerializer}</td>
> +               </tr>
> +               <tr>
> +                       <td class='code'>text/plain</td>
> +                       <td class='code'>text/plain</td>
> +                       <td>{@link
> org.apache.juneau.plaintext.PlainTextSerializer}</td>
> +               </tr>
> +               <tr>
> +                       <td
> class='code'>application/x-java-serialized-object</td>
> +                       <td
> class='code'>application/x-java-serialized-object</td>
> +                       <td>{@link
> org.apache.juneau.jso.JsoSerializer}</td>
> +               </tr>
> +       </table>
> +
> +       <h6 class='figure'>Valid Content-Type headers for
> RestServletDefault</h6>
> +       <table class='styled'>
> +               <tr>
> +                       <th>Content-Type</th>
> +                       <th>Parser</th>
> +               </tr>
> +               <tr>
> +                       <td class='code'>application/json<br>text/json</td>
> +                       <td>{@link org.apache.juneau.json.JsonParser}</td>
> +               </tr>
> +               <tr>
> +                       <td class='code'>text/xml<br>application/xml</td>
> +                       <td>{@link org.apache.juneau.xml.XmlParser}</td>
> +               </tr>
> +               <tr>
> +                       <td
> class='code'>text/html<br>text/html+stripped</td>
> +                       <td>{@link org.apache.juneau.html.HtmlParser}</td>
> +               </tr>
> +               <tr>
> +                       <td class='code'>text/uon</td>
> +                       <td>{@link org.apache.juneau.uon.UonParser}</td>
> +               </tr>
> +               <tr>
> +                       <td
> class='code'>application/x-www-form-urlencoded</td>
> +                       <td>{@link
> org.apache.juneau.urlencoding.UrlEncodingParser}</td>
> +               </tr>
> +               <tr>
> +                       <td class='code'>text/plain</td>
> +                       <td>{@link
> org.apache.juneau.plaintext.PlainTextParser}</td>
> +               </tr>
> +       </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.
> +               This is what produces the output for the OPTIONS page on
> the Hello World sample above.
> +       </p>
> +
> +       <h6 class='topic'>Additional Information</h6>
> +       <ul class='doctree'>
> +               <li class='jac'>
> +                       {@link org.apache.juneau.rest.RestServletDefault}
> +       </ul>
> +
> +       <!--
> ========================================================================================================
> -->
> +       <a id="RestResources.MethodSignature"></a>
> +       <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.
> +                       The annotation allows the framework to identify
> the available REST methods through reflection.
> +               </p>
> +               <p class='bcode'>
> +       <jd>/** GET request handler */</jd>
> +       <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/"</js>)
> +       <jk>public</jk> String sayHello() {
> +               <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.
> +                       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.
> +               </p>
> +               <p class='bcode'>
> +       <jc>// Equivalent method 1</jc>
> +       <ja>@RestMethod</ja>(name=<js>"GET"</js>)
> +       <jk>public void</jk> doGet(RestResponse res) {
> +               res.setOutput(<js>"Hello World!"</js>);
> +       }
> +
> +       <jc>// Equivalent method 2</jc>
> +       <ja>@RestMethod</ja>(name=<js>"GET"</js>)
> +       <jk>public</jk> String doGet() {
> +               <jk>return</jk> <js>"Hello World!"</js>;
> +       }
> +               </p>
> +               <p>
> +                       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}
> +                               <br>Represents an HTTP redirect response.
> +                       <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}
> +                               <br>Interface that identifies that an
> object can be serialized directly to a writer.
> +                       <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).
> +               </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:
> +                               <ul>
> +                                       <li>Request/response objects:
> +                                               <ul>
> +                                                       <li>{@link
> org.apache.juneau.rest.RestRequest} - The request object.
> +                                                       <li>{@link
> javax.servlet.http.HttpServletRequest} - The superclass of
> <code>RestRequest</code>.
> +                                                       <li>{@link
> org.apache.juneau.rest.RestResponse} - The response object.
> +                                                       <li>{@link
> javax.servlet.http.HttpServletResponse} - The superclass of
> <code>RestResponse</code>.
> +                                               </ul>
> +                                       <li>Parsed request header values:
> +                                               <ul>
> +                                                       <li>{@link
> org.apache.juneau.http.Accept}
> +                                                       <li>{@link
> org.apache.juneau.http.AcceptCharset}
> +                                                       <li>{@link
> org.apache.juneau.http.AcceptEncoding}
> +                                                       <li>{@link
> org.apache.juneau.http.AcceptLanguage}
> +                                                       <li>{@link
> org.apache.juneau.http.Authorization}
> +                                                       <li>{@link
> org.apache.juneau.http.CacheControl}
> +                                                       <li>{@link
> org.apache.juneau.http.Connection}
> +                                                       <li>{@link
> org.apache.juneau.http.ContentLength}
> +                                                       <li>{@link
> org.apache.juneau.http.ContentType}
> +                                                       <li>{@link
> org.apache.juneau.http.Date}
> +                                                       <li>{@link
> org.apache.juneau.http.Expect}
> +                                                       <li>{@link
> org.apache.juneau.http.From}
> +                                                       <li>{@link
> org.apache.juneau.http.Host}
> +                                                       <li>{@link
> org.apache.juneau.http.IfMatch}
> +                                                       <li>{@link
> org.apache.juneau.http.IfModifiedSince}
> +                                                       <li>{@link
> org.apache.juneau.http.IfNoneMatch}
> +                                                       <li>{@link
> org.apache.juneau.http.IfRange}
> +                                                       <li>{@link
> org.apache.juneau.http.IfUnmodifiedSince}
> +                                                       <li>{@link
> org.apache.juneau.http.MaxForwards}
> +                                                       <li>{@link
> org.apache.juneau.http.Pragma}
> +                                                       <li>{@link
> org.apache.juneau.http.ProxyAuthorization}
> +                                                       <li>{@link
> org.apache.juneau.http.Range}
> +                                                       <li>{@link
> org.apache.juneau.http.Referer}
> +                                                       <li>{@link
> org.apache.juneau.http.TE}
> +                                                       <li>{@link
> org.apache.juneau.http.UserAgent}
> +                                                       <li>{@link
> org.apache.juneau.http.Upgrade}
> +                                                       <li>{@link
> org.apache.juneau.http.Via}
> +                                                       <li>{@link
> org.apache.juneau.http.Warning}
> +                                                       <li>{@link
> java.util.TimeZone}
> +                                               </ul>
> +                                       <li>Direct streams on
> request/response:
> +                                               <ul>
> +                                                       <li>{@link
> java.io.InputStream}
> +                                                       <li>{@link
> javax.servlet.ServletInputStream}
> +                                                       <li>{@link
> java.io.Reader}
> +                                                       <li>{@link
> java.io.OutputStream}
> +                                                       <li>{@link
> javax.servlet.ServletOutputStream}
> +                                                       <li>{@link
> java.io.Writer}
> +                                               </ul>
> +                                       <li>Localization:
> +                                               <ul>
> +                                                       <li>{@link
> java.util.ResourceBundle} - Client-localized resource bundle.
> +                                                       <li>{@link
> org.apache.juneau.utils.MessageBundle} - A resource bundle with additional
> features.
> +                                                       <li>{@link
> java.util.Locale} - Client locale.
> +                                               </ul>
> +                                       <li>Request APIs:
> +                                               <ul>
> +                                                       <li>{@link
> org.apache.juneau.rest.RequestHeaders} - API for accessing request headers.
> +                                                       <li>{@link
> org.apache.juneau.rest.RequestQuery} - API for accessing request query
> parameters.
> +                                                       <li>{@link
> org.apache.juneau.rest.RequestFormData} - API for accessing request form
> data.
> +                                                       <li>{@link
> org.apache.juneau.rest.RequestPathMatch} - API for accessing path variables.
> +                                                       <li>{@link
> org.apache.juneau.rest.RequestBody} - API for accessing request body.
> +                                               </ul>
> +                                       <li>Other:
> +                                               <ul>
> +                                                       <li>{@link
> org.apache.juneau.http.HttpMethod} - The method name matched (when using
> <code><ja>@RestMethod</ja>(name=<js>"*"</js>)</code>)
> +                                                       <li>{@link
> java.util.logging.Logger} - The logger to use for logging.
> +                                                       <li>{@link
> org.apache.juneau.internal.JuneauLogger} - Logger with additional features.
> +                                                       <li>{@link
> org.apache.juneau.rest.RestContext} - The resource read-only context.
> +                                                       <li>{@link
> org.apache.juneau.parser.Parser} - The parser matching the request content
> type.
> +                                                       <li>{@link
> org.apache.juneau.dto.swagger.Swagger} - The auto-generated Swagger doc.
> +                                                       <li>{@link
> org.apache.juneau.ini.ConfigFile} - The external config file for the
> resource.
> +                                               </ul>
> +                               </ul>
> +                       <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.
> +                                       <li>{@link
> org.apache.juneau.rest.annotation.HasFormData @HasFormData} - Denotes
> whether the form data parameter exists.
> +                                       <li>{@link
> org.apache.juneau.rest.annotation.Query @Query} - Query parameters.  Using
> this prevents the HTTP body from being processed as a URL-Encoded form post.
> +                                       <li>{@link
> org.apache.juneau.rest.annotation.HasQuery @HasQuery} - Denotes whether the
> query parameter exists.
> +                                       <li>{@link
> org.apache.juneau.rest.annotation.Header @Header} - A header value.
> +                                       <li>{@link
> org.apache.juneau.rest.annotation.Method @Method} - The HTTP method name.
> +                                       <li>{@link
> org.apache.juneau.rest.annotation.PathRemainder @PathRemainder} - The
> remainder value after path pattern match.
> +                                       <li>{@link
> org.apache.juneau.rest.annotation.Body @Body} - The HTTP content parsed as
> a POJO.
> +                                       <li>{@link
> org.apache.juneau.rest.annotation.Messages @Messages} - The resource bundle
> for the servlet localized to the language on the request.
> +                                       <li>{@link
> org.apache.juneau.rest.annotation.Properties @Properties} - The
> serializer/parser/servlet properties so they can be read or altered on the
> request.
> +                               </ul>
> +               </ul>
> +               <p class='bcode'>
> +       <jc>// Example GET request using annotated attributes</jc>
> +       <ja>@RestMethod</ja>(name=<js>"GET"</js>,
> path=<js>"/example1/{a1}/{a2}/{a3}/*

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message