PatternCache


1   package org.apache.oro.text;
2   
3   /* ====================================================================
4    * The Apache Software License, Version 1.1
5    *
6    * Copyright (c) 2000 The Apache Software Foundation.  All rights
7    * reserved.
8    *
9    * Redistribution and use in source and binary forms, with or without
10   * modification, are permitted provided that the following conditions
11   * are met:
12   *
13   * 1. Redistributions of source code must retain the above copyright
14   *    notice, this list of conditions and the following disclaimer.
15   *
16   * 2. Redistributions in binary form must reproduce the above copyright
17   *    notice, this list of conditions and the following disclaimer in
18   *    the documentation and/or other materials provided with the
19   *    distribution.
20   *
21   * 3. The end-user documentation included with the redistribution,
22   *    if any, must include the following acknowledgment:
23   *       "This product includes software developed by the
24   *        Apache Software Foundation (http://www.apache.org/)."
25   *    Alternately, this acknowledgment may appear in the software itself,
26   *    if and wherever such third-party acknowledgments normally appear.
27   *
28   * 4. The names "Apache" and "Apache Software Foundation", "Jakarta-Oro" 
29   *    must not be used to endorse or promote products derived from this
30   *    software without prior written permission. For written
31   *    permission, please contact apache@apache.org.
32   *
33   * 5. Products derived from this software may not be called "Apache" 
34   *    or "Jakarta-Oro", nor may "Apache" or "Jakarta-Oro" appear in their 
35   *    name, without prior written permission of the Apache Software Foundation.
36   *
37   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
41   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48   * SUCH DAMAGE.
49   * ====================================================================
50   *
51   * This software consists of voluntary contributions made by many
52   * individuals on behalf of the Apache Software Foundation.  For more
53   * information on the Apache Software Foundation, please see
54   * <http://www.apache.org/>.
55   *
56   * Portions of this software are based upon software originally written 
57   * by Daniel F. Savarese. We appreciate his contributions.
58   */
59  
60  import org.apache.oro.text.regex.*;
61  
62  /**
63   * An interface defining the basic functions of a regular expression
64   * cache.
65   * <p>
66   * A PatternCache is an object that takes care of compiling, storing, and
67   * retrieving regular expressions so that the programmer does not have to
68   * explicitly manage these operation himself.  The main benefit derived
69   * is the ease of use from only having to express regular expressions
70   * by their String representations.
71  
72   @author <a HREF="dfs@savarese.org">Daniel F. Savarese</a>
73   @version $Id: PatternCache.java,v 1.1.1.1 2000/07/23 23:08:49 jon Exp $
74  
75   * @see MalformedCachePatternException
76   */
77  
78  public interface PatternCache {
79  
80    /**
81     * Adds a pattern to the cache and returns the compiled pattern.  This
82     * method is in principle almost identical to
83     * {@link #getPattern(String)} except for the fact that
84     * it throws a MalformedPatternException if an expression cannot be
85     * compiled.
86     * <p>
87     * addPattern() is meant to be used when you expressly intend to add
88     * an expression to a cache and is useful for front-loading a cache
89     * with expressions before use.  If the expression added does not
90     * already exist in the cache, it is compiled, added to the cache,
91     * and returned.  If the compiled expression is already in the cache, it
92     * is simply returned.
93     * <p>
94     * The expected behavior of this method should be to start replacing
95     * patterns in the cache only after the cache has been filled to capacity.
96     * <p>
97     * @param expression  The regular expression to add to the cache.
98     * @return The Pattern corresponding to the String representation of the
99     *         regular expression.
100    * @exception MalformedPatternException  If there is an error in compiling
101    *         the regular expression.
102    */
103   public Pattern addPattern(String   expression)
104        throws MalformedPatternException;
105 
106 
107   /**
108    * Adds a pattern to the cache and returns the compiled pattern.  This
109    * method is in principle almost identical to
110    * {@link #getPattern(String)} except for the fact that
111    * it throws a MalformedPatternException if an expression cannot be
112    * compiled.
113    * <p>
114    * addPattern() is meant to be used when you expressly intend to add
115    * an expression to the cache and is useful for front-loading a cache
116    * with expressions before use.  If the expression added does not
117    * already exist in the cache, it is compiled, added to the cache,
118    * and returned.  If the compiled expression is already in the cache, it
119    * is simply returned.
120    * <p>
121    * The expected behavior of this method should be to start replacing
122    * patterns in the cache only after the cache has been filled to capacity.
123    * <p>
124    * @param expression  The regular expression to add to the cache.
125    * @param options The compilation options to use when compiling the
126    *        expression.
127    * @return The Pattern corresponding to the String representation of the
128    *         regular expression.
129    * @exception MalformedPatternException  If there is an error in compiling
130    *         the regular expression.
131    */
132   public Pattern addPattern(String   expression, int options)
133        throws MalformedPatternException;
134 
135 
136   /**
137    * This method fetches a pattern from the cache.  It is nearly identical
138    * to {@link #addPattern addPattern()} except that it doesn't
139    * throw a MalformedPatternException.  If the pattern is not in the
140    * cache, it is compiled, placed in the cache, and returned.  If
141    * the pattern cannot be compiled successfully, the implementation must
142    * throw an exception derived from MalformedCachePatternException.
143    * Note that this exception is derived from RuntimeException, which means
144    * you are NOT forced to catch it by the compiler.  Please refer to
145    * {@link MalformedCachePatternException} for a discussion of when you
146    * should and shouldn't catch this exception.
147    * <p>
148    * @param expression  The regular expression to fetch from the cache in
149    *        compiled form.
150    * @return The Pattern corresponding to the String representation of the
151    *         regular expression.
152    * @exception MalformedCachePatternException  If there is an error in
153    *     compiling the regular expression.
154    */
155   public Pattern getPattern(String   expression)
156        throws MalformedCachePatternException;
157 
158 
159   /**
160    * This method fetches a pattern from the cache.  It is nearly identical
161    * to {@link #addPattern addPattern()} except that it doesn't
162    * throw a MalformedPatternException.  If the pattern is not in the
163    * cache, it is compiled, placed in the cache, and returned.  If
164    * the pattern cannot be compiled successfully, it
165    * throws a MalformedCachePatternException.
166    * Note that this exception is derived from RuntimeException, which means
167    * you are NOT forced to catch it by the compiler.  Please refer to
168    * {@link MalformedCachePatternException} for a discussion of when you
169    * should and shouldn't catch this exception.
170    * <p>
171    * @param expression  The regular expression to fetch from the cache in
172    *        compiled form.
173    * @param options The compilation options to use when compiling the
174    *        expression.
175    * @return The Pattern corresponding to the String representation of the
176    *         regular expression.
177    * @exception MalformedCachePatternException  If there is an error in
178    *     compiling the regular expression.
179    */
180   public Pattern getPattern(String   expression, int options)
181        throws MalformedCachePatternException;
182 
183 
184   /**
185    * Returns the number of elements in the cache, not to be confused with
186    * the {@link #capacity()} which returns the number
187    * of elements that can be held in the cache at one time.
188    * <p>
189    * @return  The current size of the cache (i.e., the number of elements
190    *          currently cached).
191    */
192   public int size();
193 
194 
195   /**
196    * Returns the maximum number of patterns that can be cached at one time.
197    * <p>
198    * @return The maximum number of patterns that can be cached at one time.
199    */
200   public int capacity();
201 }
202 
203
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags