| <!-- |
| /*************************************************************************************************************************** |
| * 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-client |
| |
| <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-client<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-client-{@property juneauVersion}.jar |
| </p> |
| |
| <h5 class='figure'>OSGi Module</h5> |
| <p class='bpcode w500'> |
| org.apache.juneau.rest.client_{@property juneauVersion}.jar |
| </p> |
| |
| <p> |
| The REST client API provides the ability to access remote REST interfaces and transparently convert the input |
| and output to and from POJOs using any of the provided serializers and parsers. |
| </p> |
| <p> |
| Built upon the Apache HttpClient libraries, it extends that API and provides specialized APIs for working with |
| REST interfaces while maintaining all the functionality available in the HttpClient API. |
| </p> |
| <p class='bpcode w800'> |
| <jc>// Create a reusable JSON client.</jc> |
| <jk>try</jk> (RestClient client = RestClient.<jsm>create</jsm>().json().build()) { |
| |
| <jc>// The address of the root resource.</jc> |
| String url = <js>"http://localhost:10000/addressBook"</js>; |
| |
| <jc>// Do a REST GET against a remote REST interface and convert |
| // the response to an unstructured ObjectMap object.</jc> |
| ObjectMap m1 = client.doGet(url).getResponse(ObjectMap.<jk>class</jk>); |
| |
| <jc>// Same as above, except parse the JSON as a bean.</jc> |
| AddressBook a2 = client.doGet(url).getResponse(AddressBook.<jk>class</jk>); |
| } |
| |
| <jk>try</jk> (RestClient client = RestClient.<jsm>create</jsm>().serializer(XmlSerializer.<jk>class</jk>).parser(XmlSerializer.<jk>class</jk>).build()) { |
| <jc>// Add a person to the address book. |
| // Use XML as the transport medium.</jc> |
| Person p = <jk>new</jk> Person(<js>"Joe Smith"</js>, 21); |
| <jk>int</jk> returnCode = client.doPost(url + <js>"/entries"</js>, p).run(); |
| } |
| </p> |
| <p> |
| Juneau provides an HTTP client API that makes it extremely simple to connect to remote REST interfaces and |
| seemlessly send and receive serialized POJOs in requests and responses. |
| </p> |
| |
| <h5 class='topic'>Features</h5> |
| <ul class='spaced-list'> |
| <li> |
| Converts POJOs directly to HTTP request message bodies using {@link oaj.serializer.Serializer} |
| classes. |
| <li> |
| Converts HTTP response message bodies directly to POJOs using {@link oaj.parser.Parser} |
| classes. |
| <li> |
| Serializes and parses HTTP request and response parts (query/form-data parameters, headers, path variables) |
| using OpenAPI marshalling and validation. |
| <li> |
| Exposes the full functionality of the Apache HttpClient API by exposing all methods defined on the |
| {@link org.apache.http.impl.client.HttpClientBuilder} class. |
| </ul> |
| <p> |
| The client API is designed to work as a thin layer on top of the proven Apache HttpClient API. |
| By leveraging the HttpClient library, details such as SSL certificate negotiation, proxies, encoding, etc... |
| are all handled in Apache code. |
| </p> |
| <p> |
| The Juneau client API prereq's Apache HttpClient 4.5+. |
| At a minimum, the following jars are required: |
| </p> |
| <ul> |
| <li><c>httpclient-4.5.jar</c> |
| <li><c>httpcore-4.4.1.jar</c> |
| <li><c>httpmime-4.5.jar</c> |
| </ul> |
| |
| <h5 class='figure'>Example:</h5> |
| <p class='bpcode w800'> |
| <jc>// Examples below use the Juneau Address Book resource example</jc> |
| |
| <jc>// Create a reusable client with JSON support</jc> |
| <jk>try</jk> (RestClient client = RestClient.<jsm>create</jsm>().json().build()) { |
| |
| <jc>// GET request, ignoring output</jc> |
| <jk>try</jk> { |
| <jk>int</jk> rc = client.doGet(<js>"http://localhost:10000/addressBook"</js>).run(); |
| <jc>// Succeeded!</jc> |
| } <jk>catch</jk> (RestCallException e) { |
| <jc>// Failed!</jc> |
| System.<jsf>err</jsf>.println( |
| String.<jsm>format</jsm>(<js>"status=%s, message=%s"</js>, e.getResponseStatus(), e.getResponseMessage()) |
| ); |
| } |
| |
| <jc>// Remaining examples ignore thrown exceptions.</jc> |
| |
| <jc>// GET request, secure, ignoring output</jc> |
| client.doGet(<js>"https://localhost:9443/sample/addressBook"</js>).run(); |
| |
| <jc>// GET request, getting output as a String. No POJO parsing is performed. |
| // Note that when calling one of the getX() methods, you don't need to call connect() or disconnect(), since |
| // it's automatically called for you.</jc> |
| String output = client.doGet(<js>"http://localhost:10000/addressBook"</js>) |
| .getResponseAsString(); |
| |
| <jc>// GET request, getting output as a Reader</jc> |
| Reader r = client.doGet(<js>"http://localhost:10000/addressBook"</js>) |
| .getReader(); |
| |
| <jc>// GET request, getting output as an untyped map</jc> |
| <jc>// Input must be an object (e.g. "{...}")</jc> |
| ObjectMap m = client.doGet(<js>"http://localhost:10000/addressBook/0"</js>) |
| .getResponse(ObjectMap.<jk>class</jk>); |
| |
| <jc>// GET request, getting output as an untyped list</jc> |
| <jc>// Input must be an array (e.g. "[...]")</jc> |
| ObjectList l = client.doGet(<js>"http://localhost:10000/addressBook"</js>) |
| .getResponse(ObjectList.<jk>class</jk>); |
| |
| <jc>// GET request, getting output as a parsed bean</jc> |
| <jc>// Input must be an object (e.g. "{...}")</jc> |
| <jc>// Note that you don't have to do any casting!</jc> |
| Person p = client.doGet(<js>"http://localhost:10000/addressBook/0"</js>) |
| .getResponse(Person.<jk>class</jk>); |
| |
| <jc>// GET request, getting output as a parsed bean</jc> |
| <jc>// Input must be an array of objects (e.g. "[{...},{...}]")</jc> |
| Person[] pa = client.doGet(<js>"http://localhost:10000/addressBook"</js>) |
| .getResponse(Person[].<jk>class</jk>); |
| |
| <jc>// Same as above, except as a List<Person></jc> |
| List<Person> pl = client.doGet(<js>"http://localhost:10000/addressBook"</js>) |
| .getResponse(List.<jk>class</jk>, Person.<jk>class</jk>); |
| |
| <jc>// GET request, getting output as a parsed string</jc> |
| <jc>// Input must be a string (e.g. "<string>foo</string>" or "'foo'")</jc> |
| String name = client.doGet(<js>"http://localhost:10000/addressBook/0/name"</js>) |
| .getResponse(String.<jk>class</jk>); |
| |
| <jc>// GET request, getting output as a parsed number</jc> |
| <jc>// Input must be a number (e.g. "<number>123</number>" or "123")</jc> |
| <jk>int</jk> age = client.doGet(<js>"http://localhost:10000/addressBook/0/age"</js>) |
| .getResponse(Integer.<jk>class</jk>); |
| |
| <jc>// GET request, getting output as a parsed boolean</jc> |
| <jc>// Input must be a boolean (e.g. "<boolean>true</boolean>" or "true")</jc> |
| <jk>boolean</jk> isCurrent = client.doGet(<js>"http://localhost:10000/addressBook/0/addresses/0/isCurrent"</js>) |
| .getResponse(Boolean.<jk>class</jk>); |
| } |
| |
| <jc>// GET request, getting a filtered object</jc> |
| <jk>try</jk> (RestClient client = RestClient.<jsm>create</jsm>().pojoSwaps(TemporalCalendarSwap.IsoInstant.<jk>class</jk>).build()) { |
| Calendar birthDate = client.doGet(<js>"http://localhost:10000/addressBook/0/birthDate"</js>) |
| .getResponse(GregorianCalendar.<jk>class</jk>); |
| |
| <jc>// PUT request on regular field</jc> |
| String newName = <js>"John Smith"</js>; |
| <jk>int</jk> rc = client.doPut(<js>"http://localhost:10000/addressBook/0/name"</js>, newName).run(); |
| |
| <jc>// PUT request on filtered field</jc> |
| Calendar newBirthDate = <jk>new</jk> GregorianCalendar(1, 2, 3, 4, 5, 6); |
| rc = client.doPut(<js>"http://localhost:10000/addressBook/0/birthDate"</js>, newBirthDate).run(); |
| |
| <jc>// POST of a new entry to a list</jc> |
| Address newAddress = <jk>new</jk> Address(<js>"101 Main St"</js>, <js>"Anywhere"</js>, <js>"NY"</js>, 12121, <jk>false</jk>); |
| rc = client.doPost(<js>"http://localhost:10000/addressBook/0/addresses"</js>, newAddress).run(); |
| } |
| </p> |
| |
| <ul class='notes'> |
| <li> |
| The {@link oajrc.RestClient} class exposes all the builder methods on the Apache |
| HttpClient {@link org.apache.http.impl.client.HttpClientBuilder} class. |
| <br>Use these methods to provide any customized HTTP client behavior. |
| </ul> |