All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.apache.commons.collections4.MapUtils Maven / Gradle / Ivy

There is a newer version: 5.0.70
Show newest version
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.collections4;

import java.io.PrintStream;
import java.text.NumberFormat;
import java.text.ParseException;
import java.util.ArrayDeque;
import java.util.Collection;
import java.util.Collections;
import java.util.Deque;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;
import java.util.Map.Entry;
import java.util.Properties;
import java.util.ResourceBundle;
import java.util.SortedMap;
import java.util.TreeMap;

import org.apache.commons.collections4.map.AbstractMapDecorator;
import org.apache.commons.collections4.map.AbstractSortedMapDecorator;
import org.apache.commons.collections4.map.FixedSizeMap;
import org.apache.commons.collections4.map.FixedSizeSortedMap;
import org.apache.commons.collections4.map.LazyMap;
import org.apache.commons.collections4.map.LazySortedMap;
import org.apache.commons.collections4.map.ListOrderedMap;
import org.apache.commons.collections4.map.MultiValueMap;
import org.apache.commons.collections4.map.PredicatedMap;
import org.apache.commons.collections4.map.PredicatedSortedMap;
import org.apache.commons.collections4.map.TransformedMap;
import org.apache.commons.collections4.map.TransformedSortedMap;
import org.apache.commons.collections4.map.UnmodifiableMap;
import org.apache.commons.collections4.map.UnmodifiableSortedMap;

