001: /*
002: * Copyright 2002-2004,2006 The Apache Software Foundation
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.collections;
017:
018: import java.util.Collection;
019: import java.util.Iterator;
020: import java.util.Map;
021:
022: import org.apache.commons.collections.functors.ChainedClosure;
023: import org.apache.commons.collections.functors.EqualPredicate;
024: import org.apache.commons.collections.functors.ExceptionClosure;
025: import org.apache.commons.collections.functors.ForClosure;
026: import org.apache.commons.collections.functors.IfClosure;
027: import org.apache.commons.collections.functors.InvokerTransformer;
028: import org.apache.commons.collections.functors.NOPClosure;
029: import org.apache.commons.collections.functors.SwitchClosure;
030: import org.apache.commons.collections.functors.TransformerClosure;
031: import org.apache.commons.collections.functors.WhileClosure;
032:
033: /**
034: * <code>ClosureUtils</code> provides reference implementations and utilities
035: * for the Closure functor interface. The supplied closures are:
036: * <ul>
037: * <li>Invoker - invokes a method on the input object
038: * <li>For - repeatedly calls a closure for a fixed number of times
039: * <li>While - repeatedly calls a closure while a predicate is true
040: * <li>DoWhile - repeatedly calls a closure while a predicate is true
041: * <li>Chained - chains two or more closures together
042: * <li>Switch - calls one closure based on one or more predicates
043: * <li>SwitchMap - calls one closure looked up from a Map
044: * <li>Transformer - wraps a Transformer as a Closure
045: * <li>NOP - does nothing
046: * <li>Exception - always throws an exception
047: * </ul>
048: * All the supplied closures are Serializable.
049: *
050: * @since Commons Collections 3.0
051: * @version $Revision: 375766 $ $Date: 2006-02-07 23:10:36 +0000 (Tue, 07 Feb 2006) $
052: *
053: * @author Stephen Colebourne
054: * @author Matt Benson
055: */
056: public class ClosureUtils {
057:
058: /**
059: * This class is not normally instantiated.
060: */
061: public ClosureUtils() {
062: super ();
063: }
064:
065: /**
066: * Gets a Closure that always throws an exception.
067: * This could be useful during testing as a placeholder.
068: *
069: * @see org.apache.commons.collections.functors.ExceptionClosure
070: *
071: * @return the closure
072: */
073: public static Closure exceptionClosure() {
074: return ExceptionClosure.INSTANCE;
075: }
076:
077: /**
078: * Gets a Closure that will do nothing.
079: * This could be useful during testing as a placeholder.
080: *
081: * @see org.apache.commons.collections.functors.NOPClosure
082: *
083: * @return the closure
084: */
085: public static Closure nopClosure() {
086: return NOPClosure.INSTANCE;
087: }
088:
089: /**
090: * Creates a Closure that calls a Transformer each time it is called.
091: * The transformer will be called using the closure's input object.
092: * The transformer's result will be ignored.
093: *
094: * @see org.apache.commons.collections.functors.TransformerClosure
095: *
096: * @param transformer the transformer to run each time in the closure, null means nop
097: * @return the closure
098: */
099: public static Closure asClosure(Transformer transformer) {
100: return TransformerClosure.getInstance(transformer);
101: }
102:
103: /**
104: * Creates a Closure that will call the closure <code>count</code> times.
105: * <p>
106: * A null closure or zero count returns the <code>NOPClosure</code>.
107: *
108: * @see org.apache.commons.collections.functors.ForClosure
109: *
110: * @param count the number of times to loop
111: * @param closure the closure to call repeatedly
112: * @return the <code>for</code> closure
113: */
114: public static Closure forClosure(int count, Closure closure) {
115: return ForClosure.getInstance(count, closure);
116: }
117:
118: /**
119: * Creates a Closure that will call the closure repeatedly until the
120: * predicate returns false.
121: *
122: * @see org.apache.commons.collections.functors.WhileClosure
123: *
124: * @param predicate the predicate to use as an end of loop test, not null
125: * @param closure the closure to call repeatedly, not null
126: * @return the <code>while</code> closure
127: * @throws IllegalArgumentException if either argument is null
128: */
129: public static Closure whileClosure(Predicate predicate,
130: Closure closure) {
131: return WhileClosure.getInstance(predicate, closure, false);
132: }
133:
134: /**
135: * Creates a Closure that will call the closure once and then repeatedly
136: * until the predicate returns false.
137: *
138: * @see org.apache.commons.collections.functors.WhileClosure
139: *
140: * @param closure the closure to call repeatedly, not null
141: * @param predicate the predicate to use as an end of loop test, not null
142: * @return the <code>do-while</code> closure
143: * @throws IllegalArgumentException if either argument is null
144: */
145: public static Closure doWhileClosure(Closure closure,
146: Predicate predicate) {
147: return WhileClosure.getInstance(predicate, closure, true);
148: }
149:
150: /**
151: * Creates a Closure that will invoke a specific method on the closure's
152: * input object by reflection.
153: *
154: * @see org.apache.commons.collections.functors.InvokerTransformer
155: * @see org.apache.commons.collections.functors.TransformerClosure
156: *
157: * @param methodName the name of the method
158: * @return the <code>invoker</code> closure
159: * @throws IllegalArgumentException if the method name is null
160: */
161: public static Closure invokerClosure(String methodName) {
162: // reuse transformer as it has caching - this is lazy really, should have inner class here
163: return asClosure(InvokerTransformer.getInstance(methodName));
164: }
165:
166: /**
167: * Creates a Closure that will invoke a specific method on the closure's
168: * input object by reflection.
169: *
170: * @see org.apache.commons.collections.functors.InvokerTransformer
171: * @see org.apache.commons.collections.functors.TransformerClosure
172: *
173: * @param methodName the name of the method
174: * @param paramTypes the parameter types
175: * @param args the arguments
176: * @return the <code>invoker</code> closure
177: * @throws IllegalArgumentException if the method name is null
178: * @throws IllegalArgumentException if the paramTypes and args don't match
179: */
180: public static Closure invokerClosure(String methodName,
181: Class[] paramTypes, Object[] args) {
182: // reuse transformer as it has caching - this is lazy really, should have inner class here
183: return asClosure(InvokerTransformer.getInstance(methodName,
184: paramTypes, args));
185: }
186:
187: /**
188: * Create a new Closure that calls two Closures, passing the result of
189: * the first into the second.
190: *
191: * @see org.apache.commons.collections.functors.ChainedClosure
192: *
193: * @param closure1 the first closure
194: * @param closure2 the second closure
195: * @return the <code>chained</code> closure
196: * @throws IllegalArgumentException if either closure is null
197: */
198: public static Closure chainedClosure(Closure closure1,
199: Closure closure2) {
200: return ChainedClosure.getInstance(closure1, closure2);
201: }
202:
203: /**
204: * Create a new Closure that calls each closure in turn, passing the
205: * result into the next closure.
206: *
207: * @see org.apache.commons.collections.functors.ChainedClosure
208: *
209: * @param closures an array of closures to chain
210: * @return the <code>chained</code> closure
211: * @throws IllegalArgumentException if the closures array is null
212: * @throws IllegalArgumentException if any closure in the array is null
213: */
214: public static Closure chainedClosure(Closure[] closures) {
215: return ChainedClosure.getInstance(closures);
216: }
217:
218: /**
219: * Create a new Closure that calls each closure in turn, passing the
220: * result into the next closure. The ordering is that of the iterator()
221: * method on the collection.
222: *
223: * @see org.apache.commons.collections.functors.ChainedClosure
224: *
225: * @param closures a collection of closures to chain
226: * @return the <code>chained</code> closure
227: * @throws IllegalArgumentException if the closures collection is null
228: * @throws IllegalArgumentException if the closures collection is empty
229: * @throws IllegalArgumentException if any closure in the collection is null
230: */
231: public static Closure chainedClosure(Collection closures) {
232: return ChainedClosure.getInstance(closures);
233: }
234:
235: /**
236: * Create a new Closure that calls another closure based on the
237: * result of the specified predicate.
238: *
239: * @see org.apache.commons.collections.functors.IfClosure
240: *
241: * @param predicate the validating predicate
242: * @param trueClosure the closure called if the predicate is true
243: * @return the <code>if</code> closure
244: * @throws IllegalArgumentException if the predicate is null
245: * @throws IllegalArgumentException if the closure is null
246: * @since Commons Collections 3.2
247: */
248: public static Closure ifClosure(Predicate predicate,
249: Closure trueClosure) {
250: return IfClosure.getInstance(predicate, trueClosure);
251: }
252:
253: /**
254: * Create a new Closure that calls one of two closures depending
255: * on the specified predicate.
256: *
257: * @see org.apache.commons.collections.functors.IfClosure
258: *
259: * @param predicate the predicate to switch on
260: * @param trueClosure the closure called if the predicate is true
261: * @param falseClosure the closure called if the predicate is false
262: * @return the <code>switch</code> closure
263: * @throws IllegalArgumentException if the predicate is null
264: * @throws IllegalArgumentException if either closure is null
265: */
266: public static Closure ifClosure(Predicate predicate,
267: Closure trueClosure, Closure falseClosure) {
268: return IfClosure.getInstance(predicate, trueClosure,
269: falseClosure);
270: }
271:
272: /**
273: * Create a new Closure that calls one of the closures depending
274: * on the predicates.
275: * <p>
276: * The closure at array location 0 is called if the predicate at array
277: * location 0 returned true. Each predicate is evaluated
278: * until one returns true.
279: *
280: * @see org.apache.commons.collections.functors.SwitchClosure
281: *
282: * @param predicates an array of predicates to check, not null
283: * @param closures an array of closures to call, not null
284: * @return the <code>switch</code> closure
285: * @throws IllegalArgumentException if the either array is null
286: * @throws IllegalArgumentException if any element in the arrays is null
287: * @throws IllegalArgumentException if the arrays are different sizes
288: */
289: public static Closure switchClosure(Predicate[] predicates,
290: Closure[] closures) {
291: return SwitchClosure.getInstance(predicates, closures, null);
292: }
293:
294: /**
295: * Create a new Closure that calls one of the closures depending
296: * on the predicates.
297: * <p>
298: * The closure at array location 0 is called if the predicate at array
299: * location 0 returned true. Each predicate is evaluated
300: * until one returns true. If no predicates evaluate to true, the default
301: * closure is called.
302: *
303: * @see org.apache.commons.collections.functors.SwitchClosure
304: *
305: * @param predicates an array of predicates to check, not null
306: * @param closures an array of closures to call, not null
307: * @param defaultClosure the default to call if no predicate matches
308: * @return the <code>switch</code> closure
309: * @throws IllegalArgumentException if the either array is null
310: * @throws IllegalArgumentException if any element in the arrays is null
311: * @throws IllegalArgumentException if the arrays are different sizes
312: */
313: public static Closure switchClosure(Predicate[] predicates,
314: Closure[] closures, Closure defaultClosure) {
315: return SwitchClosure.getInstance(predicates, closures,
316: defaultClosure);
317: }
318:
319: /**
320: * Create a new Closure that calls one of the closures depending
321: * on the predicates.
322: * <p>
323: * The Map consists of Predicate keys and Closure values. A closure
324: * is called if its matching predicate returns true. Each predicate is evaluated
325: * until one returns true. If no predicates evaluate to true, the default
326: * closure is called. The default closure is set in the map with a
327: * null key. The ordering is that of the iterator() method on the entryset
328: * collection of the map.
329: *
330: * @see org.apache.commons.collections.functors.SwitchClosure
331: *
332: * @param predicatesAndClosures a map of predicates to closures
333: * @return the <code>switch</code> closure
334: * @throws IllegalArgumentException if the map is null
335: * @throws IllegalArgumentException if the map is empty
336: * @throws IllegalArgumentException if any closure in the map is null
337: * @throws ClassCastException if the map elements are of the wrong type
338: */
339: public static Closure switchClosure(Map predicatesAndClosures) {
340: return SwitchClosure.getInstance(predicatesAndClosures);
341: }
342:
343: /**
344: * Create a new Closure that uses the input object as a key to find the
345: * closure to call.
346: * <p>
347: * The Map consists of object keys and Closure values. A closure
348: * is called if the input object equals the key. If there is no match, the
349: * default closure is called. The default closure is set in the map
350: * using a null key.
351: *
352: * @see org.apache.commons.collections.functors.SwitchClosure
353: *
354: * @param objectsAndClosures a map of objects to closures
355: * @return the closure
356: * @throws IllegalArgumentException if the map is null
357: * @throws IllegalArgumentException if the map is empty
358: * @throws IllegalArgumentException if any closure in the map is null
359: */
360: public static Closure switchMapClosure(Map objectsAndClosures) {
361: Closure[] trs = null;
362: Predicate[] preds = null;
363: if (objectsAndClosures == null) {
364: throw new IllegalArgumentException(
365: "The object and closure map must not be null");
366: }
367: Closure def = (Closure) objectsAndClosures.remove(null);
368: int size = objectsAndClosures.size();
369: trs = new Closure[size];
370: preds = new Predicate[size];
371: int i = 0;
372: for (Iterator it = objectsAndClosures.entrySet().iterator(); it
373: .hasNext();) {
374: Map.Entry entry = (Map.Entry) it.next();
375: preds[i] = EqualPredicate.getInstance(entry.getKey());
376: trs[i] = (Closure) entry.getValue();
377: i++;
378: }
379: return switchClosure(preds, trs, def);
380: }
381:
382: }
|