KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > BagUtils


1 /*
2  * Copyright 2002-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;
17
18 import org.apache.commons.collections.bag.HashBag;
19 import org.apache.commons.collections.bag.PredicatedBag;
20 import org.apache.commons.collections.bag.PredicatedSortedBag;
21 import org.apache.commons.collections.bag.SynchronizedBag;
22 import org.apache.commons.collections.bag.SynchronizedSortedBag;
23 import org.apache.commons.collections.bag.TransformedBag;
24 import org.apache.commons.collections.bag.TransformedSortedBag;
25 import org.apache.commons.collections.bag.TreeBag;
26 import org.apache.commons.collections.bag.TypedBag;
27 import org.apache.commons.collections.bag.TypedSortedBag;
28 import org.apache.commons.collections.bag.UnmodifiableBag;
29 import org.apache.commons.collections.bag.UnmodifiableSortedBag;
30
31 /**
32  * Provides utility methods and decorators for
33  * {@link Bag} and {@link SortedBag} instances.
34  *
35  * @since Commons Collections 2.1
36  * @version $Revision: 1.20 $ $Date: 2004/04/01 20:12:00 $
37  *
38  * @author Paul Jack
39  * @author Stephen Colebourne
40  * @author Andrew Freeman
41  * @author Matthew Hawthorne
42  */
43 public class BagUtils {
44
45     /**
46      * An empty unmodifiable bag.
47      */
48     public static final Bag EMPTY_BAG = UnmodifiableBag.decorate(new HashBag());
49
50     /**
51      * An empty unmodifiable sorted bag.
52      */
53     public static final Bag EMPTY_SORTED_BAG = UnmodifiableSortedBag.decorate(new TreeBag());
54
55     /**
56      * Instantiation of BagUtils is not intended or required.
57      * However, some tools require an instance to operate.
58      */
59     public BagUtils() {
60     }
61
62     //-----------------------------------------------------------------------
63 /**
64      * Returns a synchronized (thread-safe) bag backed by the given bag.
65      * In order to guarantee serial access, it is critical that all
66      * access to the backing bag is accomplished through the returned bag.
67      * <p>
68      * It is imperative that the user manually synchronize on the returned
69      * bag when iterating over it:
70      *
71      * <pre>
72      * Bag bag = BagUtils.synchronizedBag(new HashBag());
73      * ...
74      * synchronized(bag) {
75      * Iterator i = bag.iterator(); // Must be in synchronized block
76      * while (i.hasNext())
77      * foo(i.next());
78      * }
79      * }
80      * </pre>
81      *
82      * Failure to follow this advice may result in non-deterministic
83      * behavior.
84      *
85      * @param bag the bag to synchronize, must not be null
86      * @return a synchronized bag backed by that bag
87      * @throws IllegalArgumentException if the Bag is null
88      */
89     public static Bag synchronizedBag(Bag bag) {
90         return SynchronizedBag.decorate(bag);
91     }
92
93     /**
94      * Returns an unmodifiable view of the given bag. Any modification
95      * attempts to the returned bag will raise an
96      * {@link UnsupportedOperationException}.
97      *
98      * @param bag the bag whose unmodifiable view is to be returned, must not be null
99      * @return an unmodifiable view of that bag
100      * @throws IllegalArgumentException if the Bag is null
101      */
102     public static Bag unmodifiableBag(Bag bag) {
103         return UnmodifiableBag.decorate(bag);
104     }
105     
106     /**
107      * Returns a predicated (validating) bag backed by the given bag.
108      * <p>
109      * Only objects that pass the test in the given predicate can be added to the bag.
110      * Trying to add an invalid object results in an IllegalArgumentException.
111      * It is important not to use the original bag after invoking this method,
112      * as it is a backdoor for adding invalid objects.
113      *
114      * @param bag the bag to predicate, must not be null
115      * @param predicate the predicate for the bag, must not be null
116      * @return a predicated bag backed by the given bag
117      * @throws IllegalArgumentException if the Bag or Predicate is null
118      */
119     public static Bag predicatedBag(Bag bag, Predicate predicate) {
120         return PredicatedBag.decorate(bag, predicate);
121     }
122     
123     /**
124      * Returns a typed bag backed by the given bag.
125      * <p>
126      * Only objects of the specified type can be added to the bag.
127      *
128      * @param bag the bag to limit to a specific type, must not be null
129      * @param type the type of objects which may be added to the bag
130      * @return a typed bag backed by the specified bag
131      */
132     public static Bag typedBag(Bag bag, Class JavaDoc type) {
133         return TypedBag.decorate(bag, type);
134     }
135     
136     /**
137      * Returns a transformed bag backed by the given bag.
138      * <p>
139      * Each object is passed through the transformer as it is added to the
140      * Bag. It is important not to use the original bag after invoking this
141      * method, as it is a backdoor for adding untransformed objects.
142      *
143      * @param bag the bag to predicate, must not be null
144      * @param transformer the transformer for the bag, must not be null
145      * @return a transformed bag backed by the given bag
146      * @throws IllegalArgumentException if the Bag or Transformer is null
147      */
148     public static Bag transformedBag(Bag bag, Transformer transformer) {
149         return TransformedBag.decorate(bag, transformer);
150     }
151     
152     //-----------------------------------------------------------------------
153 /**
154      * Returns a synchronized (thread-safe) sorted bag backed by the given
155      * sorted bag.
156      * In order to guarantee serial access, it is critical that all
157      * access to the backing bag is accomplished through the returned bag.
158      * <p>
159      * It is imperative that the user manually synchronize on the returned
160      * bag when iterating over it:
161      *
162      * <pre>
163      * SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag());
164      * ...
165      * synchronized(bag) {
166      * Iterator i = bag.iterator(); // Must be in synchronized block
167      * while (i.hasNext())
168      * foo(i.next());
169      * }
170      * }
171      * </pre>
172      *
173      * Failure to follow this advice may result in non-deterministic
174      * behavior.
175      *
176      * @param bag the bag to synchronize, must not be null
177      * @return a synchronized bag backed by that bag
178      * @throws IllegalArgumentException if the SortedBag is null
179      */
180     public static SortedBag synchronizedSortedBag(SortedBag bag) {
181         return SynchronizedSortedBag.decorate(bag);
182     }
183     
184     /**
185      * Returns an unmodifiable view of the given sorted bag. Any modification
186      * attempts to the returned bag will raise an
187      * {@link UnsupportedOperationException}.
188      *
189      * @param bag the bag whose unmodifiable view is to be returned, must not be null
190      * @return an unmodifiable view of that bag
191      * @throws IllegalArgumentException if the SortedBag is null
192      */
193     public static SortedBag unmodifiableSortedBag(SortedBag bag) {
194         return UnmodifiableSortedBag.decorate(bag);
195     }
196     
197     /**
198      * Returns a predicated (validating) sorted bag backed by the given sorted bag.
199      * <p>
200      * Only objects that pass the test in the given predicate can be added to the bag.
201      * Trying to add an invalid object results in an IllegalArgumentException.
202      * It is important not to use the original bag after invoking this method,
203      * as it is a backdoor for adding invalid objects.
204      *
205      * @param bag the sorted bag to predicate, must not be null
206      * @param predicate the predicate for the bag, must not be null
207      * @return a predicated bag backed by the given bag
208      * @throws IllegalArgumentException if the SortedBag or Predicate is null
209      */
210     public static SortedBag predicatedSortedBag(SortedBag bag, Predicate predicate) {
211         return PredicatedSortedBag.decorate(bag, predicate);
212     }
213     
214     /**
215      * Returns a typed sorted bag backed by the given bag.
216      * <p>
217      * Only objects of the specified type can be added to the bag.
218      *
219      * @param bag the bag to limit to a specific type, must not be null
220      * @param type the type of objects which may be added to the bag
221      * @return a typed bag backed by the specified bag
222      */
223     public static SortedBag typedSortedBag(SortedBag bag, Class JavaDoc type) {
224         return TypedSortedBag.decorate(bag, type);
225     }
226     
227     /**
228      * Returns a transformed sorted bag backed by the given bag.
229      * <p>
230      * Each object is passed through the transformer as it is added to the
231      * Bag. It is important not to use the original bag after invoking this
232      * method, as it is a backdoor for adding untransformed objects.
233      *
234      * @param bag the bag to predicate, must not be null
235      * @param transformer the transformer for the bag, must not be null
236      * @return a transformed bag backed by the given bag
237      * @throws IllegalArgumentException if the Bag or Transformer is null
238      */
239     public static SortedBag transformedSortedBag(SortedBag bag, Transformer transformer) {
240         return TransformedSortedBag.decorate(bag, transformer);
241     }
242     
243 }
244
Popular Tags