KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > collection > PredicatedCollection


1 /*
2  * Copyright 2003-2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.collections.collection;
17
18 import java.util.Collection JavaDoc;
19 import java.util.Iterator JavaDoc;
20
21 import org.apache.commons.collections.Predicate;
22
23 /**
24  * Decorates another <code>Collection</code> to validate that additions
25  * match a specified predicate.
26  * <p>
27  * This collection exists to provide validation for the decorated collection.
28  * It is normally created to decorate an empty collection.
29  * If an object cannot be added to the collection, an IllegalArgumentException is thrown.
30  * <p>
31  * One usage would be to ensure that no null entries are added to the collection.
32  * <pre>Collection coll = PredicatedCollection.decorate(new ArrayList(), NotNullPredicate.INSTANCE);</pre>
33  * <p>
34  * This class is Serializable from Commons Collections 3.1.
35  *
36  * @since Commons Collections 3.0
37  * @version $Revision: 1.7 $ $Date: 2004/06/03 22:02:13 $
38  *
39  * @author Stephen Colebourne
40  * @author Paul Jack
41  */
42 public class PredicatedCollection extends AbstractSerializableCollectionDecorator {
43
44     /** Serialization version */
45     private static final long serialVersionUID = -5259182142076705162L;
46
47     /** The predicate to use */
48     protected final Predicate predicate;
49
50     /**
51      * Factory method to create a predicated (validating) collection.
52      * <p>
53      * If there are any elements already in the collection being decorated, they
54      * are validated.
55      *
56      * @param coll the collection to decorate, must not be null
57      * @param predicate the predicate to use for validation, must not be null
58      * @return a new predicated collection
59      * @throws IllegalArgumentException if collection or predicate is null
60      * @throws IllegalArgumentException if the collection contains invalid elements
61      */
62     public static Collection JavaDoc decorate(Collection JavaDoc coll, Predicate predicate) {
63         return new PredicatedCollection(coll, predicate);
64     }
65     
66     //-----------------------------------------------------------------------
67 /**
68      * Constructor that wraps (not copies).
69      * <p>
70      * If there are any elements already in the collection being decorated, they
71      * are validated.
72      *
73      * @param coll the collection to decorate, must not be null
74      * @param predicate the predicate to use for validation, must not be null
75      * @throws IllegalArgumentException if collection or predicate is null
76      * @throws IllegalArgumentException if the collection contains invalid elements
77      */
78     protected PredicatedCollection(Collection JavaDoc coll, Predicate predicate) {
79         super(coll);
80         if (predicate == null) {
81             throw new IllegalArgumentException JavaDoc("Predicate must not be null");
82         }
83         this.predicate = predicate;
84         for (Iterator JavaDoc it = coll.iterator(); it.hasNext(); ) {
85             validate(it.next());
86         }
87     }
88
89     /**
90      * Validates the object being added to ensure it matches the predicate.
91      * <p>
92      * The predicate itself should not throw an exception, but return false to
93      * indicate that the object cannot be added.
94      *
95      * @param object the object being added
96      * @throws IllegalArgumentException if the add is invalid
97      */
98     protected void validate(Object JavaDoc object) {
99         if (predicate.evaluate(object) == false) {
100             throw new IllegalArgumentException JavaDoc("Cannot add Object '" + object + "' - Predicate rejected it");
101         }
102     }
103
104     //-----------------------------------------------------------------------
105 /**
106      * Override to validate the object being added to ensure it matches
107      * the predicate.
108      *
109      * @param object the object being added
110      * @return the result of adding to the underlying collection
111      * @throws IllegalArgumentException if the add is invalid
112      */
113     public boolean add(Object JavaDoc object) {
114         validate(object);
115         return getCollection().add(object);
116     }
117
118     /**
119      * Override to validate the objects being added to ensure they match
120      * the predicate. If any one fails, no update is made to the underlying
121      * collection.
122      *
123      * @param coll the collection being added
124      * @return the result of adding to the underlying collection
125      * @throws IllegalArgumentException if the add is invalid
126      */
127     public boolean addAll(Collection JavaDoc coll) {
128         for (Iterator JavaDoc it = coll.iterator(); it.hasNext(); ) {
129             validate(it.next());
130         }
131         return getCollection().addAll(coll);
132     }
133
134 }
135
Popular Tags