001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.core.util;
007
008import java.util.Objects;
009import java.util.stream.Stream;
010
011import edu.umd.cs.findbugs.annotations.NonNull;
012import edu.umd.cs.findbugs.annotations.Nullable;
013import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
014
015/**
016 * A collection of utilities for checking and managing Java objects.
017 */
018public final class ObjectUtils {
019  private ObjectUtils() {
020    // disable construction
021  }
022
023  /**
024   * Assert that the provided object is not {@code null}.
025   * <p>
026   * This method sets the expectation that the provided object is not {@code null}
027   * in cases where a non-null value is required.
028   *
029   * @param <T>
030   *          the object type
031   * @param obj
032   *          the object
033   * @return the object
034   */
035  @NonNull
036  public static <T> T notNull(@Nullable T obj) {
037    assert obj != null;
038    return obj;
039  }
040
041  /**
042   * Require a non-null value.
043   *
044   * @param <T>
045   *          the type of the reference
046   * @param obj
047   *          the object reference to check for nullity
048   * @return {@code obj} if not {@code null}
049   * @throws NullPointerException
050   *           if {@code obj} is {@code null}
051   */
052  @NonNull
053  @SuppressFBWarnings("NP_PARAMETER_MUST_BE_NONNULL_BUT_MARKED_AS_NULLABLE")
054  public static <T> T requireNonNull(@Nullable T obj) {
055    if (obj == null) {
056      throw new NullPointerException(); // NOPMD
057    }
058    return obj;
059  }
060
061  /**
062   * Require a non-null value.
063   *
064   * @param <T>
065   *          the type of the reference
066   * @param obj
067   *          the object reference to check for nullity
068   * @param message
069   *          detail message to be used in the event that a {@code
070   *                NullPointerException} is thrown
071   * @return {@code obj} if not {@code null}
072   * @throws NullPointerException
073   *           if {@code obj} is {@code null}
074   */
075  @NonNull
076  @SuppressFBWarnings("NP_PARAMETER_MUST_BE_NONNULL_BUT_MARKED_AS_NULLABLE")
077  public static <T> T requireNonNull(@Nullable T obj, @NonNull String message) {
078    if (obj == null) {
079      throw new NullPointerException(message); // NOPMD
080    }
081    return obj;
082  }
083
084  /**
085   * A filter used to remove null items from a stream.
086   *
087   * @param <T>
088   *          the item type
089   * @param item
090   *          the item to filter
091   * @return the item as a steam or an empty stream if the item is {@code null}
092   */
093  @SuppressWarnings("null")
094  @NonNull
095  public static <T> Stream<T> filterNull(T item) {
096    return Objects.nonNull(item) ? Stream.of(item) : Stream.empty();
097  }
098
099  /**
100   * Cast the provided object as the requested return type.
101   *
102   * @param <T>
103   *          the Java type to cast the object to
104   * @param obj
105   *          the object to cast
106   * @return the object cast to the requested type
107   * @throws ClassCastException
108   *           if the object cannot be cast to the requested type
109   */
110  @SuppressWarnings("unchecked")
111  @NonNull
112  public static <T> T asType(@NonNull Object obj) {
113    return (T) obj;
114  }
115
116  /**
117   * Cast the provided object as the requested return type.
118   * <p>
119   * If the object is {@code null}, the returned value will be {@code null}.
120   *
121   * @param <T>
122   *          the Java type to cast the object to
123   * @param obj
124   *          the object to cast, which may be {@code null}
125   * @return the object cast to the requested type, or {@code null} if the
126   *         provided object is {@code null}
127   * @throws ClassCastException
128   *           if the object cannot be cast to the requested type
129   */
130  @SuppressWarnings("unchecked")
131  @Nullable
132  public static <T> T asNullableType(@Nullable Object obj) {
133    return (T) obj;
134  }
135}