| <!-- |
| /*************************************************************************************************************************** |
| * 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. |
| ***************************************************************************************************************************/ |
| --> |
| |
| juneau-rest-server |
| |
| <h5 class='figure'>Maven Dependency</h5> |
| <p class='bpcode w500'> |
| <xt><dependency></xt> |
| <xt><groupId></xt>org.apache.juneau<xt></groupId></xt> |
| <xt><artifactId></xt>juneau-rest-server<xt></artifactId></xt> |
| <xt><version></xt>{@property juneauVersion}<xt></version></xt> |
| <xt></dependency></xt> |
| </p> |
| |
| <h5 class='figure'>Java Library</h5> |
| <p class='bpcode w500'> |
| juneau-rest-server-{@property juneauVersion}.jar |
| </p> |
| |
| <h5 class='figure'>OSGi Module</h5> |
| <p class='bpcode w500'> |
| org.apache.juneau.rest.server_{@property juneauVersion}.jar |
| </p> |
| |
| <p> |
| The <l>juneau-rest-server</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 oajr.RestServlet} is nothing but a specialized |
| {@link javax.servlet.http.HttpServlet}, and the {@link oajr.RestRequest} and |
| {@link oajr.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> |
| |
| <h5 class='topic'>Features</h5> |
| <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> |
| Support for parsing all HTTP parts (headers, query, formData, path variables) using Swagger formatting rules and validations. |
| <br>Not limited to simple POJOs, but rather you can represent arbitrarily-complex POJOs in any HTTP part using UON notation. |
| <li> |
| Auto-created Swagger JSON and Swagger UI available through OPTIONS requests of resources. |
| <li> |
| Various useful debugging features that make debugging using a browser extremely simple... |
| <ul> |
| <li>Ability to pass HTTP header values as URL GET parameters (e.g. <l>&Accept=text/xml</l>). |
| <li>Ability to pass HTTP content on PUT/POST requests as a URL GET parameter |
| (e.g. <l>&content=(foo=bar)</l>). |
| <li>Ability to simulate non-GET requests using a <l>&method</l> GET parameter |
| (e.g. <l>&method=POST</l>). |
| <li>Ability to force <js>"text/plain"</js> on response using GET parameter <l>&plainText=true</l>. |
| </ul> |
| <li> |
| Ability to implement overloaded HTTP methods through the use of the <l>&method</l> attribute |
| (e.g. <l>&method=FOO</l>). |
| <li> |
| Ability to match URL patterns (e.g. <l>/foo/{fooId}/bar/{barId}</l>) against URLs |
| (e.g. <l>/foo/123/bar/456/bing</l>). |
| <li> |
| Ability to associate guards at the resource or method levels through annotations. |
| <br>Typically useful for security, but can be used for a variety of purposes. |
| <li> |
| Ability to associate converters at the resource or method levels through annotations. |
| <br>Typically useful for performing conversions on input and output, such as for supporting older input and |
| output formats. |
| </ul> |
| <p> |
| Many of the examples in this document are pulled directly from <l>juneau-examples-rest</l>. |
| </p> |