| <!-- |
| /*************************************************************************************************************************** |
| * 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<Number> xList = <jk>new</jk> ArrayList<Number>(); |
| <jk>final</jk> List<String> yList = <jk>new</jk> ArrayList<String>(); |
| |
| 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> |