/**
 * Provides utility methods and decorators for
 * {@link Map} and {@link SortedMap} instances.
 * 

* It contains various type safe methods * as well as other useful features like deep copying. *

* It also provides the following decorators: * *

    *
  • {@link #fixedSizeMap(Map)} *
  • {@link #fixedSizeSortedMap(SortedMap)} *
  • {@link #lazyMap(Map,Factory)} *
  • {@link #lazyMap(Map,Transformer)} *
  • {@link #lazySortedMap(SortedMap,Factory)} *
  • {@link #lazySortedMap(SortedMap,Transformer)} *
  • {@link #predicatedMap(Map,Predicate,Predicate)} *
  • {@link #predicatedSortedMap(SortedMap,Predicate,Predicate)} *
  • {@link #transformedMap(Map, Transformer, Transformer)} *
  • {@link #transformedSortedMap(SortedMap, Transformer, Transformer)} *
  • {@link #multiValueMap( Map )} *
  • {@link #multiValueMap( Map, Class )} *
  • {@link #multiValueMap( Map, Factory )} *
* * @since 1.0 */ @SuppressWarnings("deprecation") public class MapUtils { /** * An empty unmodifiable sorted map. * This is not provided in the JDK. */ @SuppressWarnings("rawtypes") public static final SortedMap EMPTY_SORTED_MAP = UnmodifiableSortedMap.unmodifiableSortedMap(new TreeMap<>()); /** * String used to indent the verbose and debug Map prints. */ private static final String INDENT_STRING = " "; /** * MapUtils should not normally be instantiated. */ private MapUtils() {} // Type safe getters //------------------------------------------------------------------------- /** * Gets from a Map in a null-safe manner. * * @param the key type * @param the value type * @param map the map to use * @param key the key to look up * @return the value in the Map, null if null map input */ public static V getObject(final Map map, final K key) { if (map != null) { return map.get(key); } return null; } /** * Gets a String from a Map in a null-safe manner. *

* The String is obtained via toString. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a String, null if null map input */ public static String getString(final Map map, final K key) { if (map != null) { final Object answer = map.get(key); if (answer != null) { return answer.toString(); } } return null; } /** * Gets a Boolean from a Map in a null-safe manner. *

* If the value is a Boolean it is returned directly. * If the value is a String and it equals 'true' ignoring case * then true is returned, otherwise false. * If the value is a Number an integer zero value returns * false and non-zero returns true. * Otherwise, null is returned. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a Boolean, null if null map input */ public static Boolean getBoolean(final Map map, final K key) { if (map != null) { final Object answer = map.get(key); if (answer != null) { if (answer instanceof Boolean) { return (Boolean) answer; } if (answer instanceof String) { return Boolean.valueOf((String) answer); } if (answer instanceof Number) { final Number n = (Number) answer; return n.intValue() != 0 ? Boolean.TRUE : Boolean.FALSE; } } } return null; } /** * Gets a Number from a Map in a null-safe manner. *

* If the value is a Number it is returned directly. * If the value is a String it is converted using * {@link NumberFormat#parse(String)} on the system default formatter * returning null if the conversion fails. * Otherwise, null is returned. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a Number, null if null map input */ public static Number getNumber(final Map map, final K key) { if (map != null) { final Object answer = map.get(key); if (answer != null) { if (answer instanceof Number) { return (Number) answer; } if (answer instanceof String) { try { final String text = (String) answer; return NumberFormat.getInstance().parse(text); } catch (final ParseException e) { // NOPMD // failure means null is returned } } } } return null; } /** * Gets a Byte from a Map in a null-safe manner. *

* The Byte is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a Byte, null if null map input */ public static Byte getByte(final Map map, final K key) { final Number answer = getNumber(map, key); if (answer == null) { return null; } if (answer instanceof Byte) { return (Byte) answer; } return Byte.valueOf(answer.byteValue()); } /** * Gets a Short from a Map in a null-safe manner. *

* The Short is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a Short, null if null map input */ public static Short getShort(final Map map, final K key) { final Number answer = getNumber(map, key); if (answer == null) { return null; } if (answer instanceof Short) { return (Short) answer; } return Short.valueOf(answer.shortValue()); } /** * Gets a Integer from a Map in a null-safe manner. *

* The Integer is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a Integer, null if null map input */ public static Integer getInteger(final Map map, final K key) { final Number answer = getNumber(map, key); if (answer == null) { return null; } if (answer instanceof Integer) { return (Integer) answer; } return Integer.valueOf(answer.intValue()); } /** * Gets a Long from a Map in a null-safe manner. *

* The Long is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a Long, null if null map input */ public static Long getLong(final Map map, final K key) { final Number answer = getNumber(map, key); if (answer == null) { return null; } if (answer instanceof Long) { return (Long) answer; } return Long.valueOf(answer.longValue()); } /** * Gets a Float from a Map in a null-safe manner. *

* The Float is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a Float, null if null map input */ public static Float getFloat(final Map map, final K key) { final Number answer = getNumber(map, key); if (answer == null) { return null; } if (answer instanceof Float) { return (Float) answer; } return Float.valueOf(answer.floatValue()); } /** * Gets a Double from a Map in a null-safe manner. *

* The Double is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a Double, null if null map input */ public static Double getDouble(final Map map, final K key) { final Number answer = getNumber(map, key); if (answer == null) { return null; } if (answer instanceof Double) { return (Double) answer; } return Double.valueOf(answer.doubleValue()); } /** * Gets a Map from a Map in a null-safe manner. *

* If the value returned from the specified map is not a Map then * null is returned. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a Map, null if null map input */ public static Map getMap(final Map map, final K key) { if (map != null) { final Object answer = map.get(key); if (answer != null && answer instanceof Map) { return (Map) answer; } } return null; } // Type safe getters with default values //------------------------------------------------------------------------- /** * Looks up the given key in the given map, converting null into the * given default value. * * @param the key type * @param the value type * @param map the map whose value to look up * @param key the key of the value to look up in that map * @param defaultValue what to return if the value is null * @return the value in the map, or defaultValue if the original value * is null or the map is null */ public static V getObject(final Map map, final K key, final V defaultValue) { if (map != null) { final V answer = map.get(key); if (answer != null) { return answer; } } return defaultValue; } /** * Looks up the given key in the given map, converting the result into * a string, using the default value if the conversion fails. * * @param the key type * @param map the map whose value to look up * @param key the key of the value to look up in that map * @param defaultValue what to return if the value is null or if the * conversion fails * @return the value in the map as a string, or defaultValue if the * original value is null, the map is null or the string conversion fails */ public static String getString(final Map map, final K key, final String defaultValue) { String answer = getString(map, key); if (answer == null) { answer = defaultValue; } return answer; } /** * Looks up the given key in the given map, converting the result into * a boolean, using the default value if the conversion fails. * * @param the key type * @param map the map whose value to look up * @param key the key of the value to look up in that map * @param defaultValue what to return if the value is null or if the * conversion fails * @return the value in the map as a boolean, or defaultValue if the * original value is null, the map is null or the boolean conversion fails */ public static Boolean getBoolean(final Map map, final K key, final Boolean defaultValue) { Boolean answer = getBoolean(map, key); if (answer == null) { answer = defaultValue; } return answer; } /** * Looks up the given key in the given map, converting the result into * a number, using the default value if the conversion fails. * * @param the key type * @param map the map whose value to look up * @param key the key of the value to look up in that map * @param defaultValue what to return if the value is null or if the * conversion fails * @return the value in the map as a number, or defaultValue if the * original value is null, the map is null or the number conversion fails */ public static Number getNumber(final Map map, final K key, final Number defaultValue) { Number answer = getNumber(map, key); if (answer == null) { answer = defaultValue; } return answer; } /** * Looks up the given key in the given map, converting the result into * a byte, using the default value if the conversion fails. * * @param the key type * @param map the map whose value to look up * @param key the key of the value to look up in that map * @param defaultValue what to return if the value is null or if the * conversion fails * @return the value in the map as a number, or defaultValue if the * original value is null, the map is null or the number conversion fails */ public static Byte getByte(final Map map, final K key, final Byte defaultValue) { Byte answer = getByte(map, key); if (answer == null) { answer = defaultValue; } return answer; } /** * Looks up the given key in the given map, converting the result into * a short, using the default value if the conversion fails. * * @param the key type * @param map the map whose value to look up * @param key the key of the value to look up in that map * @param defaultValue what to return if the value is null or if the * conversion fails * @return the value in the map as a number, or defaultValue if the * original value is null, the map is null or the number conversion fails */ public static Short getShort(final Map map, final K key, final Short defaultValue) { Short answer = getShort(map, key); if (answer == null) { answer = defaultValue; } return answer; } /** * Looks up the given key in the given map, converting the result into * an integer, using the default value if the conversion fails. * * @param the key type * @param map the map whose value to look up * @param key the key of the value to look up in that map * @param defaultValue what to return if the value is null or if the * conversion fails * @return the value in the map as a number, or defaultValue if the * original value is null, the map is null or the number conversion fails */ public static Integer getInteger(final Map map, final K key, final Integer defaultValue) { Integer answer = getInteger(map, key); if (answer == null) { answer = defaultValue; } return answer; } /** * Looks up the given key in the given map, converting the result into * a long, using the default value if the conversion fails. * * @param the key type * @param map the map whose value to look up * @param key the key of the value to look up in that map * @param defaultValue what to return if the value is null or if the * conversion fails * @return the value in the map as a number, or defaultValue if the * original value is null, the map is null or the number conversion fails */ public static Long getLong(final Map map, final K key, final Long defaultValue) { Long answer = getLong(map, key); if (answer == null) { answer = defaultValue; } return answer; } /** * Looks up the given key in the given map, converting the result into * a float, using the default value if the conversion fails. * * @param the key type * @param map the map whose value to look up * @param key the key of the value to look up in that map * @param defaultValue what to return if the value is null or if the * conversion fails * @return the value in the map as a number, or defaultValue if the * original value is null, the map is null or the number conversion fails */ public static Float getFloat(final Map map, final K key, final Float defaultValue) { Float answer = getFloat(map, key); if (answer == null) { answer = defaultValue; } return answer; } /** * Looks up the given key in the given map, converting the result into * a double, using the default value if the conversion fails. * * @param the key type * @param map the map whose value to look up * @param key the key of the value to look up in that map * @param defaultValue what to return if the value is null or if the * conversion fails * @return the value in the map as a number, or defaultValue if the * original value is null, the map is null or the number conversion fails */ public static Double getDouble(final Map map, final K key, final Double defaultValue) { Double answer = getDouble(map, key); if (answer == null) { answer = defaultValue; } return answer; } /** * Looks up the given key in the given map, converting the result into * a map, using the default value if the conversion fails. * * @param the key type * @param map the map whose value to look up * @param key the key of the value to look up in that map * @param defaultValue what to return if the value is null or if the * conversion fails * @return the value in the map as a number, or defaultValue if the * original value is null, the map is null or the map conversion fails */ public static Map getMap(final Map map, final K key, final Map defaultValue) { Map answer = getMap(map, key); if (answer == null) { answer = defaultValue; } return answer; } // Type safe primitive getters //------------------------------------------------------------------------- /** * Gets a boolean from a Map in a null-safe manner. *

* If the value is a Boolean its value is returned. * If the value is a String and it equals 'true' ignoring case * then true is returned, otherwise false. * If the value is a Number an integer zero value returns * false and non-zero returns true. * Otherwise, false is returned. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a Boolean, false if null map input */ public static boolean getBooleanValue(final Map map, final K key) { return Boolean.TRUE.equals(getBoolean(map, key)); } /** * Gets a byte from a Map in a null-safe manner. *

* The byte is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a byte, 0 if null map input */ public static byte getByteValue(final Map map, final K key) { final Byte byteObject = getByte(map, key); if (byteObject == null) { return 0; } return byteObject.byteValue(); } /** * Gets a short from a Map in a null-safe manner. *

* The short is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a short, 0 if null map input */ public static short getShortValue(final Map map, final K key) { final Short shortObject = getShort(map, key); if (shortObject == null) { return 0; } return shortObject.shortValue(); } /** * Gets an int from a Map in a null-safe manner. *

* The int is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as an int, 0 if null map input */ public static int getIntValue(final Map map, final K key) { final Integer integerObject = getInteger(map, key); if (integerObject == null) { return 0; } return integerObject.intValue(); } /** * Gets a long from a Map in a null-safe manner. *

* The long is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a long, 0L if null map input */ public static long getLongValue(final Map map, final K key) { final Long longObject = getLong(map, key); if (longObject == null) { return 0L; } return longObject.longValue(); } /** * Gets a float from a Map in a null-safe manner. *

* The float is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a float, 0.0F if null map input */ public static float getFloatValue(final Map map, final K key) { final Float floatObject = getFloat(map, key); if (floatObject == null) { return 0f; } return floatObject.floatValue(); } /** * Gets a double from a Map in a null-safe manner. *

* The double is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @return the value in the Map as a double, 0.0 if null map input */ public static double getDoubleValue(final Map map, final K key) { final Double doubleObject = getDouble(map, key); if (doubleObject == null) { return 0d; } return doubleObject.doubleValue(); } // Type safe primitive getters with default values //------------------------------------------------------------------------- /** * Gets a boolean from a Map in a null-safe manner, * using the default value if the conversion fails. *

* If the value is a Boolean its value is returned. * If the value is a String and it equals 'true' ignoring case * then true is returned, otherwise false. * If the value is a Number an integer zero value returns * false and non-zero returns true. * Otherwise, defaultValue is returned. * * @param the key type * @param map the map to use * @param key the key to look up * @param defaultValue return if the value is null or if the conversion fails * @return the value in the Map as a Boolean, defaultValue if null map input */ public static boolean getBooleanValue(final Map map, final K key, final boolean defaultValue) { final Boolean booleanObject = getBoolean(map, key); if (booleanObject == null) { return defaultValue; } return booleanObject.booleanValue(); } /** * Gets a byte from a Map in a null-safe manner, * using the default value if the conversion fails. *

* The byte is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @param defaultValue return if the value is null or if the conversion fails * @return the value in the Map as a byte, defaultValue if null map input */ public static byte getByteValue(final Map map, final K key, final byte defaultValue) { final Byte byteObject = getByte(map, key); if (byteObject == null) { return defaultValue; } return byteObject.byteValue(); } /** * Gets a short from a Map in a null-safe manner, * using the default value if the conversion fails. *

* The short is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @param defaultValue return if the value is null or if the conversion fails * @return the value in the Map as a short, defaultValue if null map input */ public static short getShortValue(final Map map, final K key, final short defaultValue) { final Short shortObject = getShort(map, key); if (shortObject == null) { return defaultValue; } return shortObject.shortValue(); } /** * Gets an int from a Map in a null-safe manner, * using the default value if the conversion fails. *

* The int is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @param defaultValue return if the value is null or if the conversion fails * @return the value in the Map as an int, defaultValue if null map input */ public static int getIntValue(final Map map, final K key, final int defaultValue) { final Integer integerObject = getInteger(map, key); if (integerObject == null) { return defaultValue; } return integerObject.intValue(); } /** * Gets a long from a Map in a null-safe manner, * using the default value if the conversion fails. *

* The long is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @param defaultValue return if the value is null or if the conversion fails * @return the value in the Map as a long, defaultValue if null map input */ public static long getLongValue(final Map map, final K key, final long defaultValue) { final Long longObject = getLong(map, key); if (longObject == null) { return defaultValue; } return longObject.longValue(); } /** * Gets a float from a Map in a null-safe manner, * using the default value if the conversion fails. *

* The float is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @param defaultValue return if the value is null or if the conversion fails * @return the value in the Map as a float, defaultValue if null map input */ public static float getFloatValue(final Map map, final K key, final float defaultValue) { final Float floatObject = getFloat(map, key); if (floatObject == null) { return defaultValue; } return floatObject.floatValue(); } /** * Gets a double from a Map in a null-safe manner, * using the default value if the conversion fails. *

* The double is obtained from the results of {@link #getNumber(Map,Object)}. * * @param the key type * @param map the map to use * @param key the key to look up * @param defaultValue return if the value is null or if the conversion fails * @return the value in the Map as a double, defaultValue if null map input */ public static double getDoubleValue(final Map map, final K key, final double defaultValue) { final Double doubleObject = getDouble(map, key); if (doubleObject == null) { return defaultValue; } return doubleObject.doubleValue(); } // Conversion methods //------------------------------------------------------------------------- /** * Gets a new Properties object initialised with the values from a Map. * A null input will return an empty properties object. *

* A Properties object may only store non-null keys and values, thus if * the provided map contains either a key or value which is {@code null}, * a {@link NullPointerException} will be thrown. * * @param the key type * @param the value type * @param map the map to convert to a Properties object * @return the properties object * @throws NullPointerException if a key or value in the provided map is {@code null} */ public static Properties toProperties(final Map map) { final Properties answer = new Properties(); if (map != null) { for (final Entry entry2 : map.entrySet()) { final Map.Entry entry = entry2; final Object key = entry.getKey(); final Object value = entry.getValue(); answer.put(key, value); } } return answer; } /** * Creates a new HashMap using data copied from a ResourceBundle. * * @param resourceBundle the resource bundle to convert, may not be null * @return the hashmap containing the data * @throws NullPointerException if the bundle is null */ public static Map toMap(final ResourceBundle resourceBundle) { final Enumeration enumeration = resourceBundle.getKeys(); final Map map = new HashMap<>(); while (enumeration.hasMoreElements()) { final String key = enumeration.nextElement(); final Object value = resourceBundle.getObject(key); map.put(key, value); } return map; } // Printing methods //------------------------------------------------------------------------- /** * Prints the given map with nice line breaks. *

* This method prints a nicely formatted String describing the Map. * Each map entry will be printed with key and value. * When the value is a Map, recursive behaviour occurs. *

* This method is NOT thread-safe in any special way. You must manually * synchronize on either this class or the stream as required. * * @param out the stream to print to, must not be null * @param label The label to be used, may be null. * If null, the label is not output. * It typically represents the name of the property in a bean or similar. * @param map The map to print, may be null. * If null, the text 'null' is output. * @throws NullPointerException if the stream is null */ public static void verbosePrint(final PrintStream out, final Object label, final Map map) { verbosePrintInternal(out, label, map, new ArrayDeque>(), false); } /** * Prints the given map with nice line breaks. *

* This method prints a nicely formatted String describing the Map. * Each map entry will be printed with key, value and value classname. * When the value is a Map, recursive behaviour occurs. *

* This method is NOT thread-safe in any special way. You must manually * synchronize on either this class or the stream as required. * * @param out the stream to print to, must not be null * @param label The label to be used, may be null. * If null, the label is not output. * It typically represents the name of the property in a bean or similar. * @param map The map to print, may be null. * If null, the text 'null' is output. * @throws NullPointerException if the stream is null */ public static void debugPrint(final PrintStream out, final Object label, final Map map) { verbosePrintInternal(out, label, map, new ArrayDeque>(), true); } // Implementation methods //------------------------------------------------------------------------- /** * Implementation providing functionality for {@link #debugPrint} and for * {@link #verbosePrint}. This prints the given map with nice line breaks. * If the debug flag is true, it additionally prints the type of the object * value. If the contents of a map include the map itself, then the text * (this Map) is printed out. If the contents include a * parent container of the map, the text (ancestor[i] Map) is * printed, where i actually indicates the number of levels which must be * traversed in the sequential list of ancestors (e.g. father, grandfather, * great-grandfather, etc). * * @param out the stream to print to * @param label the label to be used, may be null. * If null, the label is not output. * It typically represents the name of the property in a bean or similar. * @param map the map to print, may be null. * If null, the text 'null' is output * @param lineage a stack consisting of any maps in which the previous * argument is contained. This is checked to avoid infinite recursion when * printing the output * @param debug flag indicating whether type names should be output. * @throws NullPointerException if the stream is null */ private static void verbosePrintInternal(final PrintStream out, final Object label, final Map map, final Deque> lineage, final boolean debug) { printIndent(out, lineage.size()); if (map == null) { if (label != null) { out.print(label); out.print(" = "); } out.println("null"); return; } if (label != null) { out.print(label); out.println(" = "); } printIndent(out, lineage.size()); out.println("{"); lineage.addLast(map); for (final Map.Entry entry : map.entrySet()) { final Object childKey = entry.getKey(); final Object childValue = entry.getValue(); if (childValue instanceof Map && !lineage.contains(childValue)) { verbosePrintInternal( out, childKey == null ? "null" : childKey, (Map) childValue, lineage, debug); } else { printIndent(out, lineage.size()); out.print(childKey); out.print(" = "); final int lineageIndex = IterableUtils.indexOf(lineage, PredicateUtils.equalPredicate(childValue)); if (lineageIndex == -1) { out.print(childValue); } else if (lineage.size() - 1 == lineageIndex) { out.print("(this Map)"); } else { out.print( "(ancestor[" + (lineage.size() - 1 - lineageIndex - 1) + "] Map)"); } if (debug && childValue != null) { out.print(' '); out.println(childValue.getClass().getName()); } else { out.println(); } } } lineage.removeLast(); printIndent(out, lineage.size()); out.println(debug ? "} " + map.getClass().getName() : "}"); } /** * Writes indentation to the given stream. * * @param out the stream to indent */ private static void printIndent(final PrintStream out, final int indent) { for (int i = 0; i < indent; i++) { out.print(INDENT_STRING); } } // Misc //----------------------------------------------------------------------- /** * Inverts the supplied map returning a new HashMap such that the keys of * the input are swapped with the values. *

* This operation assumes that the inverse mapping is well defined. * If the input map had multiple entries with the same value mapped to * different keys, the returned map will map one of those keys to the * value, but the exact key which will be mapped is undefined. * * @param the key type * @param the value type * @param map the map to invert, may not be null * @return a new HashMap containing the inverted data * @throws NullPointerException if the map is null */ public static Map invertMap(final Map map) { final Map out = new HashMap<>(map.size()); for (final Entry entry : map.entrySet()) { out.put(entry.getValue(), entry.getKey()); } return out; } //----------------------------------------------------------------------- /** * Protects against adding null values to a map. *

* This method checks the value being added to the map, and if it is null * it is replaced by an empty string. *

* This could be useful if the map does not accept null values, or for * receiving data from a source that may provide null or empty string * which should be held in the same way in the map. *

* Keys are not validated. * Note that this method can be used to circumvent the map's * value type at runtime. * * @param the key type * @param map the map to add to, may not be null * @param key the key * @param value the value, null converted to "" * @throws NullPointerException if the map is null */ public static void safeAddToMap(final Map map, final K key, final Object value) throws NullPointerException { map.put(key, value == null ? "" : value); } //----------------------------------------------------------------------- /** * Puts all the keys and values from the specified array into the map. *

* This method is an alternative to the {@link java.util.Map#putAll(java.util.Map)} * method and constructors. It allows you to build a map from an object array * of various possible styles. *

* If the first entry in the object array implements {@link java.util.Map.Entry} * or {@link KeyValue} then the key and value are added from that object. * If the first entry in the object array is an object array itself, then * it is assumed that index 0 in the sub-array is the key and index 1 is the value. * Otherwise, the array is treated as keys and values in alternate indices. *

* For example, to create a color map: *

     * Map colorMap = MapUtils.putAll(new HashMap(), new String[][] {
     *     {"RED", "#FF0000"},
     *     {"GREEN", "#00FF00"},
     *     {"BLUE", "#0000FF"}
     * });
     * 
* or: *
     * Map colorMap = MapUtils.putAll(new HashMap(), new String[] {
     *     "RED", "#FF0000",
     *     "GREEN", "#00FF00",
     *     "BLUE", "#0000FF"
     * });
     * 
* or: *
     * Map colorMap = MapUtils.putAll(new HashMap(), new Map.Entry[] {
     *     new DefaultMapEntry("RED", "#FF0000"),
     *     new DefaultMapEntry("GREEN", "#00FF00"),
     *     new DefaultMapEntry("BLUE", "#0000FF")
     * });
     * 
* * @param the key type * @param the value type * @param map the map to populate, must not be null * @param array an array to populate from, null ignored * @return the input map * @throws NullPointerException if map is null * @throws IllegalArgumentException if sub-array or entry matching used and an entry is invalid * @throws ClassCastException if the array contents is mixed * @since 3.2 */ @SuppressWarnings("unchecked") // As per Javadoc throws CCE for invalid array contents public static Map putAll(final Map map, final Object[] array) { if (map == null) { throw new NullPointerException("The map must not be null"); } if (array == null || array.length == 0) { return map; } final Object obj = array[0]; if (obj instanceof Map.Entry) { for (final Object element : array) { // cast ok here, type is checked above final Map.Entry entry = (Map.Entry) element; map.put(entry.getKey(), entry.getValue()); } } else if (obj instanceof KeyValue) { for (final Object element : array) { // cast ok here, type is checked above final KeyValue keyval = (KeyValue) element; map.put(keyval.getKey(), keyval.getValue()); } } else if (obj instanceof Object[]) { for (int i = 0; i < array.length; i++) { final Object[] sub = (Object[]) array[i]; if (sub == null || sub.length < 2) { throw new IllegalArgumentException("Invalid array element: " + i); } // these casts can fail if array has incorrect types map.put((K) sub[0], (V) sub[1]); } } else { for (int i = 0; i < array.length - 1;) { // these casts can fail if array has incorrect types map.put((K) array[i++], (V) array[i++]); } } return map; } //----------------------------------------------------------------------- /** * Returns an immutable empty map if the argument is null, * or the argument itself otherwise. * * @param the key type * @param the value type * @param map the map, possibly null * @return an empty map if the argument is null */ public static Map emptyIfNull(final Map map) { return map == null ? Collections.emptyMap() : map; } /** * Null-safe check if the specified map is empty. *

* Null returns true. * * @param map the map to check, may be null * @return true if empty or null * @since 3.2 */ public static boolean isEmpty(final Map map) { return map == null || map.isEmpty(); } /** * Null-safe check if the specified map is not empty. *

* Null returns false. * * @param map the map to check, may be null * @return true if non-null and non-empty * @since 3.2 */ public static boolean isNotEmpty(final Map map) { return !MapUtils.isEmpty(map); } // Map decorators //----------------------------------------------------------------------- /** * Returns a synchronized map backed by the given map. *

* You must manually synchronize on the returned buffer's iterator to * avoid non-deterministic behavior: * *

     * Map m = MapUtils.synchronizedMap(myMap);
     * Set s = m.keySet();  // outside synchronized block
     * synchronized (m) {  // synchronized on MAP!
     *     Iterator i = s.iterator();
     *     while (i.hasNext()) {
     *         process (i.next());
     *     }
     * }
     * 
* * This method uses the implementation in {@link java.util.Collections Collections}. * * @param the key type * @param the value type * @param map the map to synchronize, must not be null * @return a synchronized map backed by the given map */ public static Map synchronizedMap(final Map map) { return Collections.synchronizedMap(map); } /** * Returns an unmodifiable map backed by the given map. *

* This method uses the implementation in the decorators subpackage. * * @param the key type * @param the value type * @param map the map to make unmodifiable, must not be null * @return an unmodifiable map backed by the given map * @throws NullPointerException if the map is null */ public static Map unmodifiableMap(final Map map) { return UnmodifiableMap.unmodifiableMap(map); } /** * Returns a predicated (validating) map backed by the given map. *

* Only objects that pass the tests in the given predicates can be added to the map. * Trying to add an invalid object results in an IllegalArgumentException. * Keys must pass the key predicate, values must pass the value predicate. * It is important not to use the original map after invoking this method, * as it is a backdoor for adding invalid objects. * * @param the key type * @param the value type * @param map the map to predicate, must not be null * @param keyPred the predicate for keys, null means no check * @param valuePred the predicate for values, null means no check * @return a predicated map backed by the given map * @throws NullPointerException if the Map is null */ public static IterableMap predicatedMap(final Map map, final Predicate keyPred, final Predicate valuePred) { return PredicatedMap.predicatedMap(map, keyPred, valuePred); } /** * Returns a transformed map backed by the given map. *

* This method returns a new map (decorating the specified map) that * will transform any new entries added to it. * Existing entries in the specified map will not be transformed. * If you want that behaviour, see {@link TransformedMap#transformedMap}. *

* Each object is passed through the transformers as it is added to the * Map. It is important not to use the original map after invoking this * method, as it is a backdoor for adding untransformed objects. *

* If there are any elements already in the map being decorated, they * are NOT transformed. * * @param the key type * @param the value type * @param map the map to transform, must not be null, typically empty * @param keyTransformer the transformer for the map keys, null means no transformation * @param valueTransformer the transformer for the map values, null means no transformation * @return a transformed map backed by the given map * @throws NullPointerException if the Map is null */ public static IterableMap transformedMap(final Map map, final Transformer keyTransformer, final Transformer valueTransformer) { return TransformedMap.transformingMap(map, keyTransformer, valueTransformer); } /** * Returns a fixed-sized map backed by the given map. * Elements may not be added or removed from the returned map, but * existing elements can be changed (for instance, via the * {@link Map#put(Object,Object)} method). * * @param the key type * @param the value type * @param map the map whose size to fix, must not be null * @return a fixed-size map backed by that map * @throws NullPointerException if the Map is null */ public static IterableMap fixedSizeMap(final Map map) { return FixedSizeMap.fixedSizeMap(map); } /** * Returns a "lazy" map whose values will be created on demand. *

* When the key passed to the returned map's {@link Map#get(Object)} * method is not present in the map, then the factory will be used * to create a new object and that object will become the value * associated with that key. *

* For instance: *

     * Factory factory = new Factory() {
     *     public Object create() {
     *         return new Date();
     *     }
     * }
     * Map lazyMap = MapUtils.lazyMap(new HashMap(), factory);
     * Object obj = lazyMap.get("test");
     * 
* * After the above code is executed, obj will contain * a new Date instance. Furthermore, that Date * instance is the value for the "test" key in the map. * * @param the key type * @param the value type * @param map the map to make lazy, must not be null * @param factory the factory for creating new objects, must not be null * @return a lazy map backed by the given map * @throws NullPointerException if the Map or Factory is null */ public static IterableMap lazyMap(final Map map, final Factory factory) { return LazyMap.lazyMap(map, factory); } /** * Returns a "lazy" map whose values will be created on demand. *

* When the key passed to the returned map's {@link Map#get(Object)} * method is not present in the map, then the factory will be used * to create a new object and that object will become the value * associated with that key. The factory is a {@link Transformer} * that will be passed the key which it must transform into the value. *

* For instance: *

     * Transformer factory = new Transformer() {
     *     public Object transform(Object mapKey) {
     *         return new File(mapKey);
     *     }
     * }
     * Map lazyMap = MapUtils.lazyMap(new HashMap(), factory);
     * Object obj = lazyMap.get("C:/dev");
     * 
* * After the above code is executed, obj will contain * a new File instance for the C drive dev directory. * Furthermore, that File instance is the value for the * "C:/dev" key in the map. *

* If a lazy map is wrapped by a synchronized map, the result is a simple * synchronized cache. When an object is not is the cache, the cache itself * calls back to the factory Transformer to populate itself, all within the * same synchronized block. * * @param the key type * @param the value type * @param map the map to make lazy, must not be null * @param transformerFactory the factory for creating new objects, must not be null * @return a lazy map backed by the given map * @throws NullPointerException if the Map or Transformer is null */ public static IterableMap lazyMap(final Map map, final Transformer transformerFactory) { return LazyMap.lazyMap(map, transformerFactory); } /** * Returns a map that maintains the order of keys that are added * backed by the given map. *

* If a key is added twice, the order is determined by the first add. * The order is observed through the keySet, values and entrySet. * * @param the key type * @param the value type * @param map the map to order, must not be null * @return an ordered map backed by the given map * @throws NullPointerException if the Map is null */ public static OrderedMap orderedMap(final Map map) { return ListOrderedMap.listOrderedMap(map); } /** * Creates a mult-value map backed by the given map which returns * collections of type ArrayList. * * @param the key type * @param the value type * @param map the map to decorate * @return a multi-value map backed by the given map which returns ArrayLists of values. * @see MultiValueMap * @since 3.2 * @deprecated since 4.1, use {@link MultiValuedMap} instead */ @Deprecated public static MultiValueMap multiValueMap(final Map> map) { return MultiValueMap.multiValueMap(map); } /** * Creates a multi-value map backed by the given map which returns * collections of the specified type. * * @param the key type * @param the value type * @param the collection class type * @param map the map to decorate * @param collectionClass the type of collections to return from the map * (must contain public no-arg constructor and extend Collection) * @return a multi-value map backed by the given map which returns collections of the specified type * @see MultiValueMap * @since 3.2 * @deprecated since 4.1, use {@link MultiValuedMap} instead */ @Deprecated public static > MultiValueMap multiValueMap(final Map map, final Class collectionClass) { return MultiValueMap.multiValueMap(map, collectionClass); } /** * Creates a multi-value map backed by the given map which returns * collections created by the specified collection factory. * * @param the key type * @param the value type * @param the collection class type * @param map the map to decorate * @param collectionFactory a factor which creates collection objects * @return a multi-value map backed by the given map which returns collections * created by the specified collection factory * @see MultiValueMap * @since 3.2 * @deprecated since 4.1, use {@link MultiValuedMap} instead */ @Deprecated public static > MultiValueMap multiValueMap(final Map map, final Factory collectionFactory) { return MultiValueMap.multiValueMap(map, collectionFactory); } // SortedMap decorators //----------------------------------------------------------------------- /** * Returns a synchronized sorted map backed by the given sorted map. *

* You must manually synchronize on the returned buffer's iterator to * avoid non-deterministic behavior: * *

     * Map m = MapUtils.synchronizedSortedMap(myMap);
     * Set s = m.keySet();  // outside synchronized block
     * synchronized (m) {  // synchronized on MAP!
     *     Iterator i = s.iterator();
     *     while (i.hasNext()) {
     *         process (i.next());
     *     }
     * }
     * 
* * This method uses the implementation in {@link java.util.Collections Collections}. * * @param the key type * @param the value type * @param map the map to synchronize, must not be null * @return a synchronized map backed by the given map * @throws NullPointerException if the map is null */ public static SortedMap synchronizedSortedMap(final SortedMap map) { return Collections.synchronizedSortedMap(map); } /** * Returns an unmodifiable sorted map backed by the given sorted map. *

* This method uses the implementation in the decorators subpackage. * * @param the key type * @param the value type * @param map the sorted map to make unmodifiable, must not be null * @return an unmodifiable map backed by the given map * @throws NullPointerException if the map is null */ public static SortedMap unmodifiableSortedMap(final SortedMap map) { return UnmodifiableSortedMap.unmodifiableSortedMap(map); } /** * Returns a predicated (validating) sorted map backed by the given map. *

* Only objects that pass the tests in the given predicates can be added to the map. * Trying to add an invalid object results in an IllegalArgumentException. * Keys must pass the key predicate, values must pass the value predicate. * It is important not to use the original map after invoking this method, * as it is a backdoor for adding invalid objects. * * @param the key type * @param the value type * @param map the map to predicate, must not be null * @param keyPred the predicate for keys, null means no check * @param valuePred the predicate for values, null means no check * @return a predicated map backed by the given map * @throws NullPointerException if the SortedMap is null */ public static SortedMap predicatedSortedMap(final SortedMap map, final Predicate keyPred, final Predicate valuePred) { return PredicatedSortedMap.predicatedSortedMap(map, keyPred, valuePred); } /** * Returns a transformed sorted map backed by the given map. *

* This method returns a new sorted map (decorating the specified map) that * will transform any new entries added to it. * Existing entries in the specified map will not be transformed. * If you want that behaviour, see {@link TransformedSortedMap#transformedSortedMap}. *

* Each object is passed through the transformers as it is added to the * Map. It is important not to use the original map after invoking this * method, as it is a backdoor for adding untransformed objects. *

* If there are any elements already in the map being decorated, they * are NOT transformed. * * @param the key type * @param the value type * @param map the map to transform, must not be null, typically empty * @param keyTransformer the transformer for the map keys, null means no transformation * @param valueTransformer the transformer for the map values, null means no transformation * @return a transformed map backed by the given map * @throws NullPointerException if the SortedMap is null */ public static SortedMap transformedSortedMap(final SortedMap map, final Transformer keyTransformer, final Transformer valueTransformer) { return TransformedSortedMap.transformingSortedMap(map, keyTransformer, valueTransformer); } /** * Returns a fixed-sized sorted map backed by the given sorted map. * Elements may not be added or removed from the returned map, but * existing elements can be changed (for instance, via the * {@link Map#put(Object,Object)} method). * * @param the key type * @param the value type * @param map the map whose size to fix, must not be null * @return a fixed-size map backed by that map * @throws NullPointerException if the SortedMap is null */ public static SortedMap fixedSizeSortedMap(final SortedMap map) { return FixedSizeSortedMap.fixedSizeSortedMap(map); } /** * Returns a "lazy" sorted map whose values will be created on demand. *

* When the key passed to the returned map's {@link Map#get(Object)} * method is not present in the map, then the factory will be used * to create a new object and that object will become the value * associated with that key. *

* For instance: * *

     * Factory factory = new Factory() {
     *     public Object create() {
     *         return new Date();
     *     }
     * }
     * SortedMap lazy = MapUtils.lazySortedMap(new TreeMap(), factory);
     * Object obj = lazy.get("test");
     * 
* * After the above code is executed, obj will contain * a new Date instance. Furthermore, that Date * instance is the value for the "test" key. * * @param the key type * @param the value type * @param map the map to make lazy, must not be null * @param factory the factory for creating new objects, must not be null * @return a lazy map backed by the given map * @throws NullPointerException if the SortedMap or Factory is null */ public static SortedMap lazySortedMap(final SortedMap map, final Factory factory) { return LazySortedMap.lazySortedMap(map, factory); } /** * Returns a "lazy" sorted map whose values will be created on demand. *

* When the key passed to the returned map's {@link Map#get(Object)} * method is not present in the map, then the factory will be used * to create a new object and that object will become the value * associated with that key. The factory is a {@link Transformer} * that will be passed the key which it must transform into the value. *

* For instance: *

     * Transformer factory = new Transformer() {
     *     public Object transform(Object mapKey) {
     *         return new File(mapKey);
     *     }
     * }
     * SortedMap lazy = MapUtils.lazySortedMap(new TreeMap(), factory);
     * Object obj = lazy.get("C:/dev");
     * 
* * After the above code is executed, obj will contain * a new File instance for the C drive dev directory. * Furthermore, that File instance is the value for the * "C:/dev" key in the map. *

* If a lazy map is wrapped by a synchronized map, the result is a simple * synchronized cache. When an object is not is the cache, the cache itself * calls back to the factory Transformer to populate itself, all within the * same synchronized block. * * @param the key type * @param the value type * @param map the map to make lazy, must not be null * @param transformerFactory the factory for creating new objects, must not be null * @return a lazy map backed by the given map * @throws NullPointerException if the Map or Transformer is null */ public static SortedMap lazySortedMap(final SortedMap map, final Transformer transformerFactory) { return LazySortedMap.lazySortedMap(map, transformerFactory); } /** * Populates a Map using the supplied Transformer to transform the elements * into keys, using the unaltered element as the value in the Map. * * @param the key type * @param the value type * @param map the Map to populate. * @param elements the Iterable containing the input values for the map. * @param keyTransformer the Transformer used to transform the element into a key value * @throws NullPointerException if the map, elements or transformer are null */ public static void populateMap(final Map map, final Iterable elements, final Transformer keyTransformer) { populateMap(map, elements, keyTransformer, TransformerUtils.nopTransformer()); } /** * Populates a Map using the supplied Transformers to transform the elements * into keys and values. * * @param the key type * @param the value type * @param the type of object contained in the {@link Iterable} * @param map the Map to populate. * @param elements the Iterable containing the input values for the map. * @param keyTransformer the Transformer used to transform the element into a key value * @param valueTransformer the Transformer used to transform the element into a value * @throws NullPointerException if the map, elements or transformers are null */ public static void populateMap(final Map map, final Iterable elements, final Transformer keyTransformer, final Transformer valueTransformer) { final Iterator iter = elements.iterator(); while (iter.hasNext()) { final E temp = iter.next(); map.put(keyTransformer.transform(temp), valueTransformer.transform(temp)); } } /** * Populates a MultiMap using the supplied Transformer to transform the elements * into keys, using the unaltered element as the value in the MultiMap. * * @param the key type * @param the value type * @param map the MultiMap to populate. * @param elements the Iterable to use as input values for the map. * @param keyTransformer the Transformer used to transform the element into a key value * @throws NullPointerException if the map, elements or transformer are null */ public static void populateMap(final MultiMap map, final Iterable elements, final Transformer keyTransformer) { populateMap(map, elements, keyTransformer, TransformerUtils.nopTransformer()); } /** * Populates a MultiMap using the supplied Transformers to transform the elements * into keys and values. * * @param the key type * @param the value type * @param the type of object contained in the {@link Iterable} * @param map the MultiMap to populate. * @param elements the Iterable containing the input values for the map. * @param keyTransformer the Transformer used to transform the element into a key value * @param valueTransformer the Transformer used to transform the element into a value * @throws NullPointerException if the map, collection or transformers are null */ public static void populateMap(final MultiMap map, final Iterable elements, final Transformer keyTransformer, final Transformer valueTransformer) { final Iterator iter = elements.iterator(); while (iter.hasNext()) { final E temp = iter.next(); map.put(keyTransformer.transform(temp), valueTransformer.transform(temp)); } } /** * Get the specified {@link Map} as an {@link IterableMap}. * * @param the key type * @param the value type * @param map to wrap if necessary. * @return IterableMap<K, V> * @throws NullPointerException if map is null * @since 4.0 */ public static IterableMap iterableMap(final Map map) { if (map == null) { throw new NullPointerException("Map must not be null"); } return map instanceof IterableMap ? (IterableMap) map : new AbstractMapDecorator(map) {}; } /** * Get the specified {@link SortedMap} as an {@link IterableSortedMap}. * * @param the key type * @param the value type * @param sortedMap to wrap if necessary * @return {@link IterableSortedMap}<K, V> * @throws NullPointerException if sortedMap is null * @since 4.0 */ public static IterableSortedMap iterableSortedMap(final SortedMap sortedMap) { if (sortedMap == null) { throw new NullPointerException("Map must not be null"); } return sortedMap instanceof IterableSortedMap ? (IterableSortedMap) sortedMap : new AbstractSortedMapDecorator(sortedMap) {}; } /** * Gets the given map size or 0 if the map is null * @param map a Map or null * @return the given map size or 0 if the map is null */ public static int size(final Map map) { return map == null ? 0 : map.size(); } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy