X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=blobdiff_plain;f=bundles%2Forg.simantics.db%2Fsrc%2Forg%2Fsimantics%2Fdb%2Ffunction%2FDbOptional.java;h=f3e140b900099e346ae393c214d33c92ff8a8f9d;hb=4b5b16eec880434af849ddd6522332884bfb5538;hp=a15cb110e9e15920db7749caa55d1b218e89c501;hpb=06718abb2b3cc780748553811c4857c165499809;p=simantics%2Fplatform.git 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 index a15cb110e..f3e140b90 100644 --- a/bundles/org.simantics.db/src/org/simantics/db/function/DbOptional.java +++ b/bundles/org.simantics.db/src/org/simantics/db/function/DbOptional.java @@ -1,333 +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. - * - *

- * 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). - * - *

- * 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 { - /** - * 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 Type of the non-existent value - * @return an empty {@code Optional} - */ - public static DbOptional empty() { - @SuppressWarnings("unchecked") - DbOptional t = (DbOptional) 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 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 DbOptional 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 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 DbOptional 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 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 filter(DbPredicate 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}: - * - *

{@code
-     *     Optional fis =
-     *         names.stream().filter(name -> !isProcessedYet(name))
-     *                       .findFirst()
-     *                       .map(name -> new FileInputStream(name));
-     * }
- * - * Here, {@code findFirst} returns an {@code Optional}, and then - * {@code map} returns an {@code Optional} for the desired - * file if one exists. - * - * @param 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 DbOptional map(DbFunction 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 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 DbOptional flatMap(DbFunction> 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 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 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 T orElseThrow(DbSupplier 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: - *
    - *
  • it is also an {@code Optional} and; - *
  • both instances have no value present or; - *
  • the present values are "equal to" each other via {@code equals()}. - *
- * - * @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"; - } -} +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. + * + *

+ * 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). + * + *

+ * 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 { + /** + * 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 Type of the non-existent value + * @return an empty {@code Optional} + */ + public static DbOptional empty() { + @SuppressWarnings("unchecked") + DbOptional t = (DbOptional) 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 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 DbOptional 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 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 DbOptional 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 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 filter(DbPredicate 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}: + * + *

{@code
+     *     Optional fis =
+     *         names.stream().filter(name -> !isProcessedYet(name))
+     *                       .findFirst()
+     *                       .map(name -> new FileInputStream(name));
+     * }
+ * + * Here, {@code findFirst} returns an {@code Optional}, and then + * {@code map} returns an {@code Optional} for the desired + * file if one exists. + * + * @param 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 DbOptional map(DbFunction 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 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 DbOptional flatMap(DbFunction> 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 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 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 T orElseThrow(DbSupplier 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: + *
    + *
  • it is also an {@code Optional} and; + *
  • both instances have no value present or; + *
  • the present values are "equal to" each other via {@code equals()}. + *
+ * + * @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"; + } +}