001 /*
002 * Copyright 2002-2004 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005 * use this file except in compliance with the License. You may obtain a copy of
006 * 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, WITHOUT
012 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013 * License for the specific language governing permissions and limitations under
014 * the License.
015 */
016 package org.springframework.rules.closure;
017
018 import org.springframework.rules.constraint.Constraint;
019
020 /**
021 * A interface to be implemented by objects which encapsulate a workflow process
022 * template that generates elements for processing. For example, a template
023 * process might produce records from a file for processing.
024 * <p>
025 * A user-provided closure call back is passed in on process execution and is
026 * called to insert custom processing within the template.
027 * <p>
028 * For example, the following code snippet demonstrates a generator that
029 * produces parsed csv records from an underlying file resource. In this case,
030 * this <code>recordGenerator</code> encapsulates required resource management
031 * (opening/closing resources) and the algorithm to parse / iterate over
032 * records. The results (a single parsed record) are passed to the callback for
033 * processing.
034 *
035 * <pre>
036 * ElementGenerator recordGenerator = new CsvRecordGenerator(new FileSystemResource(file));
037 * recordGenerator.run(new Block() {
038 * protected void handle(Object csvRecord) {
039 * // process each record
040 * }
041 * });
042 * </pre>
043 *
044 * This is a generic equivalent to approaches used throughout The Spring
045 * Framework, including Spring's JDBC Template for processing DB query result
046 * sets. In addition to providing a common callback interface, it is intended
047 * for convenience in situations where defining a separate callback hierarchy to
048 * support a template callback approach is overkill.
049 *
050 * @author Keith Donald
051 */
052 public interface ElementGenerator extends ClosureTemplate {
053
054 /**
055 * Does this process produce an element matching the given criteria?
056 *
057 * @param constraint the criteria
058 * @return <code>true</code> if yes, <code>false</code> otherwise
059 */
060 boolean anyTrue(Constraint constraint);
061
062 /**
063 * Does this process produce all elements matching the given criteria?
064 *
065 * @param constraint the criteria
066 * @return <code>true</code> if yes, <code>false</code> otherwise
067 */
068 boolean allTrue(Constraint constraint);
069
070 /**
071 * Find the first element that matches the given criteria.
072 *
073 * @param constraint the criteria
074 * @return the first element, or null if none found.
075 */
076 Object findFirst(Constraint constraint);
077
078 /**
079 * Find the first element that matches the given criteria, return
080 * <code>defaultIfNoneFound</code> if none found.
081 *
082 * @param constraint the constraint
083 * @param defaultIfNoneFound none found object
084 * @return the first match, or defaultIfNoneFound if no match found
085 */
086 Object findFirst(Constraint constraint, Object defaultIfNoneFound);
087
088 /**
089 * Find all elements produced by ths template that match the specified
090 * criteria.
091 *
092 * @param constraint the criteria
093 * @return the elements
094 */
095 ElementGenerator findAll(Constraint constraint);
096
097 /**
098 * Execute the template until the specified condition is true
099 *
100 * @param templateCallback the callback
101 * @param constraint the constraint condition
102 */
103 void runUntil(Closure templateCallback, Constraint constraint);
104
105 /**
106 * Stop this process after it has started.
107 */
108 void stop() throws IllegalStateException;
109 }