CollectionUtils


1   /*
2    * Copyright 2002-2007 the original author or authors.
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  
17  package org.springframework.util;
18  
19  import java.util.Arrays  ;
20  import java.util.Collection  ;
21  import java.util.Enumeration  ;
22  import java.util.Iterator  ;
23  import java.util.List  ;
24  import java.util.Map  ;
25  import java.util.Properties  ;
26  
27  /**
28   * Miscellaneous collection utility methods.
29   * Mainly for internal use within the framework.
30   *
31   * @author Juergen Hoeller
32   * @author Rob Harrop
33   * @since 1.1.3
34   */
35  public abstract class CollectionUtils {
36  
37      /**
38       * Return <code>true</code> if the supplied Collection is <code>null</code>
39       * or empty. Otherwise, return <code>false</code>.
40       * @param collection the Collection to check
41       * @return whether the given Collection is empty
42       */
43      public static boolean isEmpty(Collection   collection) {
44          return (collection == null || collection.isEmpty());
45      }
46  
47      /**
48       * Return <code>true</code> if the supplied Map is <code>null</code>
49       * or empty. Otherwise, return <code>false</code>.
50       * @param map the Map to check
51       * @return whether the given Map is empty
52       */
53      public static boolean isEmpty(Map   map) {
54          return (map == null || map.isEmpty());
55      }
56  
57      /**
58       * Convert the supplied array into a List. A primitive array gets
59       * converted into a List of the appropriate wrapper type.
60       * <p>A <code>null</code> source value will be converted to an
61       * empty List.
62       * @param source the (potentially primitive) array
63       * @return the converted List result
64       * @see ObjectUtils#toObjectArray(Object)
65       */
66      public static List   arrayToList(Object   source) {
67          return Arrays.asList(ObjectUtils.toObjectArray(source));
68      }
69  
70      /**
71       * Merge the given array into the given Collection.
72       * @param array the array to merge (may be <code>null</code>)
73       * @param collection the target Collection to merge the array into
74       */
75      public static void mergeArrayIntoCollection(Object   array, Collection   collection) {
76          if (collection == null) {
77              throw new IllegalArgumentException  ("Collection must not be null");
78          }
79          Object  [] arr = ObjectUtils.toObjectArray(array);
80          for (int i = 0; i < arr.length; i++) {
81              collection.add(arr[i]);
82          }
83      }
84  
85      /**
86       * Merge the given Properties instance into the given Map,
87       * copying all properties (key-value pairs) over.
88       * <p>Uses <code>Properties.propertyNames()</code> to even catch
89       * default properties linked into the original Properties instance.
90       * @param props the Properties instance to merge (may be <code>null</code>)
91       * @param map the target Map to merge the properties into
92       */
93      public static void mergePropertiesIntoMap(Properties   props, Map   map) {
94          if (map == null) {
95              throw new IllegalArgumentException  ("Map must not be null");
96          }
97          if (props != null) {
98              for (Enumeration   en = props.propertyNames(); en.hasMoreElements();) {
99                  String   key = (String  ) en.nextElement();
100                 map.put(key, props.getProperty(key));
101             }
102         }
103     }
104 
105 
106     /**
107      * Check whether the given Iterator contains the given element.
108      * @param iterator the Iterator to check
109      * @param element the element to look for
110      * @return <code>true</code> if found, <code>false</code> else
111      */
112     public static boolean contains(Iterator   iterator, Object   element) {
113         if (iterator != null) {
114             while (iterator.hasNext()) {
115                 Object   candidate = iterator.next();
116                 if (ObjectUtils.nullSafeEquals(candidate, element)) {
117                     return true;
118                 }
119             }
120         }
121         return false;
122     }
123 
124     /**
125      * Check whether the given Enumeration contains the given element.
126      * @param enumeration the Enumeration to check
127      * @param element the element to look for
128      * @return <code>true</code> if found, <code>false</code> else
129      */
130     public static boolean contains(Enumeration   enumeration, Object   element) {
131         if (enumeration != null) {
132             while (enumeration.hasMoreElements()) {
133                 Object   candidate = enumeration.nextElement();
134                 if (ObjectUtils.nullSafeEquals(candidate, element)) {
135                     return true;
136                 }
137             }
138         }
139         return false;
140     }
141 
142     /**
143      * Check whether the given Collection contains the given element instance.
144      * <p>Enforces the given instance to be present, rather than returning
145      * <code>true</code> for an equal element as well.
146      * @param collection the Collection to check
147      * @param element the element to look for
148      * @return <code>true</code> if found, <code>false</code> else
149      */
150     public static boolean containsInstance(Collection   collection, Object   element) {
151         if (collection != null) {
152             for (Iterator   it = collection.iterator(); it.hasNext();) {
153                 Object   candidate = it.next();
154                 if (candidate == element) {
155                     return true;
156                 }
157             }
158         }
159         return false;
160     }
161 
162     /**
163      * Return <code>true</code> if any element in '<code>candidates</code>' is
164      * contained in '<code>source</code>'; otherwise returns <code>false</code>.
165      * @param source the source Collection
166      * @param candidates the candidates to search for
167      * @return whether any of the candidates has been found
168      */
169     public static boolean containsAny(Collection   source, Collection   candidates) {
170         if (isEmpty(source) || isEmpty(candidates)) {
171             return false;
172         }
173         for (Iterator   it = candidates.iterator(); it.hasNext();) {
174             if (source.contains(it.next())) {
175                 return true;
176             }
177         }
178         return false;
179     }
180 
181     /**
182      * Return the first element in '<code>candidates</code>' that is contained in
183      * '<code>source</code>'. If no element in '<code>candidates</code>' is present in
184      * '<code>source</code>' returns <code>null</code>. Iteration order is
185      * {@link Collection} implementation specific.
186      * @param source the source Collection
187      * @param candidates the candidates to search for
188      * @return the first present object, or <code>null</code> if not found
189      */
190     public static Object   findFirstMatch(Collection   source, Collection   candidates) {
191         if (isEmpty(source) || isEmpty(candidates)) {
192             return null;
193         }
194         for (Iterator   it = candidates.iterator(); it.hasNext();) {
195             Object   candidate = it.next();
196             if (source.contains(candidate)) {
197                 return candidate;
198             }
199         }
200         return null;
201     }
202 
203     /**
204      * Find a value of the given type in the given Collection.
205      * @param collection the Collection to search
206      * @param type the type to look for
207      * @return a value of the given type found, or <code>null</code> if none
208      * @throws IllegalArgumentException if more than one value of the given type found
209      */
210     public static Object   findValueOfType(Collection   collection, Class   type) throws IllegalArgumentException   {
211         if (isEmpty(collection)) {
212             return null;
213         }
214         Class   typeToUse = (type != null ? type : Object  .class);
215         Object   value = null;
216         for (Iterator   it = collection.iterator(); it.hasNext();) {
217             Object   obj = it.next();
218             if (typeToUse.isInstance(obj)) {
219                 if (value != null) {
220                     throw new IllegalArgumentException  ("More than one value of type [" + typeToUse.getName() + "] found");
221                 }
222                 value = obj;
223             }
224         }
225         return value;
226     }
227 
228     /**
229      * Find a value of one of the given types in the given Collection:
230      * searching the Collection for a value of the first type, then
231      * searching for a value of the second type, etc.
232      * @param collection the collection to search
233      * @param types the types to look for, in prioritized order
234      * @return a of one of the given types found, or <code>null</code> if none
235      * @throws IllegalArgumentException if more than one value of the given type found
236      */
237     public static Object   findValueOfType(Collection   collection, Class  [] types) throws IllegalArgumentException   {
238         if (isEmpty(collection) || ObjectUtils.isEmpty(types)) {
239             return null;
240         }
241         for (int i = 0; i < types.length; i++) {
242             Object   value = findValueOfType(collection, types[i]);
243             if (value != null) {
244                 return value;
245             }
246         }
247         return null;
248     }
249 
250     /**
251      * Determine whether the given Collection only contains a single unique object.
252      * @param collection the Collection to check
253      * @return <code>true</code> if the collection contains a single reference or
254      * multiple references to the same instance, <code>false</code> else
255      */
256     public static boolean hasUniqueObject(Collection   collection) {
257         if (isEmpty(collection)) {
258             return false;
259         }
260         boolean hasCandidate = false;
261         Object   candidate = null;
262         for (Iterator   it = collection.iterator(); it.hasNext();) {
263             Object   elem = it.next();
264             if (!hasCandidate) {
265                 hasCandidate = true;
266                 candidate = elem;
267             }
268             else if (candidate != elem) {
269                 return false;
270             }
271         }
272         return true;
273     }
274 
275 }
276
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags