| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <title>jakarta.ws.rs.client</title> |
| <link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style"> |
| <script type="text/javascript" src="../../../../script.js"></script> |
| </head> |
| <body> |
| <script type="text/javascript"><!-- |
| try { |
| if (location.href.indexOf('is-external=true') == -1) { |
| parent.document.title="jakarta.ws.rs.client"; |
| } |
| } |
| catch(err) { |
| } |
| //--> |
| </script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="topNav"><a name="navbar.top"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.top.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../overview-summary.html">Overview</a></li> |
| <li class="navBarCell1Rev">Package</li> |
| <li>Class</li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../../../index-all.html">Index</a></li> |
| <li><a href="../../../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../../../jakarta/ws/rs/package-summary.html">Prev Package</a></li> |
| <li><a href="../../../../jakarta/ws/rs/container/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../index.html?jakarta/ws/rs/client/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_top"> |
| <li><a href="../../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_top"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.top"> |
| <!-- --> |
| </a></div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <div class="header"> |
| <h1 title="Package" class="title">Package jakarta.ws.rs.client</h1> |
| <div class="docSummary"> |
| <div class="block">The JAX-RS client API</div> |
| </div> |
| <p>See: <a href="#package.description">Description</a></p> |
| </div> |
| <div class="contentContainer"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Interface Summary table, listing interfaces, and an explanation"> |
| <caption><span>Interface Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Interface</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/AsyncInvoker.html" title="interface in jakarta.ws.rs.client">AsyncInvoker</a></td> |
| <td class="colLast"> |
| <div class="block">Uniform interface for asynchronous invocation of HTTP methods.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/Client.html" title="interface in jakarta.ws.rs.client">Client</a></td> |
| <td class="colLast"> |
| <div class="block"> |
| Client is the main entry point to the fluent API used to build and execute client requests in order to consume |
| responses returned.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/ClientRequestContext.html" title="interface in jakarta.ws.rs.client">ClientRequestContext</a></td> |
| <td class="colLast"> |
| <div class="block">Client request filter context.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/ClientRequestFilter.html" title="interface in jakarta.ws.rs.client">ClientRequestFilter</a></td> |
| <td class="colLast"> |
| <div class="block">An extension interface implemented by client request filters.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/ClientResponseContext.html" title="interface in jakarta.ws.rs.client">ClientResponseContext</a></td> |
| <td class="colLast"> |
| <div class="block">Client response filter context.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/ClientResponseFilter.html" title="interface in jakarta.ws.rs.client">ClientResponseFilter</a></td> |
| <td class="colLast"> |
| <div class="block">An extension interface implemented by client response filters.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/CompletionStageRxInvoker.html" title="interface in jakarta.ws.rs.client">CompletionStageRxInvoker</a></td> |
| <td class="colLast"> |
| <div class="block">Reactive invoker based <code>CompletionStage</code>.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/Invocation.html" title="interface in jakarta.ws.rs.client">Invocation</a></td> |
| <td class="colLast"> |
| <div class="block">A client request invocation.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/Invocation.Builder.html" title="interface in jakarta.ws.rs.client">Invocation.Builder</a></td> |
| <td class="colLast"> |
| <div class="block">A client request invocation builder.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/InvocationCallback.html" title="interface in jakarta.ws.rs.client">InvocationCallback</a><RESPONSE></td> |
| <td class="colLast"> |
| <div class="block">Callback that can be implemented to receive the asynchronous processing events from the invocation processing.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/RxInvoker.html" title="interface in jakarta.ws.rs.client">RxInvoker</a><T></td> |
| <td class="colLast"> |
| <div class="block">Uniform interface for reactive invocation of HTTP methods.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/RxInvokerProvider.html" title="interface in jakarta.ws.rs.client">RxInvokerProvider</a><T extends <a href="../../../../jakarta/ws/rs/client/RxInvoker.html" title="interface in jakarta.ws.rs.client">RxInvoker</a>></td> |
| <td class="colLast"> |
| <div class="block"><a href="../../../../jakarta/ws/rs/client/RxInvoker.html" title="interface in jakarta.ws.rs.client"><code>RxInvoker</code></a> provider.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/SyncInvoker.html" title="interface in jakarta.ws.rs.client">SyncInvoker</a></td> |
| <td class="colLast"> |
| <div class="block">Uniform interface for synchronous invocation of HTTP methods.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/WebTarget.html" title="interface in jakarta.ws.rs.client">WebTarget</a></td> |
| <td class="colLast"> |
| <div class="block">A resource target identified by the resource URI.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation"> |
| <caption><span>Class Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Class</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/ClientBuilder.html" title="class in jakarta.ws.rs.client">ClientBuilder</a></td> |
| <td class="colLast"> |
| <div class="block">Main entry point to the client API used to bootstrap <a href="../../../../jakarta/ws/rs/client/Client.html" title="interface in jakarta.ws.rs.client"><code>Client</code></a> instances.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/Entity.html" title="class in jakarta.ws.rs.client">Entity</a><T></td> |
| <td class="colLast"> |
| <div class="block">Encapsulates message entity including the associated variant information.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Exception Summary table, listing exceptions, and an explanation"> |
| <caption><span>Exception Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Exception</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../jakarta/ws/rs/client/ResponseProcessingException.html" title="class in jakarta.ws.rs.client">ResponseProcessingException</a></td> |
| <td class="colLast"> |
| <div class="block">JAX-RS client-side runtime processing exception thrown to indicate that response processing has failed (e.g.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| </ul> |
| <a name="package.description"> |
| <!-- --> |
| </a> |
| <h2 title="Package jakarta.ws.rs.client Description">Package jakarta.ws.rs.client Description</h2> |
| <div class="block"><h2>The JAX-RS client API</h2> |
| <p> |
| The JAX-RS client API is a Java based API used to access Web resources. It is not restricted to resources implemented |
| using JAX-RS. It provides a higher-level abstraction compared to a <code>plain HTTP |
| communication API</code> 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> |
| The JAX-RS Client API 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. |
| |
| <h3>Client API Bootstrapping and Configuration</h3> The main entry point to the API is a |
| <a href="../../../../jakarta/ws/rs/client/ClientBuilder.html" title="class in jakarta.ws.rs.client"><code>ClientBuilder</code></a> that is used to bootstrap <a href="../../../../jakarta/ws/rs/client/Client.html" title="interface in jakarta.ws.rs.client"><code>Client</code></a> instances - |
| <a href="../../../../jakarta/ws/rs/core/Configurable.html" title="interface in jakarta.ws.rs.core"><code>configurable</code></a>, heavy-weight objects that manage the underlying communication |
| infrastructure and serve as the root objects for accessing any Web resource. The following example illustrates the |
| bootstrapping and configuration of a <code>Client</code> instance: |
| |
| <pre> |
| Client client = ClientBuilder.newClient(); |
| |
| client.property("MyProperty", "MyValue") |
| .register(MyProvider.class) |
| .register(MyFeature.class); |
| </pre> |
| |
| <h3>Accessing Web Resources</h3> A Web resource can be accessed using a fluent API in which method invocations are |
| chained to configure and ultimately submit an HTTP request. The following example gets a <code>text/plain</code> |
| representation of the resource identified by <code>"http://example.org/hello"</code>: |
| |
| <pre> |
| Client client = ClientBuilder.newClient(); |
| Response res = client.target("http://example.org/hello").request("text/plain").get(); |
| </pre> |
| |
| Conceptually, the steps required to submit a request are the following: |
| <ol> |
| <li>obtain an <a href="../../../../jakarta/ws/rs/client/Client.html" title="interface in jakarta.ws.rs.client"><code>Client</code></a> instance</li> |
| <li>create a <a href="../../../../jakarta/ws/rs/client/WebTarget.html" title="interface in jakarta.ws.rs.client"><code>WebTarget</code></a> pointing at a Web resource</li> |
| <li><a href="../../../../jakarta/ws/rs/client/Invocation.Builder.html" title="interface in jakarta.ws.rs.client"><code>build</code></a> a request</li> |
| <li>submit a request to directly retrieve a response or get a prepared <a href="../../../../jakarta/ws/rs/client/Invocation.html" title="interface in jakarta.ws.rs.client"><code>Invocation</code></a> for |
| later submission</li> |
| </ol> |
| |
| As illustrated above, individual Web resources are in the JAX-RS Client API represented as resource targets. Each |
| <code>WebTarget</code> instance is bound to a concrete URI, e.g. <code>"http://example.org/messages/123"</code>, or a URI |
| template, e.g. <code>"http://example.org/messages/{id}"</code>. That way a single target can either point at a particular |
| resource or represent a larger group of resources (that e.g. share a common configuration) from which concrete |
| resources can be later derived: |
| |
| <pre> |
| // Parent target for all messages |
| WebTarget messages = client.target("http://example.org/messages/{id}"); |
| |
| // New target for http://example.org/messages/123 |
| WebTarget msg123 = messages.resolveTemplate("id", 123); |
| |
| // New target for http://example.org/messages/456 |
| WebTarget msg456 = messages.resolveTemplate("id", 456); |
| </pre> |
| |
| <h3>Generic Invocations</h3> An <a href="../../../../jakarta/ws/rs/client/Invocation.html" title="interface in jakarta.ws.rs.client"><code>Invocation</code></a> is a request that has been prepared and is |
| ready for execution. Invocations provide a generic interface that enables a separation of concerns between the |
| creator and the submitter. In particular, the submitter does not need to know how the invocation was prepared, but |
| only whether it should be executed synchronously or asynchronously. |
| |
| <pre> |
| Invocation inv1 = client.target("http://example.org/atm/balance") |
| .queryParam("card", "111122223333").queryParam("pin", "9876") |
| .request("text/plain").buildGet(); |
| Invocation inv2 = client.target("http://example.org/atm/withdrawal") |
| .queryParam("card", "111122223333").queryParam("pin", "9876") |
| .request().buildPost(text("50.0"))); |
| |
| Collection<Invocation> invs = Arrays.asList(inv1, inv2); |
| // Executed by the submitter |
| Collection<Response> ress = Collections.transform(invs, new F<Invocation, Response>() { |
| public Response apply(Invocation inv) {return inv.invoke(); } |
| }); |
| </pre></div> |
| </div> |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <div class="bottomNav"><a name="navbar.bottom"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.bottom.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../overview-summary.html">Overview</a></li> |
| <li class="navBarCell1Rev">Package</li> |
| <li>Class</li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../../../index-all.html">Index</a></li> |
| <li><a href="../../../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../../../jakarta/ws/rs/package-summary.html">Prev Package</a></li> |
| <li><a href="../../../../jakarta/ws/rs/container/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../index.html?jakarta/ws/rs/client/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_bottom"> |
| <li><a href="../../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_bottom"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| </body> |
| </html> |
