Package io.microsphere.util

Class Functional<V>

java.lang.Object

io.microsphere.util.Functional<V>

Type Parameters:

V - The type of the value being operated on

public class Functional<V>
extends java.lang.Object

A fluent API utility class for performing chained operations on a value of type V.

This class allows for conditional processing (on(Predicate)), value transformation (as(Function)), and side-effect execution (apply(Consumer)) in a fluent and readable manner.

The state of the object is not thread-safe due to the mutable internal state tracking (e.g., matched). It's designed for single-threaded use or must be externally synchronized when used concurrently.

Example Usage

 // Example 1: Conditional mapping
 String result = Functional.value("Hello")
     .on(s -> s.length() > 3)
     .as(String::toUpperCase)
     .value();

 // Example 2: Conditional side effect
 Functional.value(42)
     .on(n -> n > 40)
     .apply(n -> System.out.println("Value is: " + n));

 // Example 3: Named functional operation
 Functional.of("user", user)
     .on(u -> u.isActive())
     .as(User::getName)
     .apply(name -> System.out.println("Active user: " + name));
 

Since:

1.0.0

Author:

Mercy

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Functional(java.lang.String name, V value)	Constructs a new Functional instance with the given name and value.

Method Summary

Modifier and Type	Method	Description
void	apply(java.util.function.Consumer<V> valueConsumer)	Applies the given Consumer to the current value as a terminal operation.
<R> Functional<R>	as(java.util.function.Function<V,R> function)	Transforms the current value using the given Function and returns a new Functional wrapping the result.
static <V> Functional<V>	of(java.lang.String name, java.util.function.Supplier<V> valueSupplier)	Creates a named Functional instance whose value is obtained from the given Supplier.
static <V> Functional<V>	of(java.lang.String name, V value)	Creates a named Functional instance wrapping the given value.
Functional<V>	on(java.util.function.Predicate<? super V> predicate)	Tests the current value against the given Predicate.
java.lang.String	toString()	Returns a string representation of this Functional instance, including its name, value, and current match state.
static <V> Functional<V>	value(java.util.function.Supplier<V> valueSupplier)	Creates an unnamed Functional instance whose value is obtained from the given Supplier.
static <V> Functional<V>	value(V value)	Creates an unnamed Functional instance wrapping the given value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Functional

protected Functional(java.lang.String name,
                     V value)

Constructs a new Functional instance with the given name and value.

Example Usage

   // Subclass creating a named Functional wrapper
   Functional<String> func = new Functional<>("greeting", "Hello, World!");
 

Parameters:

name - the descriptive name for this functional instance

value - the value to be operated on

Since:

1.0.0

Method Detail

on

public Functional<V> on(java.util.function.Predicate<? super V> predicate)

Tests the current value against the given Predicate. If the predicate matches, subsequent operations (as(Function), apply(Consumer)) will be executed; otherwise, they will be skipped. If the value is null, the predicate is not evaluated.

Example Usage

   Functional.value("microsphere")
       .on(s -> s.startsWith("micro"))
       .apply(s -> System.out.println("Matched: " + s));
 

Parameters:

predicate - the condition to test the value against

Returns:

this Functional instance for fluent chaining

Since:

1.0.0

as

public <R> Functional<R> as(java.util.function.Function<V,R> function)

Transforms the current value using the given Function and returns a new Functional wrapping the result. If the previous on(Predicate) did not match, the transformation is skipped and this instance is returned as-is.

Example Usage

   Functional<Integer> length = Functional.value("Hello")
       .on(s -> s.length() > 3)
       .as(String::length);
 

Type Parameters:

R - the type of the transformed result

Parameters:

function - the transformation function to apply to the value

Returns:

a new Functional wrapping the transformed result, or this instance if skipped

Since:

1.0.0

apply

public void apply(java.util.function.Consumer<V> valueConsumer)

Applies the given Consumer to the current value as a terminal operation. If the previous on(Predicate) did not match, the consumer is not invoked.

Example Usage

   Functional.value(99)
       .on(n -> n > 50)
       .apply(n -> System.out.println("Large number: " + n));
 

Parameters:

valueConsumer - the consumer to apply to the value

Since:

1.0.0

toString

public java.lang.String toString()

Returns a string representation of this Functional instance, including its name, value, and current match state.

Example Usage

   String text = Functional.of("config", "debug").toString();
   // Output: Functional{name='config', value=debug, matched=null}
 

Overrides:

toString in class java.lang.Object

Returns:

a string describing this instance

Since:

1.0.0

value

public static <V> Functional<V> value(java.util.function.Supplier<V> valueSupplier)

Creates an unnamed Functional instance whose value is obtained from the given Supplier. The supplier is evaluated immediately.

Example Usage

   Functional<Long> timestamp = Functional.value(System::currentTimeMillis);
   timestamp.on(t -> t > 0L)
       .apply(t -> System.out.println("Current time: " + t));
 

Type Parameters:

V - the type of the value

Parameters:

valueSupplier - the supplier providing the value

Returns:

a new unnamed Functional instance wrapping the supplied value

Since:

1.0.0

value

public static <V> Functional<V> value(V value)

Creates an unnamed Functional instance wrapping the given value.

Example Usage

   Functional.value("Hello, World!")
       .on(s -> !s.isEmpty())
       .as(String::toUpperCase)
       .apply(s -> System.out.println(s));
 

Type Parameters:

V - the type of the value

Parameters:

value - the value to wrap

Returns:

a new unnamed Functional instance wrapping the value

Since:

1.0.0

of

public static <V> Functional<V> of(java.lang.String name,
                                   java.util.function.Supplier<V> valueSupplier)

Creates a named Functional instance whose value is obtained from the given Supplier. The supplier is evaluated immediately. The name is useful for debugging and identification in toString().

Example Usage

   Functional<List<String>> items = Functional.of("inventory", () -> fetchItems());
   items.on(list -> !list.isEmpty())
       .apply(list -> System.out.println("Items count: " + list.size()));
 

Type Parameters:

V - the type of the value

Parameters:

name - the descriptive name for this functional instance

valueSupplier - the supplier providing the value

Returns:

a new named Functional instance wrapping the supplied value

Since:

1.0.0

of

public static <V> Functional<V> of(java.lang.String name,
                                   V value)

Creates a named Functional instance wrapping the given value. The name is useful for debugging and identification in toString().

Example Usage

   Functional.of("user-email", user.getEmail())
       .on(email -> email.contains("@"))
       .as(String::toLowerCase)
       .apply(email -> sendNotification(email));
 

Type Parameters:

V - the type of the value

Parameters:

name - the descriptive name for this functional instance

value - the value to wrap

Returns:

a new named Functional instance wrapping the value

Since:

1.0.0