View Javadoc
1   package org.codehaus.plexus.interpolation;
2   
3   /*
4    * Copyright 2001-2008 Codehaus Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.util.List;
20  
21  /**
22   * Interpolator interface. Based on existing RegexBasedInterpolator interface.
23   *
24   * @author cstamas
25   */
26  public interface Interpolator
27      extends BasicInterpolator
28  {
29  
30      /**
31       * Add a new {@link ValueSource} to the stack used to resolve expressions
32       * in this interpolator instance.
33       * @param valueSource {@link ValueSource}.
34       */
35      void addValueSource( ValueSource valueSource );
36  
37      /**
38       * Remove the specified {@link ValueSource} from the stack used to resolve
39       * expressions in this interpolator instance.
40       * @param valueSource {@link ValueSource}.
41       */
42      void removeValuesSource( ValueSource valueSource );
43      
44      /**
45       * Add a new post-processor to handle final processing after 
46       * recursively-interpolated value is determined.
47       * @param postProcessor {@link InterpolationPostProcessor}.
48       */
49      void addPostProcessor( InterpolationPostProcessor postProcessor );
50  
51      /**
52       * Remove the given post-processor.
53       * @param postProcessor {@link InterpolationPostProcessor}.
54       */
55      void removePostProcessor( InterpolationPostProcessor postProcessor );
56  
57      /**
58       * See {@link Interpolator#interpolate(String, String, RecursionInterceptor)}.
59       * <p>
60       * This method triggers the use of a {@link SimpleRecursionInterceptor}
61       * instance for protection against expression cycles.</p>
62       *
63       * @param input The input string to interpolate
64       *
65       * @param thisPrefixPattern An optional pattern that should be trimmed from
66       *                          the start of any expressions found in the input.
67       * @return interpolated string.
68       * @throws InterpolationException in case of an error.
69       */
70      String interpolate( String input,
71                          String thisPrefixPattern )
72          throws InterpolationException;
73  
74      /**
75       * Attempt to resolve all expressions in the given input string, using the
76       * given pattern to first trim an optional prefix from each expression. The
77       * supplied recursion interceptor will provide protection from expression
78       * cycles, ensuring that the input can be resolved or an exception is
79       * thrown.
80       * <b>return an empty String if input is null</b>
81       * @param input The input string to interpolate
82       *
83       * @param thisPrefixPattern An optional pattern that should be trimmed from
84       *                          the start of any expressions found in the input.
85       *
86       * @param recursionInterceptor Used to protect the interpolation process
87       *                             from expression cycles, and throw an
88       *                             exception if one is detected.
89       * @return interpolated string.
90       * @throws InterpolationException in case of an error.
91       */
92      String interpolate( String input,
93                          String thisPrefixPattern,
94                          RecursionInterceptor recursionInterceptor )
95          throws InterpolationException;
96  
97      /**
98       * Return any feedback messages and errors that were generated - but
99       * suppressed - during the interpolation process. Since unresolvable
100      * expressions will be left in the source string as-is, this feedback is
101      * optional, and will only be useful for debugging interpolation problems.
102      *
103      * @return a {@link List} that may be interspersed with {@link String} and
104      * {@link Throwable} instances.
105      */
106     List getFeedback();
107 
108     /**
109      * Clear the feedback messages from previous interpolate(..) calls.
110      */
111     void clearFeedback();
112     
113     /**
114      * @return state of the cacheAnswers
115      */
116     boolean isCacheAnswers();
117 
118     /**
119      * @param cacheAnswers true/false.
120      */
121     void setCacheAnswers( boolean cacheAnswers );
122     
123     void clearAnswers();
124 }