KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > oro > text > GenericPatternCache


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 java.util.*;
61
62 import org.apache.oro.text.regex.*;
63 import org.apache.oro.util.*;
64
65 /**
66  * This is the base class for all cache implementations provided in the
67  * org.apache.oro.text package.
68  * Although 4 subclasses of GenericPatternCache are provided with this
69  * package, users may not derive subclasses from this class.
70  * Rather, users should create their own implmentations of the
71  * {@link PatternCache} interface.
72
73  @author <a HREF="dfs@savarese.org">Daniel F. Savarese</a>
74  @version $Id: GenericPatternCache.java,v 1.1.1.1 2000/07/23 23:08:49 jon Exp $
75
76  * @see PatternCache
77  * @see PatternCacheLRU
78  * @see PatternCacheFIFO
79  * @see PatternCacheFIFO2
80  * @see PatternCacheRandom
81  */
82 public abstract class GenericPatternCache implements PatternCache {
83   PatternCompiler _compiler;
84   Cache _cache;
85
86   /**
87    * The default capacity to be used by the GenericPatternCache subclasses
88    * provided with this package. Its value is 20.
89    */
90   public static final int DEFAULT_CAPACITY = 20;
91
92   /**
93    * The primary constructor for GenericPatternCache. It has default
94    * access so it will only be used within the package. It initializes
95    * _cache and _compiler to the arguments provided.
96    * <p>
97    * @param cache The cache with which to store patterns.
98    * @param compiler The PatternCompiler that should be used to compile
99    * patterns.
100    */
101   GenericPatternCache(Cache cache, PatternCompiler compiler) {
102     _cache = cache;
103     _compiler = compiler;
104   }
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 getPattern()} 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 final synchronized Pattern addPattern(String JavaDoc expression, int options)
133        throws MalformedPatternException
134   {
135     Object JavaDoc obj;
136     Pattern pattern;
137
138     obj = _cache.getElement(expression);
139
140     if(obj != null) {
141       pattern = (Pattern)obj;
142
143       if(pattern.getOptions() == options)
144     return pattern;
145     }
146
147     pattern = _compiler.compile(expression, options);
148     _cache.addElement(expression, pattern);
149
150     return pattern;
151   }
152
153
154   /**
155    * Same as calling
156    * <blockquote><pre>
157    * addPattern(expression, 0);
158    * </pre></blockquote>
159    * @exception MalformedPatternException If there is an error in compiling
160    * the regular expression.
161    */
162   public final synchronized Pattern addPattern(String JavaDoc expression)
163        throws MalformedPatternException
164   {
165     return addPattern(expression, 0);
166   }
167
168
169   /**
170    * This method fetches a pattern from the cache. It is nearly identical
171    * to {@link #addPattern addPattern()} except that it doesn't
172    * throw a MalformedPatternException. If the pattern is not in the
173    * cache, it is compiled, placed in the cache, and returned. If
174    * the pattern cannot be compiled successfully, it
175    * throws a MalformedCachePatternException.
176    * Note that this exception is derived from RuntimeException, which means
177    * you are NOT forced to catch it by the compiler. Please refer to
178    * {@link MalformedCachePatternException} for a discussion of
179    * when you should and shouldn't catch this exception.
180    * <p>
181    * @param expression The regular expression to fetch from the cache in
182    * compiled form.
183    * @param options The compilation options to use when compiling the
184    * expression.
185    * @return The Pattern corresponding to the String representation of the
186    * regular expression.
187    * @exception MalformedCachePatternException If there is an error in
188    * compiling the regular expression.
189    */
190   public final synchronized Pattern getPattern(String JavaDoc expression, int options)
191        throws MalformedCachePatternException
192   {
193     Pattern result = null;
194
195     try {
196       result = addPattern(expression, options);
197     } catch(MalformedPatternException e) {
198       throw new MalformedCachePatternException("Invalid expression: " +
199                            expression + "\n" +
200                            e.getMessage());
201     }
202
203     return result;
204   }
205
206
207   /**
208    * Same as calling
209    * <blockquote><pre>
210    * getPattern(expression, 0)
211    * </pre></blockquote>
212    */
213   public final synchronized Pattern getPattern(String JavaDoc expression)
214        throws MalformedCachePatternException
215   {
216     return getPattern(expression, 0);
217   }
218
219
220   /**
221    * Returns the number of elements in the cache, not to be confused with
222    * the {@link #capacity()} which returns the number
223    * of elements that can be held in the cache at one time.
224    * <p>
225    * @return The current size of the cache (i.e., the number of elements
226    * currently cached).
227    */
228   public final int size() { return _cache.size(); }
229
230   /**
231    * Returns the maximum number of patterns that can be cached at one time.
232    * <p>
233    * @return The maximum number of patterns that can be cached at one time.
234    */
235   public final int capacity() { return _cache.capacity(); }
236 }
237
Popular Tags