src/main/java/de/xn__ho_hia/null_analysis/Nullsafe.java

   1 /*
   2  * This file is part of null-analysis. It is subject to the license terms in the LICENSE file found in the top-level
   3  * directory of this distribution and at http://creativecommons.org/publicdomain/zero/1.0/. No part of null-analysis,
   4  * including this file, may be copied, modified, propagated, or distributed except according to the terms contained
   5  * in the LICENSE file.
   6  */
   7 package de.xn__ho_hia.null_analysis;
   8
   9 import java.util.Collection;
  10 import java.util.Collections;
  11 import java.util.List;
  12 import java.util.Map;
  13 import java.util.Set;
  14 import java.util.stream.Stream;
  15
  16 import org.eclipse.jdt.annotation.NonNull;
  17 import org.eclipse.jdt.annotation.Nullable;
  18
  19 /**
  20  * Utility classes which helps working with legacy (nullable) APIs.
  21  */
  22 public final class Nullsafe {
  23
  24     private Nullsafe() {
  25         // utility class
  26     }
  27
  28     /**
  29      * Converts a {@link Nullable} reference into a {@link NonNull} reference. Performs a strict <code>null</code> check
  30      * that fails in case a <code>null</code> reference is given.
  31      *
  32      * @param <TYPE>
  33      *            The type of the reference
  34      * @param reference
  35      *            A possible <code>null</code> reference.
  36      * @return Either the reference itself, or an {@link NullPointerException}, in case the reference was
  37      *         <code>null</code>.
  38      */
  39     public static <TYPE> @NonNull TYPE nonNull(@Nullable final TYPE reference) {
  40         return nonNull(reference, "Got unexpected NULL reference"); //$NON-NLS-1$
  41     }
  42
  43     /**
  44      * Converts a {@link Nullable} reference into a {@link NonNull} reference. Performs a strict <code>null</code> check
  45      * that fails in case a <code>null</code> reference is given.
  46      *
  47      * @param <T>
  48      *            The type of the reference
  49      * @param reference
  50      *            A possible <code>null</code> reference.
  51      * @param message
  52      *            The exception message to throw.
  53      * @return Either the reference itself, or an {@link NullPointerException}, in case the reference was
  54      *         <code>null</code>.
  55      */
  56     public static <T> @NonNull T nonNull(@Nullable final T reference, final String message) {
  57         if (reference != null) {
  58             return reference;
  59         }
  60
  61         throw new IllegalArgumentException(message);
  62     }
  63
  64     /**
  65      * Safely creates a {@link Stream stream} of a nullable {@link Collection collection}. Falls back to an empty stream
  66      * in case the collection is <code>null</code>.
  67      *
  68      * @param <TYPE>
  69      *            The collection type
  70      * @param collection
  71      *            A collection or <code>null</code>
  72      * @return A stream of the given collection or empty stream
  73      */
  74     public static <TYPE> @NonNull Stream<TYPE> safelyStream(@Nullable final Collection<TYPE> collection) {
  75         return collection != null ? nonNull(collection.stream()) : nonNull(Stream.<TYPE> empty());
  76     }
  77
  78     /**
  79      * Ensures that callers of this method can always work with a {@link NonNull} {@link List list}. Falls back to an
  80      * empty list in case the given list is <code>null</code>.
  81      *
  82      * @param <TYPE>
  83      *            The list type
  84      * @param list
  85      *            A list or <code>null</code>
  86      * @return The given list or an empty list
  87      */
  88     public static <TYPE> @NonNull List<TYPE> ensureList(@Nullable final List<TYPE> list) {
  89         return list != null ? list : nonNull(Collections.<TYPE> emptyList());
  90     }
  91
  92     /**
  93      * Ensures that callers of this method can always work with a {@link NonNull} {@link Set set}. Falls back to an
  94      * empty set in case the given set is <code>null</code>.
  95      *
  96      * @param <TYPE>
  97      *            The set type
  98      * @param set
  99      *            A {@link Set} or <code>null</code>
 100      * @return The given set or an empty set
 101      */
 102     public static <TYPE> @NonNull Set<TYPE> ensureSet(@Nullable final Set<TYPE> set) {
 103         return set != null ? set : nonNull(Collections.<TYPE> emptySet());
 104     }
 105
 106     /**
 107      * Ensures that callers of this method can always work with a {@link NonNull} {@link Map map}. Falls back to an
 108      * empty map in case the given map is <code>null</code>.
 109      *
 110      * @param <KEY>
 111      *            The map key type
 112      * @param <VALUE>
 113      *            The map value type
 114      * @param map
 115      *            A {@link Map} or <code>null</code>
 116      * @return The given map or an empty map
 117      */
 118     public static <KEY, VALUE> @NonNull Map<KEY, VALUE> ensureMap(@Nullable final Map<KEY, VALUE> map) {
 119         return map != null ? map : nonNull(Collections.<KEY, VALUE> emptyMap());
 120     }
 121
 122     /**
 123      * Safely checks whether a given {@link Collection collection} is <code>null</code> or empty.
 124      *
 125      * @param collection
 126      *            A collection or <code>null</code>
 127      * @return <code>true</code> if the collection is null or empty, otherwise <code>false</code>.
 128      */
 129     public static boolean isNullOrEmpty(@Nullable final Collection<?> collection) {
 130         return collection == null || collection.isEmpty();
 131     }
 132
 133     /**
 134      * Safely checks whether a given {@link Map map} is <code>null</code> or empty.
 135      *
 136      * @param map
 137      *            A map or <code>null</code>
 138      * @return <code>true</code> if the map is null or empty, otherwise <code>false</code>.
 139      */
 140     public static boolean isNullOrEmpty(@Nullable final Map<?, ?> map) {
 141         return map == null || map.isEmpty();
 142     }
 143
 144     /**
 145      * Safely checks whether a given {@link String string} is <code>null</code> or empty.
 146      *
 147      * @param string
 148      *            A String or <code>null</code>
 149      * @return <code>true</code> if the string is null or empty, otherwise <code>false</code>.
 150      */
 151     public static boolean isNullOrEmpty(@Nullable final String string) {
 152         return string == null || string.isEmpty();
 153     }
 154
 155 }