Package org.exoplatform.agenda.service

Interface AgendaCalendarSubscriptionService

public interface AgendaCalendarSubscriptionService
Subscribes a user (EXO-90278) or a space (EXO-90373) to a calendar link — an iCal or webcal URL — and keeps its events in a read-only calendar of that owner, refreshed periodically.

Who: a personal subscription is its user's alone; a space's belongs to the space, and only a real manager of the space — a member holding the manager role, the rule publishing a space calendar follows — lists, adds, edits, refreshes or removes it, whoever added it. Its events are the space's: every reader of the space's calendar reads them, nobody writes them. What the platform fetches: only the addresses the subscription guard lets through — never a loopback, private, link-local or cloud-metadata address unless the deployment allows internal addresses — with bounded size, time and redirects, no credentials and no cookies. What is imported: title, time, location and a plain-text description of each occurrence in a bounded window; never an organizer, an attendee, an alarm or an attachment; and nothing imported produces an invitation, a notification or a copy to a connected remote account.

Refusals are thrown as IllegalArgumentException carrying a message code agenda.calendarSubscription.*; a refresh asked too soon, or a URL read too many times in a short window (tooManyReads -- reached from checkUrl(java.lang.String, java.lang.String), createSubscription(java.lang.String, java.lang.String, java.lang.String, java.lang.String) and updateSubscription(long, java.lang.String, java.lang.String, java.lang.String, java.lang.String) alike, since all three read the URL), as an IllegalStateException with such a code.

  • Method Details

    • getSubscriptions

      List<CalendarSubscription> getSubscriptions(String username) throws IllegalAccessException
      Lists the user's subscriptions, oldest first, each with its URL in clear.
      Parameters:
      username - the user
      Returns:
      the subscriptions, bounded
      Throws:
      IllegalAccessException - when the user has no usable identity

    • getSubscriptions

      List<CalendarSubscription> getSubscriptions(long ownerIdentityId, String username) throws org.exoplatform.commons.exception.ObjectNotFoundException, IllegalAccessException
      Lists the subscriptions of an owner, oldest first, each with its URL in clear: the user's own, or a space's for one of its managers (EXO-90373).
      Parameters:
      ownerIdentityId - identity identifier of the owner, a user or a space
      username - the user asking
      Returns:
      the subscriptions, bounded
      Throws:
      org.exoplatform.commons.exception.ObjectNotFoundException - when the owner does not exist or was deleted
      IllegalAccessException - when the user may not manage the owner's subscriptions

    • canManageSubscriptions

      boolean canManageSubscriptions(long ownerIdentityId, String username)
      Whether a user may manage the subscriptions of an owner: the owner itself for a user, a real manager of the space for a space (EXO-90373).
      Parameters:
      ownerIdentityId - identity identifier of the owner, a user or a space
      username - the user
      Returns:
      true when the user may list, add, refresh and remove them

    • getSubscription

      CalendarSubscription getSubscription(long subscriptionId, String username) throws org.exoplatform.commons.exception.ObjectNotFoundException, IllegalAccessException
      Reads a subscription the user manages.
      Parameters:
      subscriptionId - technical identifier of the subscription
      username - the user
      Returns:
      the subscription, with its URL in clear
      Throws:
      org.exoplatform.commons.exception.ObjectNotFoundException - when no such subscription exists
      IllegalAccessException - when the user may not manage it

    • checkUrl

      String checkUrl(String url, String username) throws IllegalAccessException
      Checks that a URL can be subscribed to, by reading it once, without storing anything.
      Parameters:
      url - the URL as the user typed it; webcal:// is accepted
      username - the user
      Returns:
      the calendar's own name (X-WR-CALNAME), or null when it names none
      Throws:
      IllegalAccessException - when the user has no usable identity
      IllegalArgumentException - with a message code when the URL is refused or does not serve a calendar
      IllegalStateException - with tooManyReads when the user has read too many URLs in too short a window

    • checkUrl

      String checkUrl(String url, long ownerIdentityId, String username) throws org.exoplatform.commons.exception.ObjectNotFoundException, IllegalAccessException
      Checks that a URL can be subscribed to by an owner, by reading it once, without storing anything (EXO-90373). A link of this eXo to a calendar of the owner itself is refused.
      Parameters:
      url - the URL as the user typed it; webcal:// is accepted
      ownerIdentityId - identity identifier of the owner, a user or a space
      username - the user asking
      Returns:
      the calendar's own name, or null when it names none
      Throws:
      org.exoplatform.commons.exception.ObjectNotFoundException - when the owner does not exist or was deleted
      IllegalAccessException - when the user may not manage the owner's subscriptions
      IllegalArgumentException - with a message code when the URL is refused or does not serve a calendar

    • createSubscription

      CalendarSubscription createSubscription(String url, String name, String color, String username) throws IllegalAccessException
      Subscribes the user to a URL: reads it, creates the calendar and imports its events.
      Parameters:
      url - the URL as the user typed it
      name - the calendar name, or blank for the feed's own name
      color - the calendar colour #RRGGBB, or blank for an automatic one
      username - the user
      Returns:
      the subscription
      Throws:
      IllegalAccessException - when the user has no usable identity
      IllegalArgumentException - with a message code when the URL is refused, already subscribed, or does not serve a calendar
      IllegalStateException - with tooManyReads when the user has read too many URLs in too short a window

    • createSubscription

      CalendarSubscription createSubscription(String url, String name, String color, long ownerIdentityId, String username) throws org.exoplatform.commons.exception.ObjectNotFoundException, IllegalAccessException
      Subscribes an owner to a URL: reads it, creates the owner's calendar and imports its events (EXO-90373). A space's calendar takes the space's colour, whatever colour is given, and its creation is announced once in the space's stream.
      Parameters:
      url - the URL as the user typed it
      name - the calendar name, or blank for the feed's own name
      color - the calendar colour #RRGGBB, or blank for an automatic one; ignored for a space
      ownerIdentityId - identity identifier of the owner, a user or a space
      username - the user asking, recorded as who added it
      Returns:
      the subscription
      Throws:
      org.exoplatform.commons.exception.ObjectNotFoundException - when the owner does not exist or was deleted
      IllegalAccessException - when the user may not manage the owner's subscriptions
      IllegalArgumentException - with a message code when the URL is refused, already subscribed, or does not serve a calendar

    • updateSubscription

      CalendarSubscription updateSubscription(long subscriptionId, String url, String name, String color, String username) throws org.exoplatform.commons.exception.ObjectNotFoundException, IllegalAccessException
      Changes the name, the colour or the URL of a subscription the user manages. A new URL is read before it is stored, and its events replace the old ones; a space's subscription keeps the space's colour.
      Parameters:
      subscriptionId - technical identifier of the subscription
      url - the new URL, or blank to keep the current one
      name - the new name, or blank to keep the current one
      color - the new colour, or blank to keep the current one
      username - the user
      Returns:
      the subscription as it now stands
      Throws:
      org.exoplatform.commons.exception.ObjectNotFoundException - when no such subscription exists
      IllegalAccessException - when the user may not manage it
      IllegalStateException - with tooManyReads when a new URL is given and the user has read too many in too short a window

    • refreshSubscription

      CalendarSubscription refreshSubscription(long subscriptionId, String username) throws org.exoplatform.commons.exception.ObjectNotFoundException, IllegalAccessException
      Refreshes a subscription the user manages now. A failure is not thrown: it is recorded on the subscription returned, as a scheduled refresh records it.
      Parameters:
      subscriptionId - technical identifier of the subscription
      username - the user
      Returns:
      the subscription after the refresh
      Throws:
      org.exoplatform.commons.exception.ObjectNotFoundException - when no such subscription exists
      IllegalAccessException - when the user may not manage it
      IllegalStateException - with a message code when it was refreshed a moment ago or is being refreshed

    • deleteSubscription

      void deleteSubscription(long subscriptionId, String username) throws org.exoplatform.commons.exception.ObjectNotFoundException, IllegalAccessException
      Removes a subscription the user manages, its calendar and every event it imported.
      Parameters:
      subscriptionId - technical identifier of the subscription
      username - the user
      Throws:
      org.exoplatform.commons.exception.ObjectNotFoundException - when no such subscription exists
      IllegalAccessException - when the user may not manage it

    • deleteCalendarSubscription

      void deleteCalendarSubscription(long calendarId)
      Removes the subscription of a calendar that was deleted by another path, with no permission check, for the platform's own clean-up.
      Parameters:
      calendarId - technical identifier of the deleted calendar

    • getSubscriptionCalendarIds

      List<Long> getSubscriptionCalendarIds(List<Long> ownerIdentityIds)
      The calendars the subscriptions of these owners fill (EXO-90373).

      No permission check: it answers which calendars belong to which owner, nothing of their content. Its caller is the event listing, which has already checked that the reader may access every owner it names.

      Parameters:
      ownerIdentityIds - identity identifiers of the owners, a user or a space each
      Returns:
      technical identifiers of their subscription calendars, empty for none

    • followSpaceColor

      void followSpaceColor(Calendar calendar)
      Gives the calendars a space's subscriptions fill the colour of a calendar of that space just created or saved, so that their events keep reading as the space's (EXO-90373). Nothing happens for a subscribed calendar, a user's calendar, or a colour they already have. No permission check: the calendar was saved by a path that made its own.
      Parameters:
      calendar - the calendar as saved

    • refreshDueSubscriptions

      int refreshDueSubscriptions(int batchSize)
      Refreshes the subscriptions whose refresh is due, at most a batch of them, each claimed in the database first so that a single node of a cluster refreshes it.
      Parameters:
      batchSize - most subscriptions to refresh
      Returns:
      how many were refreshed by this call