juneau-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From James Bognar <jamesbog...@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:13:22 GMT
oops...yes.  Those were supposed to go into Git.

On Fri, Sep 8, 2017 at 9:10 PM, John D. Ament <johndament@apache.org> wrote:

> 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