juneau-doc/docs/Topics/10.juneau-rest-client.html

<!--
/***************************************************************************************************************************
 * 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>&lt;dependency&gt;</xt>
		<xt>&lt;groupId&gt;</xt>org.apache.juneau<xt>&lt;/groupId&gt;</xt>
		<xt>&lt;artifactId&gt;</xt>juneau-rest-client<xt>&lt;/artifactId&gt;</xt>
		<xt>&lt;version&gt;</xt>{@property juneauVersion}<xt>&lt;/version&gt;</xt>
	<xt>&lt;/dependency&gt;</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&lt;Person&gt;</jc>
		List&lt;Person&gt; 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. "&lt;string&gt;foo&lt;/string&gt;" 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. "&lt;number&gt;123&lt;/number&gt;" 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. "&lt;boolean&gt;true&lt;/boolean&gt;" 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>

<h5 class='section'>Notes:</h5>
<ul class='spaced-list'>
	<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>