Package org.exoplatform.agenda.service

Interface AgendaCalendarSubscriptionService

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

Who: a subscription is personal; only the user who subscribed reads, edits, refreshes or removes it. 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

    • getSubscription

      CalendarSubscription getSubscription(long subscriptionId, String username) throws org.exoplatform.commons.exception.ObjectNotFoundException, IllegalAccessException
      Reads one of the user's subscriptions.
      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 it is not the user's

    • 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

    • 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

    • 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 one of the user's subscriptions. A new URL is read before it is stored, and its events replace the old ones.
      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 it is not the user's
      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 one of the user's subscriptions 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 it is not the user's
      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
      Unsubscribes: removes the subscription, 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 it is not the user's

    • 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

    • 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