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.Map;
  16
  17 import org.eclipse.jdt.annotation.NonNull;
  18 import org.eclipse.jdt.annotation.Nullable;
  19
  20 /**
  21  * Utility methods to handle {@link org.eclipse.jdt.annotation.NonNull}
  22  * annotations.
  23  *
  24  * @author Alexandre Montplaisir
  25  */
  26 public final class NonNullUtils {
  27
  28     private NonNullUtils() {
  29     }
  30
  31     /**
  32      * Returns a non-null {@link String} for a potentially null object. This
  33      * method calls {@link Object#toString()} if the object is not null, or
  34      * returns an empty string otherwise.
  35      *
  36      * @param obj
  37      *            A {@link Nullable} object that we want converted to a string
  38      * @return The non-null string
  39      */
  40     public static String nullToEmptyString(@Nullable Object obj) {
  41         if (obj == null) {
  42             return ""; //$NON-NLS-1$
  43         }
  44         String str = obj.toString();
  45         return (str == null ? "" : str); //$NON-NLS-1$
  46     }
  47
  48     /**
  49      * Checks equality with two nullable objects
  50      *
  51      * @param o1
  52      *            the first object to compare
  53      * @param o2
  54      *            the second object to compare
  55      * @return true if o1.equals(o2) or o1 == o2
  56      * @since 1.0
  57      */
  58     public static boolean equalsNullable(final @Nullable Object o1, final @Nullable Object o2) {
  59         if (o1 == o2) {
  60             return true;
  61         }
  62         if (o1 == null) {
  63             return false;
  64         }
  65         return o1.equals(o2);
  66     }
  67
  68     // ------------------------------------------------------------------------
  69     // checkNotNull() methods, to convert @Nullable references to @NonNull ones
  70     // ------------------------------------------------------------------------
  71
  72     /**
  73      * Convert a non-annotated object reference to a {@link NonNull} one.
  74      *
  75      * If the reference is actually null, a {@link NullPointerException} is
  76      * thrown. This is usually more desirable than letting an unwanted null
  77      * reference go through and fail much later.
  78      *
  79      * @param obj
  80      *            The object that is supposed to be non-null
  81      * @return A {@link NonNull} reference to the same object
  82      * @throws NullPointerException
  83      *             If the reference was actually null
  84      */
  85     public static <T> @NonNull T checkNotNull(@Nullable T obj) {
  86         if (obj == null) {
  87             throw new NullPointerException();
  88         }
  89         return obj;
  90     }
  91
  92     /**
  93      * Convert a non-annotated [] array reference to a @NonNull one.
  94      *
  95      * Note that this method does not check the array contents itself, which can
  96      * still contain null elements.
  97      *
  98      * @param array
  99      *            The array whose reference should not be null
 100      * @return A {@link NonNull} reference to the array
 101      * @throws NullPointerException
 102      *             If the reference was actually null
 103      * @since 2.0
 104      */
 105     public static <@Nullable T> T[] checkNotNull(T @Nullable [] array) {
 106         if (array == null) {
 107             throw new NullPointerException();
 108         }
 109         return array;
 110     }
 111
 112     /**
 113      * Convert a non-annotated {@link Iterable} to a NonNull one.
 114      *
 115      * Note that, unlike {{@link #checkNotNull(Object)}}, this method does not
 116      * check the contents itself, which can still contain null elements.
 117      *
 118      * @param container
 119      *            The iterable whose reference should not be null
 120      * @return A {@link NonNull} reference to the Iterable. The original class
 121      *         type is preserved.
 122      * @throws NullPointerException
 123      *             If the reference was actually null
 124      * @since 2.0
 125      */
 126     public static <@Nullable T, C extends Iterable<T>> C checkNotNull(@Nullable C container) {
 127         if (container == null) {
 128             throw new NullPointerException();
 129         }
 130         return container;
 131     }
 132
 133     /**
 134      * Convert a non-annotated {@link Map} to a NonNull one.
 135      *
 136      * Note that, unlike {{@link #checkNotNull(Object)}}, this method does not
 137      * check the keys or values themselves, which can still contain null
 138      * elements.
 139      *
 140      * @param map
 141      *            The map whose reference should not be null
 142      * @return A {@link NonNull} reference to the Map
 143      * @throws NullPointerException
 144      *             If the reference was actually null
 145      * @since 2.0
 146      */
 147     public static <@Nullable K, @Nullable V, M extends Map<K, V>> M checkNotNull(@Nullable M map) {
 148         if (map == null) {
 149             throw new NullPointerException();
 150         }
 151         return map;
 152     }
 153
 154
 155 }