Package org.silverpeas.core.calendar

Class Calendar

  • All Implemented Interfaces:
    Serializable, Entity<Calendar,​UuidIdentifier>, IdentifiableEntity, Securable
    @Entity
public class Calendar
extends SilverpeasJpaEntity<Calendar,​UuidIdentifier>
implements Securable
    A calendar is a particular system for scheduling and organizing events and activities that occur at different times or on different dates throughout the years. Before adding any events or activities into a calendar, it requires to be persisted into the Silverpeas data source (use the save method for doing). Once saved, a collection of planned events is then set up for this calendar and through which the events of the calendar can be managed.
    Author:
    mmoquillon
    See Also:
    Serialized Form

    • Constructor Detail

      • Calendar

        protected Calendar()
        Necessary for JPA management.

      • Calendar

        public Calendar​(String instanceId,
                String title)
        Creates in the specified component instance a new calendar with the given title. The timezone identifier of the calendar is set to the default zone id of the platform on which Silverpeas runs.
        Parameters:
        instanceId - the identifier identifying an instance of a component in Silverpeas. Usually, this identifier is the identifier of the component instance to which it belongs (for example almanach32) or the identifier of the user personal calendar.
        title - the title of the calendar.

      • Calendar

        public Calendar​(String instanceId,
                String title,
                ZoneId zoneId)
        Creates in the specified component instance a new calendar with the given title and for the specified zone ID.
        Parameters:
        instanceId - the identifier of an instance of a component in Silverpeas. Usually, this identifier is the identifier of the component instance to which it belongs (for example almanach32) or the identifier of the user personal calendar.
        title - the title of the calendar.
        zoneId - the identifier of a timezone.

    • Method Detail

      • newMainCalendar

        public static Calendar newMainCalendar​(SilverpeasComponentInstance instance)
        Creates for the specified component instance a new main calendar with the given title. The timezone identifier of the calendar is set to the default zone id of the platform on which Silverpeas runs.

        A main calendar is a calendar that can not be deleted while the linked component instance is existing. The title is also set automatically from the instance.

        Parameters:
        instance - an instance of a component in Silverpeas. Usually, this identifier is the identifier of the component instance to which it belongs (for example almanach32) or the identifier of the user personal calendar.
        Returns:
        the initialized main calendar.

      • getById

        public static Calendar getById​(String id)
        Gets a calendar by its identifier.
        Parameters:
        id - the identifier of the aimed calendar.
        Returns:
        the instance of the aimed calendar or null if it does not exist.

      • getByComponentInstanceId

        public static ComponentInstanceCalendars getByComponentInstanceId​(String instanceId)
        Gets the calendars represented by the specified component instance. For instance, the component can be a collaborative application or a personal one.
        Parameters:
        instanceId - the unique identifier identifying an instance of a Silverpeas component.
        Returns:
        a list containing the calendar instances which matched if any, empty list otherwise.

      • getByComponentInstanceIds

        public static List<Calendar> getByComponentInstanceIds​(Collection<String> instanceIds)
        Gets the calendars represented by the specified component instances. For instance, a component can be a collaborative application or a personal one.
        Parameters:
        instanceIds - the unique identifiers identifying instances of a Silverpeas component.
        Returns:
        a list containing the calendar instances which matched if any, empty list otherwise.

      • getTimeWindowBetween

        public static CalendarTimeWindow getTimeWindowBetween​(LocalDate start,
                                                      LocalDate end)
        Gets a calendar window of time defined between the two specified dates and from which the events occurring in the given period can be requested.
        Parameters:
        start - the start date of the period.
        end - the end date of the period.
        Returns:
        a window of time that includes all the calendar events occurring in its specified period of time.

      • getEvents

        public static CalendarEvents getEvents()
        Gets a calendar events instance which permits to get (as stream) events.
        Returns:
        a calendar events instance.

      • getSynchronizedCalendars

        public static List<Calendar> getSynchronizedCalendars()
        Gets all the synchronized calendars in Silverpeas. A calendar is synchronized when it is the counterpart of an external remote calendar and it is regularly updated from this external calendar.
        Returns:
        a list of synchronized calendars.

      • getComponentInstanceId

        public String getComponentInstanceId()
        Gets the identifier of the component instance which the calendar is attached.
        Returns:
        the identifier of the component instance which the calendar is attached.

      • getTitle

        public String getTitle()
        Gets the title of the calendar. If the calendar is the main one of a component instance, then the title is taken from the component instance name.
        Returns:
        the title of the calendar.

      • setTitle

        public void setTitle​(String title)

      • getZoneId

        public ZoneId getZoneId()
        Gets the identifier of the location zone the calendar belongs to.
        Returns:
        the zone id as ZoneId instance.

      • setZoneId

        public void setZoneId​(ZoneId zoneId)

      • getExternalCalendarUrl

        public URL getExternalCalendarUrl()
        Gets the URL of the external calendar with which this calendar is synchronized. This URL is used in the synchronization to fetch the content of the external calendar.
        Returns:
        either the URL of an external calendar or null if this calendar isn't synchronized with such an external calendar.

      • setExternalCalendarUrl

        public void setExternalCalendarUrl​(URL calendarUrl)
        Sets the URL of an external calendar with which this calendar will be synchronized. The URL will be used to get the content of the external calendar.
        Parameters:
        calendarUrl - the URL of a calendar external to Silverpeas.

      • getLastSynchronizationDate

        public Optional<Instant> getLastSynchronizationDate()
        Gets the last synchronization date of this calendar in the case this calendar is a synchronized one. If it is a synchronized calendar and its last synchronization date is empty, this means no synchronization was yet operated.
        Returns:
        optionally the date of its last synchronization date.

      • isSynchronized

        public boolean isSynchronized()
        Is this calendar synchronized with the events from an external calendar.
        Returns:
        true if this calendar is synchronized with an external calendar.

      • setLastSynchronizationDate

        protected void setLastSynchronizationDate​(Instant dateTime)
        Sets the date time at which this calendar is lastly synchronized.
        Parameters:
        dateTime - an Instant value.

      • save

        public void save()
        Saves the calendar into the Silverpeas data source and set up for it a persistence collection of planned event. Once saved, the calendar will be then ready to be used to plan events and activities.

      • delete

        public void delete()
        Deletes the calendar in the Silverpeas data source. By deleting it, the persistence collection of planned events is then tear down, causing the deletion of all of the events planned in this calendar.

      • in

        public CalendarTimeWindow in​(Year year)
        Gets a window of time on this calendar defined by the specified period. The window of time will include only the events in this calendar that occur in the specified period.
        Parameters:
        year - the year during which the events in this calendar occur.
        Returns:
        the window of time including the events in this calendar occurring in the given period.

      • in

        public CalendarTimeWindow in​(YearMonth yearMonth)
        Gets a window of time on this calendar defined by the specified period. The window of time will include only the events in this calendar that occur in the specified period.
        Parameters:
        yearMonth - the month and year during which the events in this calendar occur.
        Returns:
        the window of time including the events in this calendar occurring in the given period.

      • in

        public CalendarTimeWindow in​(LocalDate day)
        Gets a window of time on this calendar defined by the specified period. The window of time will include only the events in this calendar that occur in the specified period.
        Parameters:
        day - day during which the events in this calendar occur.
        Returns:
        the window of time including the events in this calendar occurring in the given period.

      • between

        public CalendarTimeWindow between​(LocalDate start,
                                  LocalDate end)
        Gets a window of time on this calendar defined by the specified period. The window of time will include only the events in this calendar that occur in the specified period.
        Parameters:
        start - the start date of the period.
        end - the end date of the period.
        Returns:
        the window of time including the events in this calendar occurring in the given period.

      • synchronize

        public ICalendarImportResult synchronize()
                                  throws ImportException
        Synchronizes this calendar. An IllegalArgumentException is thrown if this calendar isn't a synchronized one.

        The synchronization is a peculiar and regular import process to update the calendar with its external counterpart in such a way this calendar is a mirror of the external one at a given time.

        Returns:
        the result of the synchronization with the number of events added, updated and deleted in this calendar.
        Throws:
        ImportException - if the synchronization fails.

      • event

        public Optional<CalendarEvent> event​(String eventId)
        Gets either the calendar event with the specified identifier or nothing if no such event exists with the given identifier.
        Parameters:
        eventId - the unique identifier of the event to get.
        Returns:
        optionally an event with the specified identifier.

      • externalEvent

        public Optional<CalendarEvent> externalEvent​(String externalEventId)
        Gets either the calendar external event with the specified external identifier or nothing if no such event exists with the given external identifier. Such events come from either an external calendar with which this calendar is synchronized or from an import of an ics file (iCalendar document containing a collection of calendar component definitions).
        Parameters:
        externalEventId - the unique external identifier of the event to get.
        Returns:
        optionally an event with the specified identifier.

      • clear

        public void clear()
        Clears this calendar of all of the planned events.

      • isEmpty

        public boolean isEmpty()
        Is this calendar empty of event?
        Returns:
        true if there is no events planned in the calendar. Otherwise returns false.

      • isMain

        public boolean isMain()
        Is this calendar the main one of the linked component instance.
        Returns:
        true if it is, false otherwise.

      • isMainPersonalOf

        public boolean isMainPersonalOf​(User user)
        Is this calendar the personal one of the given user which is not modifiable?
        Parameters:
        user - the user to verify.
        Returns:
        true if it is, false otherwise.

      • isPersonalOf

        public boolean isPersonalOf​(User user)
        Is this calendar a personal one of the given user?
        Parameters:
        user - the user to verify.
        Returns:
        true if it is, false otherwise.

      • getToken

        public String getToken()
        Gets the token associated to the calendar.
        Returns:
        the token as string.

      • canBeAccessedBy

        public boolean canBeAccessedBy​(User user)
        Description copied from interface: Securable
        Checks the given user can access this resource.
        Specified by:
        canBeAccessedBy in interface Securable
        Parameters:
        user - a user in Silverpeas.
        Returns:
        true if the user can access the data managed by this instance, false otherwise.

      • canBeModifiedBy

        public boolean canBeModifiedBy​(User user)
        Description copied from interface: Securable
        Checks the given user can modify this resource. By default, if the user can access this securable resource, then it can also modify it.
        Specified by:
        canBeModifiedBy in interface Securable
        Parameters:
        user - a user in Silverpeas.
        Returns:
        true if the user can modify the data managed by this instance, false otherwise.