Class AbstractUserProvider

java.lang.Object
io.fluxzero.sdk.tracking.handling.authentication.AbstractUserProvider
All Implemented Interfaces:
UserProvider
public abstract class AbstractUserProvider extends Object implements UserProvider
Abstract base class for implementing UserProviders that resolve user identities via a metadata key.

This implementation provides a reusable foundation for extracting, injecting, and managing User instances within Metadata, commonly used in message handling scenarios. Most concrete UserProvider implementations can extend this class to inherit standard behavior for:

  • Retrieving a user or resolving a user ID from message metadata via a configured key
  • Checking whether a user is present in metadata
  • Inserting or removing user entries in metadata

Metadata key

The default metadata key is DEFAULT_USER_KEY, which resolves to "$user". With compatibility defaults, this key stores a serialized user object. With defaults version 2026.08.04 or newer, or when USE_USER_ID_METADATA_PROPERTY is enabled, it stores User.id() for regular users and SYSTEM_USER_ID for the system user. Regular IDs resolve through UserProvider.getUserById(Object) and the system ID resolves through UserProvider.getSystemUser(). Custom keys can also be provided via the constructor for flexibility across different application contexts.
See Also:

  • Field Details

    • DEFAULT_USER_KEY

      public static final String DEFAULT_USER_KEY
      Default key used in Metadata to store user information.
      See Also:

    • USE_USER_ID_METADATA_PROPERTY

      public static final String USE_USER_ID_METADATA_PROPERTY
      Property that explicitly selects whether user metadata contains user IDs instead of serialized user objects.
      See Also:

    • SYSTEM_USER_ID

      public static final String SYSTEM_USER_ID
      Reserved user ID that resolves to the system user.
      See Also:

  • Constructor Details

    • AbstractUserProvider

      public AbstractUserProvider(String metadataKey, Class<? extends User> userClass)
      Constructs an AbstractUserProvider using a custom metadata key.
      Parameters:
      metadataKey - the key that stores the user or user ID
      userClass - the concrete user class this provider resolves

    • AbstractUserProvider

      public AbstractUserProvider(Class<? extends User> userClass)
      Constructs an AbstractUserProvider using the default metadata key DEFAULT_USER_KEY.
      Parameters:
      userClass - the concrete user class this provider resolves

  • Method Details

    • fromMessage

      public User fromMessage(HasMessage message)
      Extracts a User from the metadata of a message.

      Uses the configured metadataKey to locate the user in the metadata of the given message. Compatibility defaults only accept a serialized user object. New defaults also accept user IDs while continuing to deserialize user objects written before migration. IDs are resolved through UserProvider.getUserById(Object), except for SYSTEM_USER_ID, which resolves through UserProvider.getSystemUser().

      Specified by:
      fromMessage in interface UserProvider
      Parameters:
      message - the message containing metadata
      Returns:
      the resolved User, or null if not found

    • containsUser

      public boolean containsUser(Metadata metadata)
      Returns true if the metadata contains a user entry under the configured key.
      Specified by:
      containsUser in interface UserProvider
      Parameters:
      metadata - the metadata to inspect
      Returns:
      true if a user is present, otherwise false

    • removeFromMetadata

      public Metadata removeFromMetadata(Metadata metadata)
      Removes the user entry from the metadata.
      Specified by:
      removeFromMetadata in interface UserProvider
      Parameters:
      metadata - the original metadata
      Returns:
      a new Metadata instance without the user entry

    • addToMetadata

      public Metadata addToMetadata(Metadata metadata, User user, boolean ifAbsent)
      Adds a User to the metadata using the configured key. Compatibility defaults serialize the complete user; new defaults store User.id() so the receiving provider can resolve a regular user by ID, or SYSTEM_USER_ID when isSystemUser(User) identifies the user as the system user.
      Specified by:
      addToMetadata in interface UserProvider
      Parameters:
      metadata - the original metadata
      user - the user to add
      ifAbsent - whether to only add the user if it is not already present
      Returns:
      updated metadata including the user
      Throws:
      IllegalArgumentException - if a regular user has the reserved ID SYSTEM_USER_ID

    • isSystemUser

      protected boolean isSystemUser(User user)
      Determines whether a user should be represented by SYSTEM_USER_ID in metadata.

      The default implementation checks whether the supplied user is the same instance as UserProvider.getSystemUser(). Providers whose system user is not a stable instance may override this method with their own identity check.

      Parameters:
      user - the non-null user being added to metadata
      Returns:
      true if the user represents the system identity