Package org.apache.juneau.commons.lang

Class Value<T>

java.lang.Object
org.apache.juneau.commons.lang.Value<T>
Type Parameters:
T - The value type.
Direct Known Subclasses:
BooleanValue, ByteValue, CharValue, DoubleValue, FloatValue, IntegerValue, LongValue, ShortValue, StringValue
public class Value<T> extends Object
A generic mutable value wrapper.

This class provides a simple way to wrap any object type in a mutable container, making it useful for passing mutable references to lambdas, inner classes, and methods. It is similar to Optional but allows the value to be changed after creation.

The class supports method chaining through fluent setters and provides various convenience methods for working with the wrapped value, including mapping, conditional execution, and default value handling.

Features:
Notes:
  • This class is not thread-safe. For concurrent access, consider using atomic classes like AtomicReference.
Examples:

// Basic usage Value<String> name = Value.of("John"); name.set("Jane"); String result = name.get(); // Returns "Jane" // Use in lambda (effectively final variable) Value<String> result = Value.empty(); list.forEach(x -> { if (x.matches(criteria)) { result.set(x); } }); // With default values Value<String> optional = Value.empty(); String value = optional.orElse("default"); // Returns "default" // Mapping values Value<Integer> number = Value.of(5); Value<String> text = number.map(Object::toString); // Value of "5" // With listener for change notification Value<String> monitored = Value.of("initial") .listener(newValue -> log("Value changed to: " + newValue)); monitored.set("updated"); // Triggers listener

Specialized Value Classes:

