osgi/runtime/org.argeo.osgi.boot/src/main/java/org/argeo/osgi/boot/internal/springutil/CollectionUtils.java

   1 /*
   2  * Copyright 2002-2008 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.argeo.osgi.boot.internal.springutil;
  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 single 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 if there is a clear match,
 208          * or <code>null</code> if none or more than one such value found
 209          */
 210         public static Object findValueOfType(Collection collection, Class type) {
 211                 if (isEmpty(collection)) {
 212                         return null;
 213                 }
 214                 Object value = null;
 215                 for (Iterator it = collection.iterator(); it.hasNext();) {
 216                         Object obj = it.next();
 217                         if (type == null || type.isInstance(obj)) {
 218                                 if (value != null) {
 219                                         // More than one value found... no clear single value.
 220                                         return null;
 221                                 }
 222                                 value = obj;
 223                         }
 224                 }
 225                 return value;
 226         }
 227
 228         /**
 229          * Find a single 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 value of one of the given types found if there is a clear match,
 235          * or <code>null</code> if none or more than one such value found
 236          */
 237         public static Object findValueOfType(Collection collection, Class[] types) {
 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 }