James, Did you check these in by mistake? John On Fri, Sep 8, 2017 at 7:25 PM 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 @@ > + > + > + > + > + > + > + > + > + > +

REST Servlet API

> + > + > + > +

> + Defines an API for defining REST resources as servlets. > +

> + > +
Table of Contents
> +
    > +
  1. Introduction

    > +
  2. Hello World > Example

    > +
  3. Class > Hierarchy

    > +
  4. REST > Servlets

    > +
      > +
    1. href='#RestResources.MethodSignature'>REST Java Method Signature

      > +
        > +
      1. href='#RestResources.MethodSignature.Path'>Path

        > +
      2. href='#RestResources.MethodSignature.Matchers'>Matchers

        > +
      > +
    2. href='#RestResources.RequestContent'>Request Content

      > +
        > +
      1. href='#RestResources.RequestContent.FormPosts'>Form Posts

        > +
      2. href='#RestResources.RequestContent'>Multipart Form Posts

        > +
      > +
    3. href='#RestResources.ResponseContent'>Response Content

      > +
    4. href='#RestResources.RestHooks'>Lifecycle Hooks

      > +
    5. href='#RestResources.OptionsPages'>OPTIONS Pages

      > +
    6. href='#RestResources.Serializers'>Serializers

      > +
    7. href='#RestResources.Parsers'>Parsers

      > +
    8. href='#RestResources.Properties'>Properties

      > +
    9. href='#RestResources.Transforms'>Transforms

      > +
    10. href='#RestResources.Guards'>Guards

      > +
    11. href='#RestResources.Converters'>Converters

      > +
    12. href='#RestResources.Children'>Child Resources

      > +
    13. href='#RestResources.Labels'>Localized Messages

      > +
    14. href='#RestResources.Encoders'>Encoders

      > +
    15. href='#RestResources.SvlVars'>SVL Vars

      > +
    16. href='#RestResources.StaticFiles'>Static Files

      > +
    17. href='#RestResources.Listeners'>Listener Methods

      > +
    18. href='#RestResources.Stylesheet'>Stylesheet

      > +
    19. href='#RestResources.Headers'>Default Headers

      > +
    20. href='#RestResources.Errors'>Handling Errors / Logging

      > +
    21. href='#RestResources.ConfigFile'>Configuration Files

      > +
    22. href='#RestResources.Inheritence'>Annotation Inheritance

      > +
    23. href='#RestResources.HttpStatusCodes'>HTTP Status Codes

      > +
    24. href='#RestResources.OverloadedHttpMethods'>Overloaded HTTP Methods

      > +
    25. href='#RestResources.BuildInParams'>Built-In Parameters

      > +
    26. href='#RestResources.CustomSerializersParsers'>Defining your own > serializers/parsers

      > +
    27. href='#RestResources.ResponseHandlers'>Response Handlers

      > +
    28. href='#RestResources.OtherNotes'>Other Notes

      > +
    > +
  5. Using with OSGi

    > +
  6. POJOs > Convertible From Strings

    > +
  7. Address Book > Resource

    > +
> + > + > + > +

1 - Introduction

> +
> +

> + The juneau-rest.jar 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. > +

> +

> + 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 Accept or > Content-Type or Accept-Encoding (etc...) > + header values are because those details are all handled by > the framework. > +

> +

> + 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. > +

> + > +
Features
> + > +

> + Many of the examples in this document are pulled directly > from the microservice-samples-project.zip > + project. > +

> +
> + > + > + > +

2 - Hello World Example

> +
> +

> + 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}. > +

> +

> + In this example, we define a resource called > HelloWorldResource. > + This example is located in the > microservice-samples-project.zip project. > + It's assumed the reader is familiar with defining servlets > in web applications. > +

> +

> + Like any servlet, we could define our resource in the > web.xml file of the web application like so... > +

> +

> + <?xml version="1.0" > encoding="UTF-8"?> > + <web-app version="2.3"> > + <servlet> > + > <servlet-name>HelloWorldResource</servlet-name> > + > <servlet-class>com.foo.sample.HelloWorldResource</servlet-class> > + </servlet> > + <servlet-mapping> > + > <servlet-name>HelloWorldResource</servlet-name> > + > <url-pattern>/*</url-pattern> > + </servlet-mapping> > + </web-app> > +

> +

> + Our servlet code is shown below: > +

> +

> + /** > + * Sample REST resource that prints out a simple "Hello world!" > message. > + */ > + @RestResource( > + messages="nls/HelloWorldResource", > + htmldoc=@HtmlDoc( > + links={ > + "up: request:/..", > + "options: > servlet:/?method=OPTIONS" > + } > + ) > + ) > + public class HelloWorldResource extends Resource > { > + > + /** GET request handler */ > + @RestMethod(name="GET", > path="/*") > + public String sayHello() { > + return "Hello world!"; > + } > + } > +

> +

> + The messages annotation points to a properties file > on the classpath whose contents are shown below: > +

> +

> + > #-------------------------------------------------------------------------------- > + # HelloWorldResource labels > + > #-------------------------------------------------------------------------------- > + label = Hello World sample resource > + description = Simplest possible resource > + sayHello = Responds with "Hello world!" > +

> +

> + 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... > +

> +

> + 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. > +

> +

> + If you were to start up this servlet and view it with a > browser, you would see this: > +

> + > +

> + 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... > +

> + > +

> + Using the plainText parameter, we can view the HTML > as plain text... > +

> + > +

> + 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. > +

> +

> + When accessed through a browser, the content type will > default to HTML (based on the value of the Accept > + HTTP header). > +

> +

> + Let's use the &Accept URL parameter to override > the Accept HTTP header to view this servlet > + in other formats... > +

> +

> + In the case of JSON, we're serialize a single > string, so it gets rendered as a JSON fragment.... > +

> + > +

> + ...or as XML... > +

> + > +

> + ...or any of the other supported languages. > +

> +

> + If you click the OPTIONS link on the page, you'll see the > results from an HTTP OPTIONS request: > +

> + src="doc-files/HelloWorldResourceOptions.png"> > +

> + 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. > +

> + src="doc-files/HelloWorldResourceOptionsJson.png"> > +
> + > + > + > +

3 - Class Hierarchy

> +
> +

> + The class hierarchy for the REST servlet class is shown > below: > +

> + > +

> + 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. > +

> +

> + The {@link org.apache.juneau.rest.RestRequest} and {@link > org.apache.juneau.rest.RestResponse} classes > + described later also extend from their servlet equivalents: > +

> + > +
> + > + > + > +

4 - REST Servlets

> +
> +

> + Since REST servlets are subclasses of HttpServlet, > they can be deployed in a J2EE container like any > + other servlet, typically inside a web.xml file. > + The REST servlet framework does not depend on any > classloader scanning or external setup other than > + registering the servlet with the J2EE container. > +

> +

> + REST servlets can also be deployed by declaring them as > children of other REST servlets (described later). > +

> +

> + 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}. > +

> +

> + 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 Accept and > + Content-Type types. > +

> + > +
Valid Accept headers for RestServletDefault
> + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > +
AcceptContent-TypeSerializer
application/json
text/json
application/json{@link > org.apache.juneau.json.JsonSerializer}
class='code'>application/json+simple
text/json+simple
application/json{@link > org.apache.juneau.json.JsonSerializer.Simple}
class='code'>application/json+schema
text/json+schema
application/json{@link > org.apache.juneau.json.JsonSchemaSerializer}
text/xmltext/xml{@link > org.apache.juneau.xml.XmlDocSerializer}
text/xml+schematext/xml{@link > org.apache.juneau.xml.XmlSchemaDocSerializer}
text/htmltext/html{@link > org.apache.juneau.html.HtmlDocSerializer}
text/html+strippedtext/html{@link > org.apache.juneau.html.HtmlStrippedDocSerializer}
text/uontext/uon{@link > org.apache.juneau.uon.UonSerializer}
class='code'>application/x-www-form-urlencoded class='code'>application/x-www-form-urlencoded{@link > org.apache.juneau.urlencoding.UrlEncodingSerializer}
text/xml+soaptext/xml{@link > org.apache.juneau.soap.SoapXmlSerializer}
text/plaintext/plain{@link > org.apache.juneau.plaintext.PlainTextSerializer}
class='code'>application/x-java-serialized-object class='code'>application/x-java-serialized-object{@link > org.apache.juneau.jso.JsoSerializer}
> + > +
Valid Content-Type headers for > RestServletDefault
> + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > + > +
Content-TypeParser
application/json
text/json
{@link org.apache.juneau.json.JsonParser}
text/xml
application/xml
{@link org.apache.juneau.xml.XmlParser}
class='code'>text/html
text/html+stripped
{@link org.apache.juneau.html.HtmlParser}
text/uon{@link org.apache.juneau.uon.UonParser}
class='code'>application/x-www-form-urlencoded{@link > org.apache.juneau.urlencoding.UrlEncodingParser}
text/plain{@link > org.apache.juneau.plaintext.PlainTextParser}
> +

> + {@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. > +

> + > +
Additional Information
> + > + > + > + > +

4.1 - REST Java Method > Signature

> +
> +

> + 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. > +

> +

> + /** GET request handler */ > + @RestMethod(name="GET", path="/") > + public String sayHello() { > + return "Hello world!"; > + } > +

> + > +
Method Name
> +

> + 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 doFoo(...) methods that differ only by > + parameters. > + If you're not using messages for NLS support, then > name them whatever you want! > +

> + > +
Method Return Type
> +

> + The return type can be any serializable POJO as > defined in + > href='../../../../overview-summary.html#Core.PojoCategories'>POJO > Categories. > + It can also be void 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. > +

> +

> + // Equivalent method 1 > + @RestMethod(name="GET") > + public void doGet(RestResponse res) { > + res.setOutput("Hello World!"); > + } > + > + // Equivalent method 2 > + @RestMethod(name="GET") > + public String doGet() { > + return "Hello World!"; > + } > +

> +

> + The return type can also be any of the following > special object types: > +

> +
    > +
  • > + {@link java.io.InputStream} > +
    The contents are simply piped to the > output stream returned by > + {@link > org.apache.juneau.rest.RestResponse#getNegotiatedOutputStream()}. > +
    Note that you should call {@link > org.apache.juneau.rest.RestResponse#setContentType(String)} to set > + the Content-Type header if you use > this object type. > +
  • > + {@link java.io.Reader} > +
    The contents are simply piped to the > output stream returned by > + {@link > org.apache.juneau.rest.RestResponse#getNegotiatedWriter()}. > +
    Note that you should call {@link > org.apache.juneau.rest.RestResponse#setContentType(String)} to set > + the Content-Type header if you use > this object type. > +
  • > + {@link org.apache.juneau.rest.Redirect} > +
    Represents an HTTP redirect response. > +
  • > + {@link org.apache.juneau.Streamable} > +
    Interface that identifies that an > object can be serialized directly to an output stream. > +
  • > + {@link org.apache.juneau.Writable} > +
    Interface that identifies that an > object can be serialized directly to a writer. > +
  • > + {@link org.apache.juneau.utils.ZipFileList} > +
    Special interface for sending zip > files as responses. > +
> +

> + Additional "special types" can be defined through > the {@link org.apache.juneau.rest.ResponseHandler} > + interface (described later). > +

> + > +
Method Parameters
> +

> + The method can contain any of the following > parameters in any order: > +

> +
    > +
  • > + Parameters of the following class types: > +
      > +
    • Request/response objects: > +
        > +
      • {@link > org.apache.juneau.rest.RestRequest} - The request object. > +
      • {@link > javax.servlet.http.HttpServletRequest} - The superclass of > RestRequest. > +
      • {@link > org.apache.juneau.rest.RestResponse} - The response object. > +
      • {@link > javax.servlet.http.HttpServletResponse} - The superclass of > RestResponse. > +
      > +
    • Parsed request header values: > +
        > +
      • {@link > org.apache.juneau.http.Accept} > +
      • {@link > org.apache.juneau.http.AcceptCharset} > +
      • {@link > org.apache.juneau.http.AcceptEncoding} > +
      • {@link > org.apache.juneau.http.AcceptLanguage} > +
      • {@link > org.apache.juneau.http.Authorization} > +
      • {@link > org.apache.juneau.http.CacheControl} > +
      • {@link > org.apache.juneau.http.Connection} > +
      • {@link > org.apache.juneau.http.ContentLength} > +
      • {@link > org.apache.juneau.http.ContentType} > +
      • {@link > org.apache.juneau.http.Date} > +
      • {@link > org.apache.juneau.http.Expect} > +
      • {@link > org.apache.juneau.http.From} > +
      • {@link > org.apache.juneau.http.Host} > +
      • {@link > org.apache.juneau.http.IfMatch} > +
      • {@link > org.apache.juneau.http.IfModifiedSince} > +
      • {@link > org.apache.juneau.http.IfNoneMatch} > +
      • {@link > org.apache.juneau.http.IfRange} > +
      • {@link > org.apache.juneau.http.IfUnmodifiedSince} > +
      • {@link > org.apache.juneau.http.MaxForwards} > +
      • {@link > org.apache.juneau.http.Pragma} > +
      • {@link > org.apache.juneau.http.ProxyAuthorization} > +
      • {@link > org.apache.juneau.http.Range} > +
      • {@link > org.apache.juneau.http.Referer} > +
      • {@link > org.apache.juneau.http.TE} > +
      • {@link > org.apache.juneau.http.UserAgent} > +
      • {@link > org.apache.juneau.http.Upgrade} > +
      • {@link > org.apache.juneau.http.Via} > +
      • {@link > org.apache.juneau.http.Warning} > +
      • {@link > java.util.TimeZone} > +
      > +
    • Direct streams on > request/response: > +
        > +
      • {@link > java.io.InputStream} > +
      • {@link > javax.servlet.ServletInputStream} > +
      • {@link > java.io.Reader} > +
      • {@link > java.io.OutputStream} > +
      • {@link > javax.servlet.ServletOutputStream} > +
      • {@link > java.io.Writer} > +
      > +
    • Localization: > +
        > +
      • {@link > java.util.ResourceBundle} - Client-localized resource bundle. > +
      • {@link > org.apache.juneau.utils.MessageBundle} - A resource bundle with additional > features. > +
      • {@link > java.util.Locale} - Client locale. > +
      > +
    • Request APIs: > +
        > +
      • {@link > org.apache.juneau.rest.RequestHeaders} - API for accessing request headers. > +
      • {@link > org.apache.juneau.rest.RequestQuery} - API for accessing request query > parameters. > +
      • {@link > org.apache.juneau.rest.RequestFormData} - API for accessing request form > data. > +
      • {@link > org.apache.juneau.rest.RequestPathMatch} - API for accessing path variables. > +
      • {@link > org.apache.juneau.rest.RequestBody} - API for accessing request body. > +
      > +
    • Other: > +
        > +
      • {@link > org.apache.juneau.http.HttpMethod} - The method name matched (when using > @RestMethod(name="*")) > +
      • {@link > java.util.logging.Logger} - The logger to use for logging. > +
      • {@link > org.apache.juneau.internal.JuneauLogger} - Logger with additional features. > +
      • {@link > org.apache.juneau.rest.RestContext} - The resource read-only context. > +
      • {@link > org.apache.juneau.parser.Parser} - The parser matching the request content > type. > +
      • {@link > org.apache.juneau.dto.swagger.Swagger} - The auto-generated Swagger doc. > +
      • {@link > org.apache.juneau.ini.ConfigFile} - The external config file for the > resource. > +
      > +
    > +
  • > + Annotated parameters: > +
      > +
    • {@link > org.apache.juneau.rest.annotation.Path @Path} - Variables in matched URL > path patterns. > +
    • {@link > org.apache.juneau.rest.annotation.FormData @FormData} - Multipart form post > parameter values. > +
    • {@link > org.apache.juneau.rest.annotation.HasFormData @HasFormData} - Denotes > whether the form data parameter exists. > +
    • {@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. > +
    • {@link > org.apache.juneau.rest.annotation.HasQuery @HasQuery} - Denotes whether the > query parameter exists. > +
    • {@link > org.apache.juneau.rest.annotation.Header @Header} - A header value. > +
    • {@link > org.apache.juneau.rest.annotation.Method @Method} - The HTTP method name. > +
    • {@link > org.apache.juneau.rest.annotation.PathRemainder @PathRemainder} - The > remainder value after path pattern match. > +
    • {@link > org.apache.juneau.rest.annotation.Body @Body} - The HTTP content parsed as > a POJO. > +
    • {@link > org.apache.juneau.rest.annotation.Messages @Messages} - The resource bundle > for the servlet localized to the language on the request. > +
    • {@link > org.apache.juneau.rest.annotation.Properties @Properties} - The > serializer/parser/servlet properties so they can be read or altered on the > request. > +
    > +
> +

> + // Example GET request using annotated attributes > + @RestMethod(name="GET", > path="/example1/{a1}/{a2}/{a3}/*