For primitive types and common use cases, specialized subclasses are available with additional convenience methods:

  • IntegerValue - For mutable integers with getAndIncrement()
  • LongValue - For mutable longs with getAndIncrement()
  • ShortValue - For mutable shorts with getAndIncrement()
  • FloatValue - For mutable floats
  • DoubleValue - For mutable doubles
  • CharValue - For mutable characters
  • BooleanValue - For nullable booleans with isTrue()/isNotTrue()
  • Flag - For non-nullable boolean flags (true/false only, no null state)
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Value()
    Constructor.
    Value(T t)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> Value<T>
    empty()
    Creates a new empty value (with null as the initial value).
    boolean
    equals(Object obj)
     
    Value<T>
    filter(Predicate<? super T> predicate)
    If a value is present, and the value matches the given predicate, returns a Value describing the value, otherwise returns an empty Value.
    <T2> Value<T2>
    flatMap(Function<? super T,? extends Value<? extends T2>> mapper)
    If a value is present, returns the result of applying the given Value-bearing mapping function to the value, otherwise returns an empty Value.
    T
    get()
    Returns the value.
    T
    getAndSet(T t)
    Returns the current value and then sets it to the specified value.
    T
    getAndUnset()
    Returns the current value and then unsets it (sets to null).
    static Type
    getParameterType(Type t)
    Returns the generic parameter type of the Value type.
    int
    hashCode()
     
    void
    ifPresent(Consumer<? super T> consumer)
    If a value is present (not null), invokes the specified consumer with the value, otherwise does nothing.
    boolean
    is(T other)
    Checks if the current value equals the specified value using Utils.eq(Object, Object).
    boolean
    isEmpty()
    Returns true if the value is empty.
    boolean
    isPresent()
    Returns true if the value is set.
    static boolean
    isType(Type t)
    Convenience method for checking if the specified type is this class.
    Value<T>
    listener(ValueListener<T> listener)
    Registers a listener that will be called whenever the value is changed via set(Object).
    <T2> Value<T2>
    map(Function<? super T,T2> mapper)
    Applies a mapping function to the value if present, returning a new Value with the result.
    static <T> Value<T>
    of(T object)
    Creates a new value with the specified initial value.
    T
    orElse(T def)
    Returns the contents of this value or the default value if null.
    T
    orElseGet(Supplier<? extends T> other)
    Return the value if present, otherwise invoke other and return the result of that invocation.
    <X extends Throwable>
    T
    orElseThrow(Supplier<? extends X> exceptionSupplier)
    Return the contained value, if present, otherwise throw an exception to be created by the provided supplier.
    Value<T>
    set(T t)
    Sets the value.
    Value<T>
    setIf(boolean condition, T t)
    Sets the value only if the specified condition is true.
    Value<T>
    setIfEmpty(T t)
    Sets the value only if it is currently empty (null).
    String
    toString()
     
    static Type
    unwrap(Type t)
    Returns the unwrapped type.
    Value<T>
    update(Function<T,T> updater)
    Updates the value in-place using the specified function.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Value

      public Value()
      Constructor.

    • Value

      public Value(T t)
      Constructor.
      Parameters:
      t - Initial value.

  • Method Details

    • empty

      public static <T> Value<T> empty()
      Creates a new empty value (with null as the initial value).
      Example:

      Value<String> value = Value.empty(); assertNull(value.get()); assertTrue(value.isEmpty());

      Type Parameters:
      T - The value type.
      Returns:
      A new empty Value object.

    • isType

      public static boolean isType(Type t)
      Convenience method for checking if the specified type is this class.
      Parameters:
      t - The type to check.
      Returns:
      true if the specified type is this class.

    • of

      public static <T> Value<T> of(T object)
      Creates a new value with the specified initial value.
      Example:

      Value<String> value = Value.of("hello"); assertEquals("hello", value.get());

      Type Parameters:
      T - The value type.
      Parameters:
      object - The object being wrapped. Can be null.
      Returns:
      A new Value object containing the specified value.

    • getParameterType

      public static Type getParameterType(Type t)
      Returns the generic parameter type of the Value type.
      Parameters:
      t - The type to find the parameter type of.
      Returns:
      The parameter type of the value, or null if the type is not a subclass of Value.

    • unwrap

      public static Type unwrap(Type t)
      Returns the unwrapped type.
      Parameters:
      t - The type to unwrap.
      Returns:
      The unwrapped type, or the same type if the type isn't Value.

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • filter

      public Value<T> filter(Predicate<? super T> predicate)
      If a value is present, and the value matches the given predicate, returns a Value describing the value, otherwise returns an empty Value.

      This method is analogous to Optional.filter(Predicate).

      Example:

      Value<String> value = Value.of("hello"); Value<String> filtered = value.filter(s -> s.length() > 3); assertTrue(filtered.isPresent()); Value<String> filtered2 = value.filter(s -> s.length() > 10); assertFalse(filtered2.isPresent());

      Parameters:
      predicate - The predicate to apply to the value, if present. Must not be null.
      Returns:
      A Value describing the value if it is present and matches the predicate, otherwise an empty Value.

    • flatMap

      public <T2> Value<T2> flatMap(Function<? super T,? extends Value<? extends T2>> mapper)
      If a value is present, returns the result of applying the given Value-bearing mapping function to the value, otherwise returns an empty Value.

      This method is similar to map(Function), but the mapping function returns a Value rather than a simple value. This is analogous to Optional.flatMap(Function).

      Example:

      Value<String> value = Value.of("hello"); Value<Integer> length = value.flatMap(s -> Value.of(s.length())); assertEquals(5, length.get()); // Returns empty if mapper returns empty Value<String> empty = value.flatMap(s -> Value.empty()); assertFalse(empty.isPresent());

      Type Parameters:
      T2 - The type of value in the Value returned by the mapping function.
      Parameters:
      mapper - The mapping function to apply to the value, if present. Must not be null.
      Returns:
      The result of applying the Value-bearing mapping function to the value if present, otherwise an empty Value.

    • get

      public T get()
      Returns the value.
      Returns:
      The value, or null if it is not set.

    • getAndSet

      public T getAndSet(T t)
      Returns the current value and then sets it to the specified value.
      Example:

      Value<String> value = Value.of("old"); String oldValue = value.getAndSet("new"); // Returns "old" String newValue = value.get(); // Returns "new"

      Parameters:
      t - The new value.
      Returns:
      The value before it was set.

    • getAndUnset

      public T getAndUnset()
      Returns the current value and then unsets it (sets to null).

      This is useful for "consuming" a value, ensuring it can only be retrieved once.

      Example:

      Value<String> value = Value.of("data"); String result = value.getAndUnset(); // Returns "data" assertNull(value.get()); // Value is now null

      Returns:
      The value before it was unset, or null if it was already null.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • ifPresent

      public void ifPresent(Consumer<? super T> consumer)
      If a value is present (not null), invokes the specified consumer with the value, otherwise does nothing.
      Example:

      Value<String> value = Value.of("hello"); value.ifPresent(System.out::println); // Prints "hello" Value<String> empty = Value.empty(); empty.ifPresent(System.out::println); // Does nothing

      Parameters:
      consumer - Block to be executed if a value is present. Must not be null.

    • is

      public boolean is(T other)
      Checks if the current value equals the specified value using Utils.eq(Object, Object).

      This method uses eq() for equality comparison, which handles null values safely and performs deep equality checks for arrays and collections.

      Example:

      Value<String> value = Value.of("hello"); assertTrue(value.is("hello")); assertFalse(value.is("world")); // Handles null values safely Value<String> empty = Value.empty(); assertTrue(empty.is(null)); assertFalse(empty.is("test")); // Works with any type Value<Integer> number = Value.of(42); assertTrue(number.is(42)); assertFalse(number.is(43));

      Parameters:
      other - The value to compare with. Can be null.
      Returns:
      true if the values are equal according to Utils.eq(Object, Object).

    • isEmpty

      public boolean isEmpty()
      Returns true if the value is empty.
      Returns:
      true if the value is empty.

    • isPresent

      public boolean isPresent()
      Returns true if the value is set.
      Returns:
      true if the value is set.

    • listener

      public Value<T> listener(ValueListener<T> listener)
      Registers a listener that will be called whenever the value is changed via set(Object).

      Only one listener can be registered at a time. Calling this method again will replace the previous listener.

      Example:

      Value<String> value = Value.of("initial"); value.listener(newValue -> log("Changed to: " + newValue)); value.set("updated"); // Triggers listener, logs "Changed to: updated"

      Parameters:
      listener - The listener to be called on value changes. Can be null to remove the listener.
      Returns:
      This object for method chaining.
      See Also:

    • map

      public <T2> Value<T2> map(Function<? super T,T2> mapper)
      Applies a mapping function to the value if present, returning a new Value with the result.

      If this value is empty (null), returns an empty value without applying the mapper.

      Example:

      Value<String> name = Value.of("john"); Value<String> upper = name.map(String::toUpperCase); assertEquals("JOHN", upper.get()); Value<Integer> length = name.map(String::length); assertEquals(4, length.get()); Value<String> empty = Value.empty(); Value<Integer> result = empty.map(String::length); // Returns empty Value

      Type Parameters:
      T2 - The mapped value type.
      Parameters:
      mapper - The mapping function to apply. Must not be null.
      Returns:
      A new Value containing the mapped result, or an empty value if this value is empty.

    • orElse

      public T orElse(T def)
      Returns the contents of this value or the default value if null.
      Parameters:
      def - The default value.
      Returns:
      The contents of this value or the default value if null.

    • orElseGet

      public T orElseGet(Supplier<? extends T> other)
      Return the value if present, otherwise invoke other and return the result of that invocation.
      Parameters:
      other - a Supplier whose result is returned if no value is present
      Returns:
      the value if present otherwise the result of other.get()
      Throws:
      NullPointerException - if value is not present and other is null

    • orElseThrow

      public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X
      Return the contained value, if present, otherwise throw an exception to be created by the provided supplier.
      Type Parameters:
      X - The exception type.
      Parameters:
      exceptionSupplier - The supplier which will return the exception to be thrown
      Returns:
      the present value
      Throws:
      X - if there is no value present
      NullPointerException - if no value is present and exceptionSupplier is null

    • set

      public Value<T> set(T t)
      Sets the value.

      If a ValueListener is registered, it will be notified of the change.

      Example:

      Value<String> value = Value.empty(); value.set("hello").set("world"); // Method chaining assertEquals("world", value.get());

      Parameters:
      t - The new value. Can be null.
      Returns:
      This object for method chaining.

    • setIf

      public Value<T> setIf(boolean condition, T t)
      Sets the value only if the specified condition is true.
      Example:

      Value<String> value = Value.of("old"); value.setIf(true, "new"); // Sets to "new" value.setIf(false, "newer"); // Does nothing assertEquals("new", value.get());

      Parameters:
      condition - The condition to check.
      t - The value to set if condition is true.
      Returns:
      This object.

    • setIfEmpty

      public Value<T> setIfEmpty(T t)
      Sets the value only if it is currently empty (null).

      If the value is already set, this method does nothing.

      Example:

      Value<String> value = Value.empty(); value.setIfEmpty("first"); // Sets value to "first" value.setIfEmpty("second"); // Does nothing, value remains "first" assertEquals("first", value.get());

      Parameters:
      t - The new value. Can be null.
      Returns:
      This object for method chaining.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • update

      public Value<T> update(Function<T,T> updater)
      Updates the value in-place using the specified function.

      If the current value is null, this is a no-op.

      Example:

      Value<String> value = Value.of("hello"); value.update(String::toUpperCase); assertEquals("HELLO", value.get()); // No-op when null Value<String> empty = Value.empty(); empty.update(String::toUpperCase); // Does nothing assertNull(empty.get());

      Parameters:
      updater - The function to apply to the current value. Must not be null.
      Returns:
      This object.