SetUtils


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 java.util.Collection  ;
19  import java.util.Collections  ;
20  import java.util.Iterator  ;
21  import java.util.Set  ;
22  import java.util.SortedSet  ;
23  import java.util.TreeSet  ;
24  
25  import org.apache.commons.collections.set.ListOrderedSet;
26  import org.apache.commons.collections.set.PredicatedSet;
27  import org.apache.commons.collections.set.PredicatedSortedSet;
28  import org.apache.commons.collections.set.SynchronizedSet;
29  import org.apache.commons.collections.set.SynchronizedSortedSet;
30  import org.apache.commons.collections.set.TransformedSet;
31  import org.apache.commons.collections.set.TransformedSortedSet;
32  import org.apache.commons.collections.set.TypedSet;
33  import org.apache.commons.collections.set.TypedSortedSet;
34  import org.apache.commons.collections.set.UnmodifiableSet;
35  import org.apache.commons.collections.set.UnmodifiableSortedSet;
36  
37  /**
38   * Provides utility methods and decorators for
39   * {@link Set} and {@link SortedSet} instances.
40   *
41   * @since Commons Collections 2.1
42   * @version $Revision: 1.26 $ $Date: 2004/04/01 20:12:00 $
43   * 
44   * @author Paul Jack
45   * @author Stephen Colebourne
46   * @author Neil O'Toole
47   * @author Matthew Hawthorne
48   */
49  public class SetUtils {
50  
51      /**
52       * An empty unmodifiable set.
53       * This uses the {@link Collections} implementation 
54       * and is provided for completeness.
55       */
56      public static final Set   EMPTY_SET = Collections.EMPTY_SET;
57      /**
58       * An empty unmodifiable sorted set.
59       * This is not provided in the JDK.
60       */
61      public static final SortedSet   EMPTY_SORTED_SET = UnmodifiableSortedSet.decorate(new TreeSet  ());
62  
63      /**
64       * <code>SetUtils</code> should not normally be instantiated.
65       */
66      public SetUtils() {
67      }
68  
69      //-----------------------------------------------------------------------
70      /**
71       * Tests two sets for equality as per the <code>equals()</code> contract
72       * in {@link java.util.Set#equals(java.lang.Object)}.
73       * <p>
74       * This method is useful for implementing <code>Set</code> when you cannot
75       * extend AbstractSet. The method takes Collection instances to enable other
76       * collection types to use the Set implementation algorithm.
77       * <p>
78       * The relevant text (slightly paraphrased as this is a static method) is:
79       * <blockquote>
80       * <p>Two sets are considered equal if they have
81       * the same size, and every member of the first set is contained in
82       * the second. This ensures that the <tt>equals</tt> method works
83       * properly across different implementations of the <tt>Set</tt>
84       * interface.</p>
85       * 
86       * <p>
87       * This implementation first checks if the two sets are the same object: 
88       * if so it returns <tt>true</tt>.  Then, it checks if the two sets are
89       * identical in size; if not, it returns false. If so, it returns
90       * <tt>a.containsAll((Collection) b)</tt>.</p>
91       * </blockquote>
92       * 
93       * @see java.util.Set
94       * @param set1  the first set, may be null
95       * @param set2  the second set, may be null
96       * @return whether the sets are equal by value comparison
97       */
98      public static boolean isEqualSet(final Collection   set1, final Collection   set2) {
99          if (set1 == set2) {
100             return true;
101         }
102         if (set1 == null || set2 == null || set1.size() != set2.size()) {
103             return false;
104         }
105 
106         return set1.containsAll(set2);
107     }
108 
109     /**
110      * Generates a hash code using the algorithm specified in 
111      * {@link java.util.Set#hashCode()}.
112      * <p>
113      * This method is useful for implementing <code>Set</code> when you cannot
114      * extend AbstractSet. The method takes Collection instances to enable other
115      * collection types to use the Set implementation algorithm.
116      * 
117      * @see java.util.Set#hashCode()
118      * @param set  the set to calculate the hash code for, may be null
119      * @return the hash code
120      */
121     public static int hashCodeForSet(final Collection   set) {
122         if (set == null) {
123             return 0;
124         }
125         int hashCode = 0;
126         Iterator   it = set.iterator();
127         Object   obj = null;
128 
129         while (it.hasNext()) {
130             obj = it.next();
131             if (obj != null) {
132                 hashCode += obj.hashCode();
133             }
134         }
135         return hashCode;
136     }
137     
138     //-----------------------------------------------------------------------
139     /**
140      * Returns a synchronized set backed by the given set.
141      * <p>
142      * You must manually synchronize on the returned buffer's iterator to 
143      * avoid non-deterministic behavior:
144      *  
145      * <pre>
146      * Set s = SetUtils.synchronizedSet(mySet);
147      * synchronized (s) {
148      *     Iterator i = s.iterator();
149      *     while (i.hasNext()) {
150      *         process (i.next());
151      *     }
152      * }
153      * </pre>
154      * 
155      * This method uses the implementation in the decorators subpackage.
156      * 
157      * @param set  the set to synchronize, must not be null
158      * @return a synchronized set backed by the given set
159      * @throws IllegalArgumentException  if the set is null
160      */
161     public static Set   synchronizedSet(Set   set) {
162         return SynchronizedSet.decorate(set);
163     }
164 
165     /**
166      * Returns an unmodifiable set backed by the given set.
167      * <p>
168      * This method uses the implementation in the decorators subpackage.
169      *
170      * @param set  the set to make unmodifiable, must not be null
171      * @return an unmodifiable set backed by the given set
172      * @throws IllegalArgumentException  if the set is null
173      */
174     public static Set   unmodifiableSet(Set   set) {
175         return UnmodifiableSet.decorate(set);
176     }
177 
178     /**
179      * Returns a predicated (validating) set backed by the given set.
180      * <p>
181      * Only objects that pass the test in the given predicate can be added to the set.
182      * Trying to add an invalid object results in an IllegalArgumentException.
183      * It is important not to use the original set after invoking this method,
184      * as it is a backdoor for adding invalid objects.
185      *
186      * @param set  the set to predicate, must not be null
187      * @param predicate  the predicate for the set, must not be null
188      * @return a predicated set backed by the given set
189      * @throws IllegalArgumentException  if the Set or Predicate is null
190      */
191     public static Set   predicatedSet(Set   set, Predicate predicate) {
192         return PredicatedSet.decorate(set, predicate);
193     }
194 
195     /**
196      * Returns a typed set backed by the given set.
197      * <p>
198      * Only objects of the specified type can be added to the set.
199      * 
200      * @param set  the set to limit to a specific type, must not be null
201      * @param type  the type of objects which may be added to the set
202      * @return a typed set backed by the specified set
203      */
204     public static Set   typedSet(Set   set, Class   type) {
205         return TypedSet.decorate(set, type);
206     }
207     
208     /**
209      * Returns a transformed set backed by the given set.
210      * <p>
211      * Each object is passed through the transformer as it is added to the
212      * Set. It is important not to use the original set after invoking this 
213      * method, as it is a backdoor for adding untransformed objects.
214      *
215      * @param set  the set to transform, must not be null
216      * @param transformer  the transformer for the set, must not be null
217      * @return a transformed set backed by the given set
218      * @throws IllegalArgumentException  if the Set or Transformer is null
219      */
220     public static Set   transformedSet(Set   set, Transformer transformer) {
221         return TransformedSet.decorate(set, transformer);
222     }
223     
224     /**
225      * Returns a set that maintains the order of elements that are added
226      * backed by the given set.
227      * <p>
228      * If an element is added twice, the order is determined by the first add.
229      * The order is observed through the iterator or toArray.
230      *
231      * @param set  the set to order, must not be null
232      * @return an ordered set backed by the given set
233      * @throws IllegalArgumentException  if the Set is null
234      */
235     public static Set   orderedSet(Set   set) {
236         return ListOrderedSet.decorate(set);
237     }
238     
239     //-----------------------------------------------------------------------
240     /**
241      * Returns a synchronized sorted set backed by the given sorted set.
242      * <p>
243      * You must manually synchronize on the returned buffer's iterator to 
244      * avoid non-deterministic behavior:
245      *  
246      * <pre>
247      * Set s = SetUtils.synchronizedSet(mySet);
248      * synchronized (s) {
249      *     Iterator i = s.iterator();
250      *     while (i.hasNext()) {
251      *         process (i.next());
252      *     }
253      * }
254      * </pre>
255      * 
256      * This method uses the implementation in the decorators subpackage.
257      * 
258      * @param set  the sorted set to synchronize, must not be null
259      * @return a synchronized set backed by the given set
260      * @throws IllegalArgumentException  if the set is null
261      */
262     public static SortedSet   synchronizedSortedSet(SortedSet   set) {
263         return SynchronizedSortedSet.decorate(set);
264     }
265 
266     /**
267      * Returns an unmodifiable sorted set backed by the given sorted set.
268      * <p>
269      * This method uses the implementation in the decorators subpackage.
270      *
271      * @param set  the sorted set to make unmodifiable, must not be null
272      * @return an unmodifiable set backed by the given set
273      * @throws IllegalArgumentException  if the set is null
274      */
275     public static SortedSet   unmodifiableSortedSet(SortedSet   set) {
276         return UnmodifiableSortedSet.decorate(set);
277     }
278 
279     /**
280      * Returns a predicated (validating) sorted set backed by the given sorted set.  
281      * <p>
282      * Only objects that pass the test in the given predicate can be added to the set.
283      * Trying to add an invalid object results in an IllegalArgumentException.
284      * It is important not to use the original set after invoking this method,
285      * as it is a backdoor for adding invalid objects.
286      *
287      * @param set  the sorted set to predicate, must not be null
288      * @param predicate  the predicate for the sorted set, must not be null
289      * @return a predicated sorted set backed by the given sorted set
290      * @throws IllegalArgumentException  if the Set or Predicate is null
291      */
292     public static SortedSet   predicatedSortedSet(SortedSet   set, Predicate predicate) {
293         return PredicatedSortedSet.decorate(set, predicate);
294     }
295 
296     /**
297      * Returns a typed sorted set backed by the given set.
298      * <p>
299      * Only objects of the specified type can be added to the set.
300      * 
301      * @param set  the set to limit to a specific type, must not be null
302      * @param type  the type of objects which may be added to the set
303      * @return a typed set backed by the specified set
304      */
305     public static SortedSet   typedSortedSet(SortedSet   set, Class   type) {
306         return TypedSortedSet.decorate(set, type);
307     }
308     
309     /**
310      * Returns a transformed sorted set backed by the given set.
311      * <p>
312      * Each object is passed through the transformer as it is added to the
313      * Set. It is important not to use the original set after invoking this 
314      * method, as it is a backdoor for adding untransformed objects.
315      *
316      * @param set  the set to transform, must not be null
317      * @param transformer  the transformer for the set, must not be null
318      * @return a transformed set backed by the given set
319      * @throws IllegalArgumentException  if the Set or Transformer is null
320      */
321     public static SortedSet   transformedSortedSet(SortedSet   set, Transformer transformer) {
322         return TransformedSortedSet.decorate(set, transformer);
323     }
324     
325 }
326
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags