Package org.nuxeo.user.preferences.api

Interface UserPreferencesService

All Known Implementing Classes:
UserPreferencesServiceImpl
public interface UserPreferencesService
Service providing the storage and retrieval of user preferences.

There are two different user preferences:

  • UserPreference: a global preference entity providing a value for a given key.
  • UserPreferences: an entity handling a collection of UserPreference used to hold all the preferences for a given document or list all the current user global preference.

key must contain letters, digits, dashes, underscores or periods characters only. By default, value is html-sanitized before being persisted. Sanitizing can be disabled with the UserPreferencesUtil.PROP_SANITIZE_VALUES property. Null value is rejected.

User preferences are saved per repository, meaning 2 preferences with the same key but for different repositories can exist.

The maximum number of preferences for a given user and repository is defined by the UserPreferencesUtil.PROP_MAX_PREFERENCES property (default value: UserPreferencesUtil.DEFAULT_PROP_MAX_PREFERENCES). If this limit is exceeded, a TooManyUserPreferencesException is thrown.

Since:
2025.16

  • Method Details

    • get

      Optional<UserPreference> get(CoreSession session, @Nonnull String key)
      Gets an optional current user's preference for the given key.
      Parameters:
      session - the core session
      key - the preference key
      Returns:
      the user preference entity if any

    • get

      UserPreferences get(CoreSession session, @Nonnull DocumentRef docRef)
      Gets current user's preferences for the given document reference.
      Parameters:
      session - the core session
      docRef - the document reference
      Returns:
      the user document preferences entity

    • get

      Optional<UserPreference> get(CoreSession session, @Nonnull DocumentRef docRef, @Nonnull String key)
      Gets optional current user's preference for the given document reference and key.
      Parameters:
      session - the core session
      docRef - the document reference
      key - the user preference key
      Returns:
      the user document preferences entity if any

    • list

      UserPreferences list(CoreSession session)
      Lists all current user's global preferences.
      Parameters:
      session - the core session
      Returns:
      all the user preference entities

    • create

      UserPreference create(CoreSession session, @Nonnull String key, @Nonnull String value)
      Creates a current user's preference value for the given key.
      Parameters:
      session - the core session
      key - the preference key
      value - the preference value
      Returns:
      the created user preference
      Throws:
      UserPreferencesExistsException - if a UserPreference already exists for the current user and key.
      TooManyUserPreferencesException - if the number of preferences exceeds UserPreferencesUtil.PROP_MAX_PREFERENCES

    • createOrUpdate

      UserPreference createOrUpdate(CoreSession session, @Nonnull String key, @Nonnull String value)
      Creates or updates a current user's preference.
      Parameters:
      session - the core session
      key - the user preference key
      value - the preference value
      Returns:
      the updated user preference

    • create

      UserPreferences create(CoreSession session, @Nonnull DocumentRef docRef, @Nonnull Map<String,String> preferences)
      Creates current user's document preferences.
      Parameters:
      session - the core session
      docRef - the document reference
      preferences - the key / preferences map
      Returns:
      the created user document preferences
      Throws:
      UserPreferencesExistsException - if a UserPreferences already exists for the current user and document reference.
      TooManyUserPreferencesException - if the number of preferences exceeds UserPreferencesUtil.PROP_MAX_PREFERENCES
      API Note:
      an empty preferences map is considered as a null preference, and so rejected

    • update

      UserPreference update(CoreSession session, @Nonnull String key, @Nonnull String value)
      Updates a current user's preference value.
      Parameters:
      session - the core session
      key - the user preference key
      value - the preference new value
      Returns:
      the updated user preference
      Throws:
      UserPreferencesNotFound - if the user preference does not exist

    • update

      UserPreferences update(CoreSession session, @Nonnull DocumentRef docRef, @Nonnull UserPreferences preferences)
      Updates a current user's document preferences.

      Existing document preferences are erased unlike putAll(org.nuxeo.ecm.core.api.CoreSession, org.nuxeo.ecm.core.api.DocumentRef, org.nuxeo.user.preferences.api.UserPreferences) which preserves existing document preferences.

      Parameters:
      session - the core session
      preferences - the user preferences to be updated
      Returns:
      the updated user document preferences
      Throws:
      UserPreferencesNotFound - if the user document preferences does not exist
      TooManyUserPreferencesException - if the number of preferences exceeds UserPreferencesUtil.PROP_MAX_PREFERENCES
      API Note:
      an empty preferences map is considered as a null preference, and so rejected

    • putAll

      UserPreferences putAll(CoreSession session, @Nonnull DocumentRef docRef, @Nonnull UserPreferences preferences)
      Puts all current user's document preferences. If no UserPreferences exists for current user and document reference, it is created.

      Existing document preferences are preserved unless explicitly overwritten by the given UserPreferences.

      Parameters:
      session - the core session
      preferences - the user preferences
      Returns:
      the created or updated user document preferences
      Throws:
      TooManyUserPreferencesException - if the number of preferences exceeds UserPreferencesUtil.PROP_MAX_PREFERENCES
      API Note:
      an empty UserPreferences.preferences() map is considered as a null preference, and so rejected

    • delete

      void delete(CoreSession session, @Nonnull String key)
      Deletes the current user's preference for the given key.
      Parameters:
      session - the core session
      key - the user preference key

    • delete

      void delete(CoreSession session, @Nonnull DocumentRef docRef)
      Deletes all the current user's preferences for the given document reference.
      Parameters:
      session - the core session
      docRef - the user preferences document reference

    • remove

      UserPreferences remove(CoreSession session, @Nonnull DocumentRef docRef, @Nonnull String key)
      Removes the current user's preference for the given document reference and key.
      Parameters:
      session - the core session
      docRef - the document reference
      key - the preference key
      Returns:
      the updated user preferences

    • deleteAllForDocument

      void deleteAllForDocument(CoreSession session, @Nonnull IdRef idRef)
      Internal use.

      Deletes all user preferences for the given document reference. The core session must have sufficient privileges to delete preferences of all users.

      Parameters:
      session - the core session
      idRef - the document id reference

    • deleteAllForUser

      void deleteAllForUser(CoreSession session, @Nonnull String userId)
      Internal use.

      Deletes all preferences for the given user id. The core session must have sufficient privileges to delete preferences of the given user id.

      Parameters:
      session - the core session
      userId - the user id