Class PayloadParameterResolver

java.lang.Object
io.fluxzero.sdk.tracking.handling.PayloadParameterResolver
All Implemented Interfaces:
HandlerInputResolver<HasMessage>, KeyedParameterResolver<HasMessage>, ParameterResolver<HasMessage>, PreparedParameterResolver<HasMessage>
public class PayloadParameterResolver extends Object implements PreparedParameterResolver<HasMessage>, KeyedParameterResolver<HasMessage>, HandlerInputResolver<HasMessage>
Resolves handler method parameters by injecting the message payload.

This resolver matches a parameter when its declared type is assignable from the actual payload class of the incoming message.

This resolver is typically used in conjunction with filters such as PayloadFilter to determine handler compatibility based on payload types.

Special care is taken to allow null payloads for parameters that are declared nullable, which can occur during upcasting or transformation pipelines.

See Also:

  • Constructor Details

    • PayloadParameterResolver

      public PayloadParameterResolver()

  • Method Details

    • matches

      public boolean matches(Parameter p, Annotation methodAnnotation, HasMessage value)
      Description copied from interface: ParameterResolver
      Indicates whether the resolved value is compatible with the declared parameter type.

      This method helps determine whether the parameter can be injected for a given message. It first invokes ParameterResolver.resolve(Parameter, Annotation) and then verifies that the returned value (if any) is assignable to the parameter type.

      Specified by:
      matches in interface ParameterResolver<HasMessage>
      Parameters:
      p - the parameter being checked
      methodAnnotation - the annotation on the handler method
      value - the message instance to use for resolution
      Returns:
      true if the parameter can be resolved and assigned to, false otherwise

    • resolve

      public Function<HasMessage, Object> resolve(Parameter p, Annotation methodAnnotation)
      Description copied from interface: ParameterResolver
      Resolves a Parameter of a handler method into a value function based on the given message.

      If the parameter cannot be resolved by this resolver and ParameterResolver.matches(Parameter, Annotation, M) is not implemented, this method must return null.

      Specified by:
      resolve in interface ParameterResolver<HasMessage>
      Parameters:
      p - the parameter to resolve
      methodAnnotation - the annotation present on the handler method (e.g., @HandleEvent)
      Returns:
      a function that takes a message and returns a value to be injected into the method parameter, or null if the parameter cannot be resolved and ParameterResolver.matches(Parameter, Annotation, M) is not implemented.

    • resolveIfPossible

      public Function<HasMessage, Object> resolveIfPossible(Parameter parameter, Annotation methodAnnotation, HasMessage value)
      Description copied from interface: PreparedParameterResolver
      Returns a prepared resolver for the given message, or null when this resolver cannot handle the parameter.
      Specified by:
      resolveIfPossible in interface PreparedParameterResolver<HasMessage>

    • getCacheKey

      public Object getCacheKey(HasMessage value)
      Description copied from interface: KeyedParameterResolver
      Returns an immutable, equality-stable and preferably low-cardinality applicability key.
      Specified by:
      getCacheKey in interface KeyedParameterResolver<HasMessage>
      Parameters:
      value - current message
      Returns:
      cache key, or null when this message must be evaluated dynamically

    • resolveForKey

      public KeyedParameterResolver.Resolution<HasMessage> resolveForKey(Parameter parameter, Annotation methodAnnotation, HasMessage value, Object cacheKey)
      Description copied from interface: KeyedParameterResolver
      Computes a reusable resolution recipe for the supplied key.
      Specified by:
      resolveForKey in interface KeyedParameterResolver<HasMessage>
      Parameters:
      parameter - handler method parameter
      methodAnnotation - handler method annotation
      value - representative message for the key
      cacheKey - key returned by KeyedParameterResolver.getCacheKey(Object)
      Returns:
      reusable resolution outcome

    • getInputCacheKey

      public Object getInputCacheKey(Parameter parameter, Annotation methodAnnotation, HandlerInput<HasMessage> representative)
      Description copied from interface: HandlerInputResolver
      Returns a key containing every input property that can affect whether this resolver matches the parameter and how the parameter value is resolved.

      Return null when no safe reusable key can be provided. Fluxzero will then fall back to normal per-message resolution. Keys are compared using Object.equals(Object) and must be stable after they are returned.

      Specified by:
      getInputCacheKey in interface HandlerInputResolver<HasMessage>
      Parameters:
      parameter - the handler parameter to resolve
      methodAnnotation - the annotation that marks the handler method, if present
      representative - an input representative of the group to be cached
      Returns:
      a stable, complete cache key, or null to disable prepared resolution for this input

    • isPayloadClassKey

      public boolean isPayloadClassKey(Parameter parameter, Annotation methodAnnotation, HandlerInput<HasMessage> representative)
      Description copied from interface: HandlerInputResolver
      Returns whether the payload's runtime class alone determines this resolver's successful result for the supplied parameter.

      Return true only if every payload of that class produces the same match decision and may use the same prepared resolver. This enables a faster class-based lookup.

      Specified by:
      isPayloadClassKey in interface HandlerInputResolver<HasMessage>
      Returns:
      true if the result can safely be reused for every payload of the same runtime class

    • isNoMatchPayloadClassKey

      public boolean isNoMatchPayloadClassKey(Parameter parameter, Annotation methodAnnotation, HandlerInput<HasMessage> representative)
      Description copied from interface: HandlerInputResolver
      Returns whether an unmatched result is guaranteed to remain unmatched for every payload with the same runtime class.

      This is separate from HandlerInputResolver.isPayloadClassKey(Parameter, Annotation, HandlerInput) because matching and non-matching inputs may require different cache guarantees.

      Specified by:
      isNoMatchPayloadClassKey in interface HandlerInputResolver<HasMessage>
      Returns:
      true if the non-match can safely be reused for the entire payload class

    • prepareInput

      public HandlerInputResolver.Resolution<HasMessage> prepareInput(Parameter parameter, Annotation methodAnnotation, HandlerInput<HasMessage> representative)
      Description copied from interface: HandlerInputResolver
      Determines whether this resolver handles the parameter and, when it does, creates the function that supplies the parameter value during invocation.

      The result must agree with normal ParameterResolver selection, including any contribution the resolver makes to handler specificity.

      Specified by:
      prepareInput in interface HandlerInputResolver<HasMessage>
      Parameters:
      parameter - the handler parameter to resolve
      methodAnnotation - the annotation that marks the handler method, if present
      representative - an input representative of the cache key returned for this parameter
      Returns:
      an unmatched, rejected, or successfully resolved result

    • test

      public boolean test(HasMessage message, Parameter parameter)
      Description copied from interface: ParameterResolver
      Determines whether a given message should be passed to a handler method based on this parameter's characteristics.

      This hook is used after ParameterResolver.matches(Parameter, Annotation, M) is invoked but before ParameterResolver.resolve(Parameter, Annotation) and can thus be used to prevent other parameter resolvers from supplying a candidate for parameter injection.

      Specified by:
      test in interface ParameterResolver<HasMessage>
      Parameters:
      message - the message being evaluated
      parameter - the method parameter to test
      Returns:
      true if the message should be processed, false if it should be filtered out

    • determinesSpecificity

      public boolean determinesSpecificity()
      Indicates that this resolver contributes to disambiguating handler methods when multiple handlers are present in the same target class.

      This is useful when more than one method matches a message, and the framework must decide which method is more specific. If this returns true, the resolver's presence and compatibility with the parameter may influence which handler is selected.

      Specified by:
      determinesSpecificity in interface ParameterResolver<HasMessage>
      Returns:
      true, signaling that this resolver helps determine method specificity

    • specificityPriority

      public int specificityPriority()
      Description copied from interface: ParameterResolver
      Relative priority used when multiple specificity-determining resolvers could explain a matching handler.

      Lower values win over higher values. This matches Fluxzero's regular ordering conventions and makes it possible to prefer semantically stronger matches, such as a direct payload parameter, over broader contextual injections such as an entity value.

      Specified by:
      specificityPriority in interface ParameterResolver<HasMessage>
      Returns:
      resolver priority for specificity comparisons; lower means more specific