Package io.microsphere.util

Class Compatible<T,​R>

  • Type Parameters:
    T - the type of context object associated with this compatibility check (not used directly in logic)
    R - the return type of the conditional function
    public class Compatible<T,​R>
extends java.lang.Object
    A utility class to conditionally execute logic based on version comparison.

    Compatible allows defining conditional logic that is executed only if the current version meets a specified condition relative to another version. It supports common version comparison operations such as equal to, greater than, less than, and their inclusive counterparts.

    Example Usage

    Example 1: Basic Usage

    
 Version currentVersion = Version.of("1.2.3");
 Compatible<Void, String> compatible = new Compatible<>(currentVersion, v -> "Matched Condition");

 // Execute logic only if current version is greater than "1.2.0"
 Optional<String> result = compatible.on(">", "1.2.0", v -> "Executed").call();
 System.out.println(result.orElse("Not Matched")); // Output: Executed

    Example 2: Chaining Conditions

    
 Version currentVersion = Version.of("2.0.0");
 Compatible<Void, String> base = new Compatible<>(currentVersion, null);

 // Apply multiple conditions in sequence
 Optional<String> result = base
     .on("<", "1.9.0", v -> "Older")
     .on("==", "2.0.0", v -> "Exact Match")
     .on(">=", "2.0.0", v -> "At least 2.0.0")
     .call();

 System.out.println(result.orElse("No condition matched")); // Output: Exact Match

    Example 3: Using with Class-based Version

    
 // Automatically fetches version from the manifest of the JAR containing MyComponent.class
 Compatible<MyComponent, Boolean> compatibilityCheck = Compatible.of(MyComponent.class);

 boolean isSupported = compatibilityCheck
     .on(">=", "1.5.0", v -> true)
     .on("<", "1.5.0", v -> false)
     .get() != null;

 System.out.println("Feature supported: " + isSupported);
    See Also:
    Version, Version.Operator

    • Constructor Summary

      Constructors 
      Constructor Description
      Compatible​(Version version, java.util.function.Function<Version,​R> conditionalFunction)
      Constructs a Compatible instance with the specified version and conditional function.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void accept​(java.util.function.Consumer<R> resultConsumer)
      Accepts a consumer to process the result of the conditional function if a matching condition was found.
      java.util.Optional<R> call()
      Executes the conditional function if a matching condition was found and returns the result wrapped in an Optional.
      R get()
      Retrieves the result of the conditional function if a matching condition was found.
      static <T> Compatible<T,​?> of​(java.lang.Class<T> targetClass)
      Creates a Compatible instance for the specified class, automatically detecting its version.
      <R> Compatible<T,​R> on​(Version.Operator operator, Version comparedVersion, java.util.function.Function<Version,​R> conditionalFunction)
      Adds a conditional function to be executed if the current version satisfies the specified operator and compared version.
      <R> Compatible<T,​R> on​(java.lang.String operator, java.lang.String comparedVersion, java.util.function.Function<Version,​R> conditionalFunction)
      Adds a conditional function to be executed if the current version satisfies the specified operator and compared version.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • Compatible

        public Compatible​(Version version,
                  java.util.function.Function<Version,​R> conditionalFunction)
        Constructs a Compatible instance with the specified version and conditional function.

        This constructor initializes a Compatible object with a given version and a function that defines the logic to execute when a version condition is satisfied. The conditional function is applied only if the version meets the criteria defined in subsequent on(String, String, Function) or on(Operator, Version, Function) calls.

        Example Usage

        
 Version currentVersion = Version.of("1.2.3");
 Compatible<Void, String> compatible = new Compatible<>(currentVersion, v -> "Default Result");

 // Execute logic only if current version is greater than "1.2.0"
 Optional<String> result = compatible.on(">", "1.2.0", v -> "Condition Matched").call();
 System.out.println(result.orElse("No Match")); // Output: Condition Matched
        Parameters:
        version - the version to be used for comparison
        conditionalFunction - the function to execute if a condition is satisfied, or null if no default action is needed

    • Method Detail

      • of

        public static <T> Compatible<T,​?> of​(java.lang.Class<T> targetClass)
        Creates a Compatible instance for the specified class, automatically detecting its version.

        This factory method retrieves the version associated with the given class (typically from its JAR manifest) and initializes a Compatible instance with no initial conditional function. This is useful for performing version-based compatibility checks on classes without manually specifying their versions.

        Example Usage

        
 // Automatically fetches version from the manifest of the JAR containing MyComponent.class
 Compatible<MyComponent, Boolean> compatibilityCheck = Compatible.of(MyComponent.class);

 boolean isSupported = compatibilityCheck
     .on(">=", "1.5.0", v -> true)
     .on("<", "1.5.0", v -> false)
     .get() != null;

 System.out.println("Feature supported: " + isSupported); // Output: Feature supported: true (if version >= 1.5.0)
        Type Parameters:
        T - the type of the target class
        Parameters:
        targetClass - the class for which to create a Compatible instance
        Returns:
        a new Compatible instance initialized with the detected version of the target class
        See Also:
        Version.getVersion(Class)

      • on

        public <R> Compatible<T,​R> on​(java.lang.String operator,
                                    java.lang.String comparedVersion,
                                    java.util.function.Function<Version,​R> conditionalFunction)
        Adds a conditional function to be executed if the current version satisfies the specified operator and compared version.

        This method allows chaining multiple conditions. If the current version meets the condition defined by the operator and compared version, the provided function will be executed. Otherwise, the chain continues to the next condition.

        Example Usage

        
 Version currentVersion = Version.of("1.2.3");
 Compatible<Void, String> compatible = new Compatible<>(currentVersion, v -> "Default Result");

 // Execute logic only if current version is greater than "1.2.0"
 Optional<String> result = compatible.on(">", "1.2.0", v -> "Condition Matched").call();
 System.out.println(result.orElse("No Match")); // Output: Condition Matched
        Type Parameters:
        R - the return type of the conditional function
        Parameters:
        operator - the operator to compare versions (e.g., ">", "<", "==", ">=", "<=")
        comparedVersion - the version to compare against, as a string
        conditionalFunction - the function to execute if the condition is met
        Returns:
        a new Compatible instance with the added condition, or the same instance if the condition is not met

      • on

        public <R> Compatible<T,​R> on​(Version.Operator operator,
                                    Version comparedVersion,
                                    java.util.function.Function<Version,​R> conditionalFunction)
        Adds a conditional function to be executed if the current version satisfies the specified operator and compared version.

        This method allows chaining multiple conditions. If the current version meets the condition defined by the operator and compared version, the provided function will be executed. Otherwise, the chain continues to the next condition.

        Example Usage

        
 Version currentVersion = Version.of("1.2.3");
 Compatible<Void, String> compatible = new Compatible<>(currentVersion, v -> "Default Result");

 // Execute logic only if current version is greater than "1.2.0"
 Optional<String> result = compatible.on(Operator.GT, Version.of("1.2.0"), v -> "Condition Matched").call();
 System.out.println(result.orElse("No Match")); // Output: Condition Matched
        Type Parameters:
        R - the return type of the conditional function
        Parameters:
        operator - the operator to compare versions (e.g., Operator.GT, Operator.LT, Operator.EQ, Operator.GE, Operator.LE)
        comparedVersion - the version to compare against
        conditionalFunction - the function to execute if the condition is met
        Returns:
        a new Compatible instance with the added condition, or the same instance if the condition is not met

      • call

        public java.util.Optional<R> call()
        Executes the conditional function if a matching condition was found and returns the result wrapped in an Optional. If no condition matches or no function is defined, returns an empty Optional.

        This method is typically called after chaining one or more on(String, String, Function) conditions. It evaluates the provided function (if any) against the current version and returns the computed result.

        Example Usage

        
 Version currentVersion = Version.of("1.2.3");
 Compatible<Void, String> compatible = new Compatible<>(currentVersion, v -> "Default Result");

 // Execute logic only if current version is greater than "1.2.0"
 Optional<String> result = compatible.on(">", "1.2.0", v -> "Condition Matched").call();
 System.out.println(result.orElse("No Match")); // Output: Condition Matched
        Returns:
        an Optional containing the result of the conditional function, or empty if no condition matched

      • accept

        public void accept​(java.util.function.Consumer<R> resultConsumer)
        Accepts a consumer to process the result of the conditional function if a matching condition was found. This method is useful for side-effect operations such as logging or updating state based on the result.

        If a condition matches and the conditional function produces a result, the provided Consumer will be invoked with that result. If no condition matches or no function is defined, the consumer is not called.

        Example Usage

        
 Version currentVersion = Version.of("1.2.3");
 Compatible<Void, String> compatible = new Compatible<>(currentVersion, v -> "Default Result");

 // Process the result if the condition matches
 compatible.on(">", "1.2.0", v -> "Condition Matched")
           .accept(result -> System.out.println("Result: " + result)); // Output: Result: Condition Matched
        Parameters:
        resultConsumer - the consumer to accept the result of the conditional function

      • get

        @Nullable
public R get()
        Retrieves the result of the conditional function if a matching condition was found. If no condition matches or no function is defined, returns null.

        This method is a convenience wrapper around call() that directly returns the result instead of wrapping it in an Optional. It is useful when you are certain that a condition will match and want to avoid handling Optional.

        Example Usage

        
 Version currentVersion = Version.of("1.2.3");
 Compatible<Void, String> compatible = new Compatible<>(currentVersion, v -> "Default Result");

 // Get the result directly if the condition matches
 String result = compatible.on(">", "1.2.0", v -> "Condition Matched").get();
 System.out.println(result); // Output: Condition Matched
        Returns:
        the result of the conditional function, or null if no condition matched