Updated PlaceHolder interface and MutableValue class.

Updated JavaDoc for MutableValue class.
Updated Receiver class with return type for fluent API designs.
Added static method MutableValue.of(value) for easy creation.
Added static method MutableValue.empty() for easy creation.
Added method MutableValue.getValue() for exception-free retrieval of empty values.

Author: osmundf

main-java/app/zoftwhere/function/PlaceHolder.java

@@ -13,6 +13,10 @@ default boolean isEmpty() {
         return !isPresent();
     }
 
+    default T getValue() {
+        return optional().orElse(null);
+    }
+
     default T orElse(T other) {
         return optional().orElse(other);
     }

main-java/app/zoftwhere/mutable/MutableValue.java

@@ -5,27 +5,65 @@
 
 import app.zoftwhere.function.PlaceHolder;
 
+/**
+ * A mutable value.
+ *
+ * @param <T> the type
+ */
 public class MutableValue<T> implements PlaceHolder<T> {
 
     private T value;
 
+    /**
+     * Returns a {@code MutableValue} describing the given value.
+     *
+     * @param value the possibly-{@code null} value to describe
+     * @param <T>   the type of the value
+     * @return {@code MutableValue} instance with the initial specified value
+     */
+    public static <T> MutableValue<T> ofNullable(T value) {
+        return new MutableValue<>(value);
+    }
+
+    /**
+     * Returns an empty {@code MutableValue}.
+     *
+     * @param <T> the type of the value
+     * @return {@code MutableValue} instance with a null initial value.
+     */
+    public static <T> MutableValue<T> empty() {
+        return new MutableValue<>();
+    }
+
+    /**
+     * Constructs a mutable value with initial value of null.
+     */
     public MutableValue() {
         this.value = null;
     }
 
+    /**
+     * Constructs a mutable value.
+     *
+     * @param value initial value
+     */
     public MutableValue(T value) {
         this.value = value;
     }
 
+    /**
+     * Set mutable value.
+     */
     @Override
     public Void set(T value) {
         this.value = value;
+        return null;
     }
 
     /**
-     * Retrieve variable value.
+     * Retrieve mutable value.
      *
-     * @return Stored value.
+     * @return Stored value
      * @exception NoSuchElementException if no value is present
      */
     @Override
@@ -36,18 +74,55 @@ public T get() {
         return value;
     }
 
+    /**
+     * Retrieve mutable value.
+     *
+     * @return Stored value
+     */
+    @Override
+    public T getValue() {
+        return value;
+    }
+
+    /**
+     * Returns an {@code Optional} describing the current value.
+     *
+     * @return an {@code Optional} with a present value if the specified value is non-{@code null}, otherwise an empty
+     * {@code Optional}
+     */
     public Optional<T> optional() {
         return Optional.ofNullable(value);
     }
 
+    /**
+     * Check if value is not null.
+     *
+     * @return {@code true} if a value is present, otherwise {@code false}
+     */
     @Override
     public boolean isPresent() {
         return value != null;
     }
 
+    /**
+     * Check if the value is null.
+     *
+     * @return {@code true} if a value is null, otherwise {@code false}
+     */
     @Override
     public boolean isEmpty() {
         return value == null;
     }
 
+    /**
+     * Retrieves non-null mutable value, otherwise returns {@code other}.
+     *
+     * @param other the value to be returned, if no value is present. May be {@code null}
+     * @return the value, if present, otherwise {@code other}
+     */
+    @Override
+    public T orElse(T other) {
+        return value != null ? value : other;
+    }
+
 }

test-java/app/zoftwhere/mutable/MutableValueTest.java

@@ -7,6 +7,7 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.junit.jupiter.api.Assertions.fail;
 
@@ -22,6 +23,16 @@ void testConstructor() {
         assertEquals(value, actual.get());
     }
 
+    @Test
+    void testOfNullable() {
+        var value = "new value";
+        var actual = MutableValue.ofNullable(value);
+        assertNotNull(value);
+        assertNotNull(actual);
+        assertNotNull(actual.get());
+        assertEquals(value, actual.get());
+    }
+
     @Test
     void testOptional() {
         assertFalse(new MutableValue<String>().optional().isPresent());
@@ -34,6 +45,20 @@ void testOptional() {
         assertEquals(input, fixed.optional().get());
     }
 
+    @Test
+    void testEmpty() {
+        final var value = MutableValue.<String>empty();
+        assertNull(value.getValue());
+        assertTrue(value.isEmpty());
+    }
+
+    @Test
+    void testGetValue() {
+        final var value = MutableValue.<String>empty();
+        value.set("Hello");
+        assertEquals("Hello", value.getValue());
+    }
+
     @Test
     void testOrElse() {
         String output;
@@ -65,7 +90,6 @@ void testIsPresent() {
 
     @Test
     void testIsEmpty() {
-        assertTrue(new MutableValue<String>().isEmpty());
         assertTrue(new MutableValue<String>().isEmpty());
         assertFalse(new MutableValue<>("").isEmpty());
     }

test-java/app/zoftwhere/mutable/scope/MutableValueScopeTest.java

@@ -0,0 +1,17 @@
+package app.zoftwhere.mutable.scope;
+
+import app.zoftwhere.mutable.MutableValue;
+import org.junit.jupiter.api.Test;
+
+class MutableValueScopeTest {
+
+    @Test
+    void testOfNullable() {
+        MutableValue.<String>ofNullable(null).set("");
+    }
+
+    @Test
+    void testEmpty() {
+        MutableValue.<String>empty().set("");
+    }
+}