/** * Returns an {@code Optional} describing the specified value, if non-null, * otherwise returns an absent {@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 absent {@code Optional} */ public static <T> Optional<T> ofNullable(T value) { return value == null ? (Optional<T>) absent() : of(value); }
/** * Return the contained value, if present, otherwise null. * * @return the present value, if present, otherwise null */ public T orNull() { return isPresent() ? value : null; }
/** * 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 IllegalArgumentException if value is null */ public static <T> Optional<T> of(T value) { return new Optional<>(value); }
@Test public void isPresent() throws Exception { Assert.assertTrue(Optional.of("42").isPresent()); Assert.assertTrue(Optional.ofNullable("42").isPresent()); Assert.assertFalse(Optional.ofNullable(null).isPresent()); Assert.assertFalse(Optional.absent().isPresent()); }
@Test public void get() throws Exception { Assert.assertEquals("42", Optional.of("42").get()); Assert.assertEquals("42", Optional.ofNullable("42").get()); try { Optional.ofNullable(null).get(); Optional.absent().get(); Assert.fail("Invoking get() on an absent optional should raise an exception."); } catch (IllegalStateException expected) { // No-op. This is the expected behaviour. } }
@Test public void orWithSupplier() throws Exception { final Supplier<String> aStringSupplier = new Supplier<String>() { @Override public String get() { return "42"; } }; Assert.assertEquals("42", Optional.<String>ofNullable(null).or(aStringSupplier)); Assert.assertEquals("42", Optional.<String>absent().or(aStringSupplier)); }
@Test public void orThrow() throws Exception { try { Optional.ofNullable(null).orThrow(new Exception("An exception occurred.")); Optional.absent().orThrow(new Exception("An exception occurred.")); Assert.fail("Invoking orThrow() on an absent optional should throw an exception."); } catch (Exception anException) { // No-op. This is the expected behaviour. } }
@Test public void ifPresent() throws Exception { Optional.ofNullable("42").ifPresent(new Consumer<String>() { @Override public void consume(String value) { Assert.assertEquals("42", value); } }); Optional.ofNullable(null).ifPresent(new Consumer<Object>() { @Override public void consume(Object value) { Assert.fail("ifPresent() on an absent optional should never call its consumer"); } }); Optional.absent().ifPresent(new Consumer<Object>() { @Override public void consume(Object value) { Assert.fail("ifPresent() on an absent optional should never call its consumer"); } }); }
@Test public void orNull() throws Exception { Assert.assertNull(Optional.ofNullable(null).orNull()); Assert.assertNull(Optional.absent().orNull()); }
@Test public void ifPresentOrElse() throws Exception { Optional.ofNullable("42").ifPresentOrElse(new Consumer<String>() { @Override public void consume(String value) { Optional.ofNullable(null).ifPresentOrElse(new Consumer<Object>() { @Override public void consume(Object value) { Optional.absent().ifPresentOrElse(new Consumer<Object>() { @Override public void consume(Object value) {
@Test public void ofNullable() throws Exception { Assert.assertTrue(Optional.ofNullable("42").isPresent()); Assert.assertFalse(Optional.ofNullable(null).isPresent()); }
@Test public void or() throws Exception { Assert.assertEquals("42", Optional.ofNullable(null).or("42")); Assert.assertEquals("42", Optional.absent().or("42")); }
@Test public void orThrowWithSupplier() throws Exception { final Supplier<Exception> anExceptionSupplier = new Supplier<Exception>() { @Override public Exception get() { return new Exception("An exception occurred."); } }; try { Optional.ofNullable(null).orThrow(anExceptionSupplier); Optional.absent().orThrow(anExceptionSupplier); Assert.fail("Invoking orThrow() on an absent optional should throw an exception."); } catch (Exception anException) { // No-op. This is the expected behaviour. } }
/** * 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 isPresent() ? value.hashCode() : 0; }
/** * 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. * * @return the string representation of this instance */ @Override public String toString() { return isPresent() ? String.format("Optional[%s]", value) : "Optional.ABSENT"; } }
/** * If a value is present in this {@code Optional}, returns the value, * otherwise throws {@code IllegalStateException}. * * @return the non-null value held by this {@code Optional} * @throws IllegalStateException if there is no value present */ public T get() { if (isPresent()) { return value; } throw new IllegalStateException("Value is absent."); }
/** * Return the value if present, otherwise return {@code other}. * * @param other the value to be returned if there is no value present, may not * be null * @return the value, if present, otherwise {@code other} * @throws IllegalArgumentException if {@code other} is null */ public T or(T other) { if (other == null) { throw new IllegalArgumentException("null may not be passed as an argument; use orNull() instead."); } return isPresent() ? value : other; }
/** * Return the contained value, if present, otherwise throw an exception * instance provided as the parameter. * * @param <X> Type of the exception to be thrown * @param throwable The throwable instance to be thrown * @return the present value * @throws X if there is no value present * @throws IllegalArgumentException if {@code throwable} is null */ public <X extends Throwable> T orThrow(X throwable) throws X { if (throwable == null) { throw new IllegalArgumentException("null may not be passed as an argument; use orNull() instead."); } if (isPresent()) { return value; } throw throwable; }