001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  You may obtain a copy of the License at                                                              *
006// *                                                                                                                         *
007// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
008// *                                                                                                                         *
009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.rest.client;
014
015import java.io.*;
016import java.util.regex.*;
017
018/**
019 * Used to find regular expression matches in REST responses made through {@link RestCall}.
020 *
021 * <p>
022 * Response patterns are applied to REST calls through the {@link RestCall#responsePattern(ResponsePattern)} method.
023 *
024 * <h5 class='section'>Example:</h5>
025 *
026 * This example shows how to use a response pattern finder to find and capture patterns for <js>"x=number"</js> and
027 * <js>"y=string"</js> from a response body.
028 * <p class='bcode w800'>
029 *    <jk>final</jk> List&lt;Number&gt; xList = <jk>new</jk> ArrayList&lt;Number&gt;();
030 *    <jk>final</jk> List&lt;String&gt; yList = <jk>new</jk> ArrayList&lt;String&gt;();
031 *
032 *    restClient.doGet(<jsf>URL</jsf>)
033 *       .addResponsePattern(
034 *          <jk>new</jk> ResponsePattern(<js>"x=(\\d+)"</js>) {
035 *             <ja>@Override</ja>
036 *             <jk>public void</jk> onMatch(RestCall restCall, Matcher m) <jk>throws</jk> RestCallException {
037 *                xList.add(Integer.<jsm>parseInt</jsm>(m.group(1)));
038 *             }
039 *             <ja>@Override</ja>
040 *             <jk>public void</jk> onNoMatch(RestCall restCall) <jk>throws</jk> RestCallException {
041 *                <jk>throw new</jk> RestCallException(<js>"No X's found!"</js>);
042 *             }
043 *          }
044 *       )
045 *       .addResponsePattern(
046 *          <jk>new</jk> ResponsePattern(<js>"y=(\\S+)"</js>) {
047 *             <ja>@Override</ja>
048 *             <jk>public void</jk> onMatch(RestCall restCall, Matcher m) <jk>throws</jk> RestCallException {
049 *                yList.add(m.group(1));
050 *             }
051 *             <ja>@Override</ja>
052 *             <jk>public void</jk> onNoMatch(RestCall restCall) <jk>throws</jk> RestCallException {
053 *                <jk>throw new</jk> RestCallException(<js>"No Y's found!"</js>);
054 *             }
055 *          }
056 *       )
057 *       .run();
058 * </p>
059 *
060 * <ul class='notes'>
061 *    <li>
062 *       Using response patterns does not affect the functionality of any of the other methods
063 *       used to retrieve the response such as {@link RestCall#getResponseAsString()} or {@link RestCall#getResponse(Class)}.
064 *       <br>HOWEVER, if you want to retrieve the entire text of the response from inside the match methods, use
065 *       {@link RestCall#getCapturedResponse()} since this method will not absorb the response for those other methods.
066 *    <li>
067 *       Response pattern methods are NOT executed if a REST exception occurs during the request.
068 *    <li>
069 *       The {@link RestCall#successPattern(String)} and {@link RestCall#failurePattern(String)} methods use instances
070 *       of this class to throw {@link RestCallException RestCallExceptions} when success patterns are not found or
071 *       failure patterns are found.
072 *    <li>
073 *       {@link ResponsePattern} objects are reusable and thread-safe.
074 * </ul>
075 */
076public abstract class ResponsePattern {
077
078   private Pattern pattern;
079
080   /**
081    * Constructor.
082    *
083    * @param pattern Regular expression pattern.
084    */
085   public ResponsePattern(String pattern) {
086      this.pattern = Pattern.compile(pattern);
087   }
088
089   void match(RestCall rc) throws RestCallException {
090      try {
091         Matcher m = pattern.matcher(rc.getCapturedResponse());
092         boolean found = false;
093         while (m.find()) {
094            onMatch(rc, m);
095            found = true;
096         }
097         if (! found)
098            onNoMatch(rc);
099      } catch (IOException e) {
100         throw new RestCallException(e);
101      }
102   }
103
104   /**
105    * Returns the pattern passed in through the constructor.
106    *
107    * @return The pattern passed in through the constructor.
108    */
109   protected String getPattern() {
110      return pattern.pattern();
111   }
112
113   /**
114    * Instances can override this method to handle when a regular expression pattern matches on the output.
115    *
116    * <p>
117    * This method is called once for every pattern match that occurs in the response text.
118    *
119    * @param rc The {@link RestCall} that this pattern finder is being used on.
120    * @param m The regular expression {@link Matcher}.  Can be used to retrieve group matches in the pattern.
121    * @throws RestCallException Instances can throw an exception if a failure condition is detected.
122    */
123   public void onMatch(RestCall rc, Matcher m) throws RestCallException {}
124
125   /**
126    * Instances can override this method to handle when a regular expression pattern doesn't match on the output.
127    *
128    * @param rc The {@link RestCall} that this pattern finder is being used on.
129    * @throws RestCallException Instances can throw an exception if a failure condition is detected.
130    */
131   public void onNoMatch(RestCall rc) throws RestCallException {}
132}