Interface UserProvider

All Known Subinterfaces:
RefreshingUserProvider<U>
All Known Implementing Classes:
AbstractUserProvider, DelegatingUserProvider, NoOpUserProvider, OidcUserProvider
public interface UserProvider
Service interface for managing User identities in Fluxzero.

A UserProvider is responsible for extracting, resolving, and injecting user identity information into messages. It enables user-aware processing by:

  • Resolving the current authenticated User
  • Looking up users by ID or from message metadata
  • Storing user metadata into messages for downstream correlation

Implementations of this interface can be registered via Java’s ServiceLoader. When multiple implementations are found, they are combined using andThen(UserProvider).

See Also:

  • Field Details

    • defaultUserProvider

      static final UserProvider defaultUserProvider
      Default UserProvider discovered via ServiceLoader. If multiple providers are found, they are chained using andThen(UserProvider). May be null if no provider is registered.

  • Method Details

    • requiresMessageBasedLocalResolution

      default boolean requiresMessageBasedLocalResolution()
      Returns whether locally handled messages must be passed to fromMessage(HasMessage) to determine the handling user.

      Fluxzero normally reuses the user that was selected when the message was dispatched. This avoids constructing a complete message solely to store that user in metadata and read it back again. This is correct for regular providers, including implementations of AbstractUserProvider, where fromMessage(message) returns the same user that addToMetadata(Metadata, User) added.

      Override this method to return true only if fromMessage(HasMessage) can intentionally produce a different user, or if user resolution depends on other parts of the completed message. Local handling will then use the regular message-based path so that the provider retains exactly that behavior.

      Returns:
      true to resolve the handling user from the completed local message; false to reuse the user selected during dispatch

    • getActiveUser

      default User getActiveUser()
      Returns the currently active user, typically injected by the current context.
      Returns:
      the active User, or User.getCurrent() if not explicitly provided

    • getUserById

      User getUserById(Object userId)
      Retrieves a User by their unique identifier.

      This method is primarily used in TestFixture-based access control tests, such as when using whenCommandByUser(...), to simulate requests by a specific user.

      Implementations may return null if the user cannot be found, or alternatively return a new, unprivileged User instance. The latter approach allows tests to verify authorization behavior for unknown or default users without requiring explicit user creation.

      Parameters:
      userId - the unique identifier of the user (typically a String or number)
      Returns:
      the matching User, a default unprivileged User, or null if not found

    • getSystemUser

      User getSystemUser()
      Returns the User representing the system (non-human) identity. Typically used for scheduled messages, internal services, etc.

    • fromMessage

      User fromMessage(HasMessage message)
      Extracts the User from a given HasMessage instance. Implementations may inspect message metadata or payload to resolve the user identity.
      Parameters:
      message - the message containing potential user-related metadata
      Returns:
      the resolved User, or null if no user info was found

    • containsUser

      boolean containsUser(Metadata metadata)
      Checks if the given metadata contains user information that can be resolved by this provider.
      Parameters:
      metadata - the metadata to inspect
      Returns:
      true if the metadata contains recognizable user information

    • removeFromMetadata

      Metadata removeFromMetadata(Metadata metadata)
      Removes any user-related metadata entries from the given Metadata.
      Parameters:
      metadata - the metadata to clean
      Returns:
      a new Metadata instance without any user-specific keys

    • addToMetadata

      default Metadata addToMetadata(Metadata metadata, User user)
      Adds user-related metadata to a message, overwriting existing values if present.
      Parameters:
      metadata - the original metadata
      user - the user whose info should be added
      Returns:
      new metadata including the user identity

    • addToMetadata

      Metadata addToMetadata(Metadata metadata, User user, boolean ifAbsent)
      Adds user-related metadata to a message.
      Parameters:
      metadata - the original metadata
      user - the user to include
      ifAbsent - if true, metadata is only added if not already present
      Returns:
      updated Metadata with user info conditionally added

    • andThen

      default UserProvider andThen(UserProvider other)
      Combines this provider with another.

      The returned provider will try this provider first, falling back to other if a user cannot be resolved. This is useful for composing multiple resolution strategies.

      Parameters:
      other - another user provider to chain after this one
      Returns:
      a new UserProvider that delegates to both providers