| <!-- |
| |
| Copyright (c) 2013, 2020 Oracle and/or its affiliates. All rights reserved. |
| |
| This program and the accompanying materials are made available under the |
| terms of the Eclipse Public License v. 2.0, which is available at |
| http://www.eclipse.org/legal/epl-2.0. |
| |
| This Source Code may also be made available under the following Secondary |
| Licenses when the conditions for such availability set forth in the |
| Eclipse Public License v. 2.0 are satisfied: GNU General Public License, |
| version 2 with the GNU Classpath Exception, which is available at |
| https://www.gnu.org/software/classpath/license.html. |
| |
| SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 |
| |
| --> |
| |
| <html xmlns="http://www.w3.org/1999/html" xmlns="http://www.w3.org/1999/html" xmlns="http://www.w3.org/1999/html"> |
| <body> |
| <p>Jakarta RESTful Web Services provides a foundational API to develop web services |
| following the Representational State Transfer (REST) architectural pattern. |
| This API is distributed under the <a href="resources/EFSL.html">Eclipse Foundation Specification License</a>.</p> |
| |
| <h1>Web resources</h1> |
| |
| <p>JAX-RS core APIs enable developers to rapidly build Web applications in Java that are characteristic |
| of the best designed parts of the Web. The API brings in support for designing and implementing |
| Web resources and application that follow principles of |
| <a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm">REST (Representational |
| State Transfer)</a> architectural style to the Java Platform.</p> |
| |
| <p>In JAX-RS, Java POJOs can be exposed as RESTful Web resources independent of the underlying technology |
| using a high level easy-to-use declarative annotation-based API. E.g.:</p> |
| |
| <pre> |
| @Path("widgets/{widgetid}") |
| @Consumes("application/widgets+xml") |
| @Produces("application/widgets+xml") |
| public class WidgetResource { |
| |
| @GET |
| public String getWidget(@PathParam("widgetid") String id) { |
| return getWidgetAsXml(id); |
| } |
| |
| @PUT |
| public void updateWidget(@PathParam("widgetid") String id, |
| Source update) { |
| updateWidgetFromXml(id, update); |
| } |
| |
| ... |
| } |
| </pre> |
| |
| <h1>Web resource clients</h1> |
| |
| <p>JAX-RS client API is a Java based API used to access resources on the Web. It is not restricted |
| to resources implemented using JAX-RS. It provides a higher-level abstraction compared to a |
| {@link java.net.HttpURLConnection plain HTTP communication API} as well as integration with the |
| JAX-RS extension providers, in order to enable concise and efficient implementation of |
| reusable client-side solutions that leverage existing and well |
| established client-side implementations of HTTP-based communication.</p> |
| |
| <p>The JAX-RS Client API also encapsulates the Uniform Interface Constraint – |
| a key constraint of the REST architectural style – and associated data |
| elements as client-side Java artifacts and supports a pluggable architecture |
| by defining multiple extension points.</p> |
| |
| <p>Following example demonstrates a simple JAX-RS client API usage scenario:</p> |
| |
| <pre> |
| Client client = ClientBuilder.newClient(); |
| |
| client.property("MyProperty", "MyValue") |
| .register(MyProvider.class) |
| .enable(MyFeature.class); |
| |
| Response res = client.target("http://example.org/hello").request("text/plain").get(); |
| String message = res.readEntity(String.class); |
| </pre> |
| |
| <h1>Provider extensions</h1> |
| |
| <p>JAX-RS applications may provide custom extensions to the client and server runtime using the |
| common extension APIs defined in <a href="jakarta/ws/rs/ext/package-summary.html">jakarta.ws.rs.ext</a> |
| package, namely entity providers and entity provider interceptors. Additionally, request and |
| response processing chains on client as well as server side can be further customized by |
| implemening custom request and response filters - see the |
| <a href="jakarta/ws/rs/client/ClientRequestFilter.html">ClientRequestFilter</a>, |
| <a href="jakarta/ws/rs/client/ClientResponseFilter.html">ClientResponseFilter</a>, |
| <a href="jakarta/ws/rs/container/ContainerRequestFilter.html">ContainerRequestFilter</a>, |
| <a href="jakarta/ws/rs/container/ContainerResponseFilter.html">ContainerResponseFilter</a> |
| APIs.</p> |
| </body> |
| </html> |
