Package io.meeds.commons.digest

Interface DigestService

public interface DigestService
Service holding the settings of the digest mail notifications feature. The digest is independent from the notification channels: it only relies on its own settings, the platform wide administrator switch and the choices of each user.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    capture(NotificationInfo notification)
    Stores a notification for the digests of its recipients.
    void
    discard(String username, String pluginId, String parameterName, String parameterValue)
    Forgets the waiting items of a recipient about one object, when the thing that caused them is undone before the digest goes out — an invitation cancelled, a join request withdrawn.
    List<DigestCategoryProvider>
    getCategories()
     
    List<DigestCategory>
    getCategories(Locale locale)
     
    DigestUserSettings
    getUserSettings(String username)
     
    boolean
    isDigestAllowed()
     
    void
    processDueDigests()
    One run of the digest sender: cleans the waiting items nobody will ever read, then serves every user whose daily or weekly digest is due now, in his own timezone.
    void
    saveDigestAllowed(boolean allowed)
    Saves the administrator switch allowing users to set digest mail notifications.
    void
    saveUserSettings(String username, DigestUserSettings settings, String timeZone)
    Saves the digest choices of a user and keeps the digest sender job work list in sync: the user is enrolled when he enables a frequency, and removed when both frequencies end up off.
    void
    updateTimeZone(String username, String timeZone)
    Refreshes the timezone the digest sender job keeps for a user, when the platform saved a new one in his profile: the next occurrence is then computed in that timezone.

  • Method Details

    • isDigestAllowed

      boolean isDigestAllowed()
      Returns:
      true when the administrator allowed users to set digest mail notifications, false otherwise. When nothing was ever saved, the digest is not allowed.

    • saveDigestAllowed

      void saveDigestAllowed(boolean allowed)
      Saves the administrator switch allowing users to set digest mail notifications.
      Parameters:
      allowed - true to allow users to configure their digest

    • getUserSettings

      DigestUserSettings getUserSettings(String username)
      Parameters:
      username - the user to read the choices of
      Returns:
      the digest choices of the user, both frequencies off with no category when he never saved any. The categories of the addons uninstalled since his last save are left out.

    • saveUserSettings

      void saveUserSettings(String username, DigestUserSettings settings, String timeZone) throws IllegalAccessException
      Saves the digest choices of a user and keeps the digest sender job work list in sync: the user is enrolled when he enables a frequency, and removed when both frequencies end up off. A frequency switched on starts covering the notifications received from now on.
      Parameters:
      username - the user saving his choices
      settings - the chosen frequencies and their categories
      timeZone - the user profile timezone, used to send the digest at the right local hour, the server one is used when null
      Throws:
      IllegalAccessException - when the administrator has not allowed the digest mail notifications: nobody can enroll while the switch is off, whatever the caller
      IllegalArgumentException - when a frequency is enabled with no category. The categories that no installed addon provides are left out instead of being rejected, so that uninstalling an addon never keeps a user from saving his choices.

    • getCategories

      List<DigestCategoryProvider> getCategories()
      Returns:
      the categories the user can choose from, in display order. Only the categories of the installed addons are returned.

    • getCategories

      List<DigestCategory> getCategories(Locale locale)
      Parameters:
      locale - the language of the labels
      Returns:
      the categories the user can choose from, in display order, with their label in the given language

    • capture

      void capture(NotificationInfo notification)
      Stores a notification for the digests of its recipients. For each recipient, the item is stored only when the administrator switch is on and the category of the notification belongs to the daily list of a recipient whose daily digest is on, or to his weekly list with his weekly digest on. A notification whose plugin belongs to no installed category is ignored, so are broadcast-to-everyone notifications. One stored row per recipient, shared by his two frequencies, holding ids only: the email text is built fresh at send time.
      Parameters:
      notification - the notification the dispatcher just processed

    • discard

      void discard(String username, String pluginId, String parameterName, String parameterValue)
      Forgets the waiting items of a recipient about one object, when the thing that caused them is undone before the digest goes out — an invitation cancelled, a join request withdrawn. It mirrors the removal of the on-site notifications the addons already do in these cases: the digest must not announce what no longer exists.
      Parameters:
      username - the recipient
      pluginId - the notification type
      parameterName - the stored parameter identifying the object, for example spaceId
      parameterValue - its value

    • processDueDigests

      void processDueDigests()
      One run of the digest sender: cleans the waiting items nobody will ever read, then serves every user whose daily or weekly digest is due now, in his own timezone. Serving a user means moving his watermark (the claim, which makes several servers safe), building his email from the items received since the previous watermark and putting it in the mail queue, then deleting the items every enabled frequency has covered. When the administrator switch is off, the claim and the deletion still happen but no email is built: switching the digest back on then only digests what happens from that moment. Meant to be called by the scheduled job, every hour.

    • updateTimeZone

      void updateTimeZone(String username, String timeZone)
      Refreshes the timezone the digest sender job keeps for a user, when the platform saved a new one in his profile: the next occurrence is then computed in that timezone. Nothing happens for a user with no digest enabled.
      Parameters:
      username - the user whose timezone changed
      timeZone - the new zone id, may be null