<!--
/***************************************************************************************************************************
 * 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.
 ***************************************************************************************************************************/
 -->

Using Response Patterns

<p>
	One issue with REST (and HTTP in general) is that the HTTP response code must be set as a header before the 
	body of the request is sent.  
	This can be problematic when REST calls invoke long-running processes, pipes
	the results through the connection, and then fails after an HTTP 200 has already been sent.
</p>
<p>
	One common solution is to serialize some text at the end to indicate whether the long-running process 
	succeeded (e.g. <js>"FAILED"</js> or <js>"SUCCEEDED"</js>).
</p>
<p>
	The {@link oajrc.RestClient} class has convenience methods for scanning the 
	response without interfering with the other methods used for retrieving output.  
</p>
<p>
	The following example shows how the {@link oajrc.RestCall#successPattern(String)} 
	method can be used to look for a SUCCESS message in the output:
</p>	

<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<jc>// Throw a RestCallException if SUCCESS is not found in the output.</jc>
	restClient.doPost(<jsf>URL</jsf>)
		.successPattern(<js>"SUCCESS"</js>)
		.run();
</p>
<p>
	The {@link oajrc.RestCall#failurePattern(String)} method does the opposite.  
	It throws an exception if a failure message is detected.
</p>	

<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<jc>// Throw a RestCallException if FAILURE or ERROR is found in the output.</jc>
	restClient.doPost(<jsf>URL</jsf>)
		.failurePattern(<js>"FAILURE|ERROR"</js>)
		.run();
</p>
<p>
	These convenience methods are specialized methods that use the 
	{@link oajrc.RestCall#responsePattern(ResponsePattern)} method which uses regular 
	expression matching against the response body.
	This method can be used to search for arbitrary patterns in the response body.
</p>
<p>
	The following example shows how to use a response pattern finder to find and capture patterns for 
	<js>"x=number"</js> and <js>"y=string"</js> from a response body.
</p>	

<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<jk>final</jk> List&lt;Number&gt; xList = <jk>new</jk> ArrayList&lt;Number&gt;();
	<jk>final</jk> List&lt;String&gt; yList = <jk>new</jk> ArrayList&lt;String&gt;();
	
	String responseText = restClient.doGet(<jsf>URL</jsf>)
		.responsePattern(
			<jk>new</jk> ResponsePattern(<js>"x=(\\d+)"</js>) {
				<ja>@Override</ja>
				<jk>public void</jk> onMatch(RestCall restCall, Matcher m) <jk>throws</jk> RestCallException {
					xList.add(Integer.<jsm>parseInt</jsm>(m.group(1)));
				}
				<ja>@Override</ja>
				<jk>public void</jk> onNoMatch(RestCall restCall) <jk>throws</jk> RestCallException {
					<jk>throw new</jk> RestCallException(<js>"No X's found!"</js>);
				}
			}
		)
		.responsePattern(
			<jk>new</jk> ResponsePattern(<js>"y=(\\S+)"</js>) {
				<ja>@Override</ja>
				<jk>public void</jk> onMatch(RestCall restCall, Matcher m) <jk>throws</jk> RestCallException {
					yList.add(m.group(1));
				}
				<ja>@Override</ja>
				<jk>public void</jk> onNoMatch(RestCall restCall) <jk>throws</jk> RestCallException {
					<jk>throw new</jk> RestCallException(<js>"No Y's found!"</js>);
				}
			}
		)
		.getResponseAsString();
</p>
<p>
	Using response patterns does not affect the functionality of any of the other methods
	used to retrieve the response such as {@link oajrc.RestCall#getResponseAsString()} 
	or {@link oajrc.RestCall#getResponse(Class)}.
	HOWEVER, if you want to retrieve the entire text of the response from inside the match methods,
	use {@link oajrc.RestCall#getCapturedResponse()} since this method will not absorb 
	the response for those other methods.
</p>