common/org.eclipse.tracecompass.common.core/src/org/eclipse/tracecompass/common/core/NonNullUtils.java

   1 /*******************************************************************************
   2  * Copyright (c) 2014, 2015 Ericsson
   3  *
   4  * All rights reserved. This program and the accompanying materials are
   5  * made available under the terms of the Eclipse Public License v1.0 which
   6  * accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *   Alexandre Montplaisir - Initial API and implementation
  11  *******************************************************************************/
  12
  13 package org.eclipse.tracecompass.common.core;
  14
  15 import java.util.Arrays;
  16 import java.util.Objects;
  17 import java.util.stream.Stream;
  18
  19 import org.eclipse.jdt.annotation.NonNull;
  20 import org.eclipse.jdt.annotation.Nullable;
  21
  22 /**
  23  * Utility methods to handle {@link org.eclipse.jdt.annotation.NonNull}
  24  * annotations.
  25  *
  26  * @author Alexandre Montplaisir
  27  */
  28 public final class NonNullUtils {
  29
  30     private NonNullUtils() {
  31     }
  32
  33     /**
  34      * Returns a non-null {@link String} for a potentially null object. This
  35      * method calls {@link Object#toString()} if the object is not null, or
  36      * returns an empty string otherwise.
  37      *
  38      * @param obj
  39      *            A {@link Nullable} object that we want converted to a string
  40      * @return The non-null string
  41      */
  42     public static String nullToEmptyString(@Nullable Object obj) {
  43         if (obj == null) {
  44             return ""; //$NON-NLS-1$
  45         }
  46         String str = obj.toString();
  47         return (str == null ? "" : str); //$NON-NLS-1$
  48     }
  49
  50     /**
  51      * Checks equality with two nullable objects
  52      *
  53      * @param o1
  54      *            the first object to compare
  55      * @param o2
  56      *            the second object to compare
  57      * @return true if o1.equals(o2) or o1 == o2
  58      * @since 1.0
  59      * @deprecated use {@link Objects#equals(Object)} instead
  60      */
  61     @Deprecated
  62     public static boolean equalsNullable(final @Nullable Object o1, final @Nullable Object o2) {
  63         if (o1 == o2) {
  64             return true;
  65         }
  66         if (o1 == null) {
  67             return false;
  68         }
  69         return o1.equals(o2);
  70     }
  71
  72     // ------------------------------------------------------------------------
  73     // checkNotNull() methods, to convert @Nullable references to @NonNull ones
  74     // ------------------------------------------------------------------------
  75
  76     /**
  77      * Convert a non-annotated object reference to a {@link NonNull} one.
  78      *
  79      * If the reference is actually null, a {@link NullPointerException} is
  80      * thrown. This is usually more desirable than letting an unwanted null
  81      * reference go through and fail much later.
  82      *
  83      * @param obj
  84      *            The object that is supposed to be non-null
  85      * @return A {@link NonNull} reference to the same object
  86      * @throws NullPointerException
  87      *             If the reference was actually null
  88      */
  89     public static <T> @NonNull T checkNotNull(@Nullable T obj) {
  90         if (obj == null) {
  91             throw new NullPointerException();
  92         }
  93         return obj;
  94     }
  95
  96     /**
  97      * Ensures a {@link Stream} does not contain any null values.
  98      *
  99      * This also "upcasts" the reference from a Stream<@Nullable T> to a
 100      * Stream<@NonNull T>.
 101      *
 102      * @param stream
 103      *            The stream to check for
 104      * @return A stream with the same elements
 105      * @throws NullPointerException
 106      *             If the stream itself or any of its values are null
 107      * @since 2.0
 108      */
 109     public static <T> Stream<@NonNull T> checkNotNullContents(@Nullable Stream<T> stream) {
 110         if (stream == null) {
 111             throw new NullPointerException();
 112         }
 113         return checkNotNull(stream.<@NonNull T> map(t -> checkNotNull(t)));
 114     }
 115
 116     /**
 117      * Ensures an array does not contain any null elements.
 118      *
 119      * @param array
 120      *            The array to check
 121      * @return The same array, now with guaranteed @NonNull elements
 122      * @throws NullPointerException
 123      *             If the array reference or any contained element was null
 124      * @since 2.0
 125      */
 126     public static <T> @NonNull T[] checkNotNullContents(T @Nullable [] array) {
 127         if (array == null) {
 128             throw new NullPointerException();
 129         }
 130         Arrays.stream(array).forEach(elem -> checkNotNull(elem));
 131         @SuppressWarnings("null")
 132         @NonNull T[] ret = (@NonNull T[]) array;
 133         return ret;
 134     }
 135 }