From: Tuukka Lehtonen <tuukka.lehtonen@semantum.fi>
Date: Fri, 25 Nov 2016 10:03:27 +0000 (+0200)
Subject: Introduce utility class org.simantics.db.function.DbOptional<T>.
X-Git-Tag: v1.25.0~29^2
X-Git-Url: https://gerrit.simantics.org/r/gitweb?p=simantics%2Fplatform.git;a=commitdiff_plain;h=fbeeb3e2a52430fa90563d2d033008cc0bd0d754

Introduce utility class org.simantics.db.function.DbOptional<T>.

The class is a direct copy of java.util.Optional<T> but it uses
DbConsumer, DbFunction, DbPredicate and DbSupplier instead of the
standard Java 1.8 functional interfaces to allow the DbOptional methods
to throw DatabaseExceptions for cleaner database code in certain
situations.

The rationale behind this class is much the same as with the standard
optional. See e.g.
http://www.oracle.com/technetwork/articles/java/java8-optional-2175753.html.

refs #6829

Change-Id: Ibf62a56eb227264cbfac359aca99d87570b68a47
---

diff --git a/bundles/org.simantics.db/src/org/simantics/db/function/DbOptional.java b/bundles/org.simantics.db/src/org/simantics/db/function/DbOptional.java
new file mode 100644
index 000000000..a15cb110e
--- /dev/null
+++ b/bundles/org.simantics.db/src/org/simantics/db/function/DbOptional.java
@@ -0,0 +1,333 @@
+package org.simantics.db.function;
+
+import java.util.NoSuchElementException;
+import java.util.Objects;
+
+import org.simantics.db.exception.DatabaseException;
+
+/**
+ * A container object which may or may not contain a non-null value. If a value
+ * is present, {@code isPresent()} will return {@code true} and {@code get()}
+ * will return the value.
+ *
+ * <p>
+ * Additional methods that depend on the presence or absence of a contained
+ * value are provided, such as {@link #orElse(java.lang.Object) orElse()}
+ * (return a default value if value not present) and
+ * {@link #ifPresent(org.simantics.db.function.DbConsumer) ifPresent()} (execute
+ * a block of code if the value is present).
+ *
+ * <p>
+ * This is a value-based class; use of identity-sensitive operations (including
+ * reference equality ({@code ==}), identity hash code, or synchronization) on
+ * instances of {@code DbOptional} may have unpredictable results and should be
+ * avoided.
+ *
+ * @since 1.25
+ */
+public final class DbOptional<T> {
+    /**
+     * Common instance for {@code empty()}.
+     */
+    private static final DbOptional<?> EMPTY = new DbOptional<>();
+
+    /**
+     * If non-null, the value; if null, indicates no value is present
+     */
+    private final T value;
+
+    /**
+     * Constructs an empty instance.
+     *
+     * @implNote Generally only one empty instance, {@link Optional#EMPTY},
+     * should exist per VM.
+     */
+    private DbOptional() {
+        this.value = null;
+    }
+
+    /**
+     * Returns an empty {@code Optional} instance.  No value is present for this
+     * Optional.
+     *
+     * @apiNote Though it may be tempting to do so, avoid testing if an object
+     * is empty by comparing with {@code ==} against instances returned by
+     * {@code Option.empty()}. There is no guarantee that it is a singleton.
+     * Instead, use {@link #isPresent()}.
+     *
+     * @param <T> Type of the non-existent value
+     * @return an empty {@code Optional}
+     */
+    public static<T> DbOptional<T> empty() {
+        @SuppressWarnings("unchecked")
+        DbOptional<T> t = (DbOptional<T>) EMPTY;
+        return t;
+    }
+
+    /**
+     * Constructs an instance with the value present.
+     *
+     * @param value the non-null value to be present
+     * @throws NullPointerException if value is null
+     */
+    private DbOptional(T value) {
+        this.value = Objects.requireNonNull(value);
+    }
+
+    /**
+     * Returns an {@code Optional} with the specified present non-null value.
+     *
+     * @param <T> the class of the value
+     * @param value the value to be present, which must be non-null
+     * @return an {@code Optional} with the value present
+     * @throws NullPointerException if value is null
+     */
+    public static <T> DbOptional<T> of(T value) {
+        return new DbOptional<>(value);
+    }
+
+    /**
+     * Returns an {@code Optional} describing the specified value, if non-null,
+     * otherwise returns an empty {@code Optional}.
+     *
+     * @param <T> the class of the value
+     * @param value the possibly-null value to describe
+     * @return an {@code Optional} with a present value if the specified value
+     * is non-null, otherwise an empty {@code Optional}
+     */
+    public static <T> DbOptional<T> ofNullable(T value) {
+        return value == null ? empty() : of(value);
+    }
+
+    /**
+     * If a value is present in this {@code Optional}, returns the value,
+     * otherwise throws {@code NoSuchElementException}.
+     *
+     * @return the non-null value held by this {@code Optional}
+     * @throws NoSuchElementException if there is no value present
+     *
+     * @see Optional#isPresent()
+     */
+    public T get() {
+        if (value == null) {
+            throw new NoSuchElementException("No value present");
+        }
+        return value;
+    }
+
+    /**
+     * Return {@code true} if there is a value present, otherwise {@code false}.
+     *
+     * @return {@code true} if there is a value present, otherwise {@code false}
+     */
+    public boolean isPresent() {
+        return value != null;
+    }
+
+    /**
+     * If a value is present, invoke the specified consumer with the value,
+     * otherwise do nothing.
+     *
+     * @param consumer block to be executed if a value is present
+     * @throws DatabaseException 
+     * @throws NullPointerException if value is present and {@code consumer} is
+     * null
+     */
+    public void ifPresent(DbConsumer<? super T> consumer) throws DatabaseException {
+        if (value != null)
+            consumer.accept(value);
+    }
+
+    /**
+     * If a value is present, and the value matches the given predicate,
+     * return an {@code Optional} describing the value, otherwise return an
+     * empty {@code Optional}.
+     *
+     * @param predicate a predicate to apply to the value, if present
+     * @return an {@code Optional} describing the value of this {@code Optional}
+     * if a value is present and the value matches the given predicate,
+     * otherwise an empty {@code Optional}
+     * @throws DatabaseException 
+     * @throws NullPointerException if the predicate is null
+     */
+    public DbOptional<T> filter(DbPredicate<? super T> predicate) throws DatabaseException {
+        Objects.requireNonNull(predicate);
+        if (!isPresent())
+            return this;
+        else
+            return predicate.test(value) ? this : empty();
+    }
+
+    /**
+     * If a value is present, apply the provided mapping function to it,
+     * and if the result is non-null, return an {@code Optional} describing the
+     * result.  Otherwise return an empty {@code Optional}.
+     *
+     * @apiNote This method supports post-processing on optional values, without
+     * the need to explicitly check for a return status.  For example, the
+     * following code traverses a stream of file names, selects one that has
+     * not yet been processed, and then opens that file, returning an
+     * {@code Optional<FileInputStream>}:
+     *
+     * <pre>{@code
+     *     Optional<FileInputStream> fis =
+     *         names.stream().filter(name -> !isProcessedYet(name))
+     *                       .findFirst()
+     *                       .map(name -> new FileInputStream(name));
+     * }</pre>
+     *
+     * Here, {@code findFirst} returns an {@code Optional<String>}, and then
+     * {@code map} returns an {@code Optional<FileInputStream>} for the desired
+     * file if one exists.
+     *
+     * @param <U> The type of the result of the mapping function
+     * @param mapper a mapping function to apply to the value, if present
+     * @return an {@code Optional} describing the result of applying a mapping
+     * function to the value of this {@code Optional}, if a value is present,
+     * otherwise an empty {@code Optional}
+     * @throws DatabaseException 
+     * @throws NullPointerException if the mapping function is null
+     */
+    public<U> DbOptional<U> map(DbFunction<? super T, ? extends U> mapper) throws DatabaseException {
+        Objects.requireNonNull(mapper);
+        if (!isPresent())
+            return empty();
+        else {
+            return DbOptional.ofNullable(mapper.apply(value));
+        }
+    }
+
+    /**
+     * If a value is present, apply the provided {@code Optional}-bearing
+     * mapping function to it, return that result, otherwise return an empty
+     * {@code Optional}.  This method is similar to {@link #map(Function)},
+     * but the provided mapper is one whose result is already an {@code Optional},
+     * and if invoked, {@code flatMap} does not wrap it with an additional
+     * {@code Optional}.
+     *
+     * @param <U> The type parameter to the {@code Optional} returned by
+     * @param mapper a mapping function to apply to the value, if present
+     *           the mapping function
+     * @return the result of applying an {@code Optional}-bearing mapping
+     * function to the value of this {@code Optional}, if a value is present,
+     * otherwise an empty {@code Optional}
+     * @throws DatabaseException 
+     * @throws NullPointerException if the mapping function is null or returns
+     * a null result
+     */
+    public<U> DbOptional<U> flatMap(DbFunction<? super T, DbOptional<U>> mapper) throws DatabaseException {
+        Objects.requireNonNull(mapper);
+        if (!isPresent())
+            return empty();
+        else {
+            return Objects.requireNonNull(mapper.apply(value));
+        }
+    }
+
+    /**
+     * Return the value if present, otherwise return {@code other}.
+     *
+     * @param other the value to be returned if there is no value present, may
+     * be null
+     * @return the value, if present, otherwise {@code other}
+     */
+    public T orElse(T other) {
+        return value != null ? value : other;
+    }
+
+    /**
+     * Return the value if present, otherwise invoke {@code other} and return
+     * the result of that invocation.
+     *
+     * @param other a {@code Supplier} whose result is returned if no value
+     * is present
+     * @return the value if present otherwise the result of {@code other.get()}
+     * @throws DatabaseException 
+     * @throws NullPointerException if value is not present and {@code other} is
+     * null
+     */
+    public T orElseGet(DbSupplier<? extends T> other) throws DatabaseException {
+        return value != null ? value : other.get();
+    }
+
+    /**
+     * Return the contained value, if present, otherwise throw an exception
+     * to be created by the provided supplier.
+     *
+     * @apiNote A method reference to the exception constructor with an empty
+     * argument list can be used as the supplier. For example,
+     * {@code IllegalStateException::new}
+     *
+     * @param <X> Type of the exception to be thrown
+     * @param exceptionSupplier The supplier which will return the exception to
+     * be thrown
+     * @return the present value
+     * @throws X if there is no value present
+     * @throws DatabaseException 
+     * @throws NullPointerException if no value is present and
+     * {@code exceptionSupplier} is null
+     */
+    public <X extends Throwable> T orElseThrow(DbSupplier<? extends X> exceptionSupplier) throws X, DatabaseException {
+        if (value != null) {
+            return value;
+        } else {
+            throw exceptionSupplier.get();
+        }
+    }
+
+    /**
+     * Indicates whether some other object is "equal to" this Optional. The
+     * other object is considered equal if:
+     * <ul>
+     * <li>it is also an {@code Optional} and;
+     * <li>both instances have no value present or;
+     * <li>the present values are "equal to" each other via {@code equals()}.
+     * </ul>
+     *
+     * @param obj an object to be tested for equality
+     * @return {code true} if the other object is "equal to" this object
+     * otherwise {@code false}
+     */
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) {
+            return true;
+        }
+
+        if (!(obj instanceof DbOptional)) {
+            return false;
+        }
+
+        DbOptional<?> other = (DbOptional<?>) obj;
+        return Objects.equals(value, other.value);
+    }
+
+    /**
+     * Returns the hash code value of the present value, if any, or 0 (zero) if
+     * no value is present.
+     *
+     * @return hash code value of the present value or 0 if no value is present
+     */
+    @Override
+    public int hashCode() {
+        return Objects.hashCode(value);
+    }
+
+    /**
+     * Returns a non-empty string representation of this Optional suitable for
+     * debugging. The exact presentation format is unspecified and may vary
+     * between implementations and versions.
+     *
+     * @implSpec If a value is present the result must include its string
+     * representation in the result. Empty and present DbOptionals must be
+     * unambiguously differentiable.
+     *
+     * @return the string representation of this instance
+     */
+    @Override
+    public String toString() {
+        return value != null
+            ? String.format("DbOptional[%s]", value)
+            : "DbOptional.empty";
+    }
+}