Class ClientUtils

java.lang.Object
io.fluxzero.sdk.common.ClientUtils
public class ClientUtils extends Object
Utility class offering client-side support functions for working with Fluxzero.

Unlike ObjectUtils, this class is specifically intended for use within Fluxzero client applications and can make use of infrastructure components such as Fluxzero.

It provides convenience methods for:

  • Memoization with lifespans via Fluxzero's clock
  • Topic resolution for annotated handler methods
  • Determining whether handlers are local or self-tracking
  • Time-bound execution blocking
  • Safe annotation parsing and revision introspection
  • Truncating Temporal values

  • Field Details

    • ignoreMarker

      public static final org.slf4j.Marker ignoreMarker
      A marker used to denote specific log entries that should be ignored or treated differently, typically to bypass error handling in logging frameworks.

      This marker is created using the MarkerFactory with the identifier "ignoreError". It can be useful in scenarios where certain log messages need to be flagged for exclusion from error-reporting workflows.

  • Constructor Details

    • ClientUtils

      public ClientUtils()

  • Method Details

    • waitForResults

      public static void waitForResults(Duration maxDuration, Collection<? extends Future<?>> futures)
      Blocks until all futures are complete or the maximum duration has elapsed.

      Useful for tracking batched async operations (e.g., event publishing or indexing).

      Parameters:
      maxDuration - the maximum time to wait
      futures - the set of futures to wait on

    • isSelfTracking

      public static boolean isSelfTracking(Class<?> target, Executable method)
      Returns whether the specified method or its declaring class is marked with TrackSelf.
      Parameters:
      target - the handler class
      method - the method to inspect
      Returns:
      true if marked for self-tracking, false otherwise

    • getLocalHandlerAnnotation

      public static Optional<LocalHandler> getLocalHandlerAnnotation(HandlerInvoker handlerInvoker)
      Retrieves the LocalHandler annotation associated with a given handler, from its method, its declaring class, or ancestral package, if present.

    • getLocalHandlerAnnotation

      public static Optional<LocalHandler> getLocalHandlerAnnotation(Class<?> target, Executable method)
      Retrieves the LocalHandler annotation associated with a given method, its declaring class, or ancestral package, if present.

    • isLocalHandler

      public static boolean isLocalHandler(HandlerInvoker invoker, HasMessage message)
      Determines if the specified handler method handles messages locally. A handler is considered a local if it is explicitly annotated as such using LocalHandler or meets the criteria for local self-handling, i.e.: isLocalSelfHandler(HandlerInvoker, HasMessage) returns true.

    • isLocalSelfHandler

      public static boolean isLocalSelfHandler(HandlerInvoker invoker, HasMessage message)
      Returns whether the handler method should only handle messages from the same instance ("self"). This is true when the handler’s payload type equals the message type and no TrackSelf annotation is present.

    • orderOf

      public static int orderOf(Object component)
      Resolves the configured order for the given component.

      This first checks Fluxzero's own Order annotation and then falls back to Spring's org.springframework.core.annotation.Order when present on the classpath.

      Parameters:
      component - the component to inspect
      Returns:
      the configured order value, or 0 if no order annotation is present

    • loadServices

      public static <T> List<T> loadServices(Class<T> serviceType)
      Loads implementations of the given service using Java's ServiceLoader.

      Misconfigured providers that are present in META-INF/services but missing from the current classpath are skipped. This can happen, for example, when test resources contribute service descriptors without also exposing the corresponding provider classes to downstream modules.

      Type Parameters:
      T - the service type
      Parameters:
      serviceType - the service interface to load
      Returns:
      discovered service implementations, ordered by orderOf(Object)

    • memoize

      public static <T> MemoizingSupplier<T> memoize(Supplier<T> supplier)
      Memoizes the given supplier using a default memoization strategy.

    • memoize

      public static <K,V> MemoizingFunction<K,V> memoize(Function<K,V> supplier)
      Memoizes the given function using a default memoization strategy.

    • memoize

      public static <T,U,R> MemoizingBiFunction<T,U,R> memoize(BiFunction<T,U,R> supplier)
      Memoizes the given bi-function using a default memoization strategy.

    • memoize

      public static <T> MemoizingSupplier<T> memoize(Supplier<T> supplier, Duration lifespan)
      Memoizes the given supplier using a time-based lifespan and Fluxzero’s internal clock.

    • memoize

      public static <K,V> MemoizingFunction<K,V> memoize(Function<K,V> supplier, Duration lifespan)
      Memoizes the given function using a time-based lifespan and Fluxzero's internal clock.

    • memoize

      public static <T,U,R> MemoizingBiFunction<T,U,R> memoize(BiFunction<T,U,R> supplier, Duration lifespan)
      Memoizes the given bi-function using a time-based lifespan and Fluxzero's internal clock.

    • getRevisionNumber

      public static int getRevisionNumber(Object object)
      Extracts the revision number from the Revision annotation on the given object’s class.
      Returns:
      the revision number, or 0 if not present

    • determineSearchCollection

      public static String determineSearchCollection(@NonNull @NonNull Object c)
      Determines the collection name used for document indexing and search based on the annotated handler or document type.

    • getSearchParameters

      public static SearchParameters getSearchParameters(Class<?> type)
      Returns the effective SearchParameters for the given type, using the Searchable annotation. Defaults to a collection name matching the class’s simple name if not explicitly set.

    • getTopics

      public static Set<String> getTopics(MessageType messageType, Object handler)
      Extracts all topics associated with the given handler object and message type.

      The topics are derived based on the handler's annotations or inferred class properties. This method delegates the operation to another overload which processes a collection of handler classes.

      Parameters:
      messageType - the type of the message (e.g., DOCUMENT or CUSTOM)
      handler - the handler object used to determine topics
      Returns:
      a set of topic names associated with the handler and message type

    • getTopics

      public static Set<String> getTopics(MessageType messageType, Collection<Class<?>> handlerClasses)
      Extracts all topics from HandleDocument or HandleCustom annotated methods for the given classes.
      Parameters:
      messageType - the type of message (DOCUMENT or CUSTOM)
      handlerClasses - the classes to inspect
      Returns:
      a set of topic names

    • getTopic

      public static String getTopic(HandleDocument handleDocument, Executable executable)
      Extracts the topic associated with a given HandleDocument annotation or Executable. The topic is determined based on the document collection name, the associated document class, or parameter type of the executable.
      Parameters:
      handleDocument - the HandleDocument annotation containing metadata about the document handler. Can specify the document collection or class.
      executable - the Executable (e.g., method or constructor) used to infer the topic if the annotation does not provide one. The parameter type of the executable may determine the topic.
      Returns:
      the topic as a String, or null if no valid topic is determined.

    • truncate

      public static <T extends Temporal> T truncate(T timestamp, TemporalUnit unit)
      Truncates a Temporal (e.g., LocalDateTime) to the specified unit (e.g., MONTHS or YEARS). Automatically adjusts the truncation unit for compound units like MONTHS -> DAYS.
      Parameters:
      timestamp - the temporal value to truncate
      unit - the unit to truncate to
      Returns:
      a truncated version of the original value