Package org.silverpeas.core.calendar

Class CalendarEvent

    • Constructor Detail

      • CalendarEvent

        protected CalendarEvent​(Period period)
        Constructs a new calendar event that spawns to the specified period of time.
        Parameters:
        period - a period of time in which this event occurs.

      • CalendarEvent

        protected CalendarEvent()
        Constructs an empty calendar event. This constructor is dedicated to the persistence engine when loading events from the data source.

    • Method Detail

      • getById

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

      • getByIds

        public static List<CalendarEvent> getByIds​(List<String> ids)
        Gets list of calendar event by their identifier.
        Parameters:
        ids - the identifiers of the aimed calendar events.
        Returns:
        the instance of the aimed calendar event or null if it does not exist.

      • getByExternalId

        public static CalendarEvent getByExternalId​(Calendar calendar,
                                            String externalId)
        Gets a calendar event by its external identifier and the calendar it belongs. An external identifier is the identifier of an event that was imported from an external calendar into a calendar in Silverpeas. This identifier is the one of the event in the external calendar.
        Parameters:
        calendar - the calendar repository.
        externalId - the identifier of the calendar event in the external calendar from which it was imported.
        Returns:
        the instance of the asked calendar event or null if it does not exist.

      • on

        public static CalendarEvent on​(Period period)
        Creates a new calendar event that is spanning on the specified period of time.
        Parameters:
        period - the period on which the event occurs.
        Returns:
        a calendar event occurring on the specified period.

      • on

        public static CalendarEvent on​(LocalDate day)
        Creates a new calendar event that is on all the specified day.
        Parameters:
        day - the day on which the event will occur.
        Returns:
        a calendar event spanning on all the specified day.

      • getContent

        public Optional<WysiwygContent> getContent()
        Gets optionally the rich content of this event.
        Returns:
        the rich content of this event as an Optional value.

      • setContent

        public void setContent​(WysiwygContent content)
        Sets the rich content of this event.
        Parameters:
        content - the content to set.

      • createdBy

        public CalendarEvent createdBy​(User user)
        This event is created by the specified user.
        Parameters:
        user - the user to set as the creator of this event.
        Returns:
        itself.

      • createdBy

        public CalendarEvent createdBy​(String userId)
        This event is created by the specified user.
        Parameters:
        userId - the unique identifier of the user to set as the creator of this event.
        Returns:
        itself.

      • getCreator

        public User getCreator()
        Gets the user who created and planned this event.
        Specified by:
        getCreator in interface SilverpeasResource
        Returns:
        the user that has authored this event.

      • getLastUpdater

        public User getLastUpdater()
        Gets the last user who updated this planned event.
        Specified by:
        getLastUpdater in interface SilverpeasResource
        Returns:
        the user who has last updated this event.

      • getLastUpdateDate

        public Date getLastUpdateDate()
        Description copied from interface: SilverpeasResource
        Gets the date at which the resource has been lastly updated. If the resource doesn't have such an information, then this method should return the date of the resource creation.
        Specified by:
        getLastUpdateDate in interface SilverpeasResource
        Returns:
        the date of the last update of the resource.

      • getCalendar

        public Calendar getCalendar()
        Gets the calendar to which this event is related. A calendar event can only be persisted into a given existing calendar.
        Specified by:
        getCalendar in interface PlannableOnCalendar
        Returns:
        either the calendar to which this event belongs or null if this event isn't yet saved into a given calendar.

      • setCalendar

        protected void setCalendar​(Calendar calendar)
        Sets a new calendar to this event. This moves the event from its initial calendar to the specified calendar. This will be effective once the update() method invoked.
        Parameters:
        calendar - the new calendar into which the event has to move.

      • getTitle

        public String getTitle()
        Description copied from interface: PlannableOnCalendar
        Gets the title of this plannable object. A title is a short resume or the subject of the plannable object.
        Specified by:
        getTitle in interface Contribution
        Specified by:
        getTitle in interface PlannableOnCalendar
        Returns:
        a short text about the reason of this plannable object.

      • setTitle

        public void setTitle​(String title)
        Description copied from interface: PlannableOnCalendar
        Sets a title to this plannable object. A title is a short resume or the subject of the plannable object.
        Specified by:
        setTitle in interface PlannableOnCalendar
        Parameters:
        title - a short text about the reason of this plannable object.

      • getExternalId

        public String getExternalId()
        Gets the external identifier.

        Any events coming from a calendar external to Silverpeas are identified by an unique identifier for this external calendar. The external identifier is this identifier and it is null for events in a Silverpeas calendar. This identifier is typically processed by the calendar import/export mechanism of Silverpeas.

        Returns:
        the external identifier as string.

      • withExternalId

        public CalendarEvent withExternalId​(String externalId)
        Specifies an external identifier.
        Parameters:
        externalId - an external identifier as string.
        Returns:
        itself.

      • isExternal

        public boolean isExternal()
        Indicates if the event is coming from another platform than Silverpeas.
        Returns:
        true if the event is coming from another platform, false otherwise.

      • getLastSynchronizationDate

        public Instant getLastSynchronizationDate()
        Gets the last date at which this event was synchronized from an external calendar.
        Returns:
        a date and time or null if this event isn't a synchronized one.

      • isSynchronized

        public boolean isSynchronized()
        Is this event comes from the synchronization of an external calendar?
        Returns:
        true if this event is a synchronized one, false otherwise.

      • setLastSynchronizationDate

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

      • withTitle

        public CalendarEvent withTitle​(String title)
        Specifies a title to this event.
        Parameters:
        title - the title of the event
        Returns:
        itself.

      • inLocation

        public CalendarEvent inLocation​(String location)
        Specifies a location where this event will occur.
        Parameters:
        location - a location: an address, a designation, a GPS coordinates, ...
        Returns:
        itself.

      • withVisibilityLevel

        public CalendarEvent withVisibilityLevel​(VisibilityLevel accessLevel)
        Specifies the visibility level to this event. In generally, it defines the intention of the user about the visibility on the event he accepts to give. Usual values are PUBLIC, PRIVATE or CONFIDENTIAL for example. By default, the visibility level is PUBLIC.
        Parameters:
        accessLevel - the new visibility level to this event.
        Returns:
        itself.

      • getCategories

        public CategorySet getCategories()
        Gets the categories to which this event belongs.
        Specified by:
        getCategories in interface Categorized
        Returns:
        the categories of this event.

      • getVisibilityLevel

        public VisibilityLevel getVisibilityLevel()
        Gets the visibility level of this event.
        Returns:
        the visibility level of this event.

      • getDescription

        public String getDescription()
        Gets a description about this event.
        Specified by:
        getDescription in interface Contribution
        Specified by:
        getDescription in interface Nameable
        Returns:
        a description about this event or an empty string if no description is attached to this event.

      • setDescription

        public void setDescription​(String description)
        Sets a new description to this event.
        Parameters:
        description - a new description of the event.

      • getPriority

        public Priority getPriority()
        Gets the priority of this event.
        Specified by:
        getPriority in interface Prioritized
        Returns:
        the priority of the event.

      • getAttributes

        public AttributeSet getAttributes()
        Gets the different additional attributes set to this event.
        Returns:
        the additional attributes of this event.

      • getSequence

        public long getSequence()
        Gets the revision sequence number of this calendar event within a sequence of revisions. Any changes to some properties of a calendar event increment this sequence number. This number is mainly dedicated with the synchronization or syndication mechanism of calendar events with external calendars. Its meaning comes from the icalendar specification.
        Returns:
        the sequence number of this event.
        See Also:
        CalendarComponent.getSequence()

      • getLocation

        public String getLocation()
        Gets the location where the event occurs. It can be an address, a designation or a GPS coordinates.
        Returns:
        the event's location.

      • setLocation

        public void setLocation​(String location)
        Sets a new location for this event. It can be an address, a designation or a GPS coordinates.
        Parameters:
        location - a location where the event occurs.

      • recur

        public CalendarEvent recur​(Recurrence recurrence)
        Recurs this event with the specified event recurrence.

        If the recurrence ends up at a given date or datetime, then this value is updated according to the period of time of this event:

        • The event is on all the day: the recurrence rule is updated to end at the given recurrence ending date; the time part is removed.
        • The event starts and ends at a given datetime: the recurrence rule is updated to end at a datetime with as date the given recurrence ending date and as time the time at which this event usually starts.
        Specified by:
        recur in interface Recurrent
        Parameters:
        recurrence - the recurrence defining the recurring property of this event.
        Returns:
        itself.

      • unsetRecurrence

        public void unsetRecurrence()
        Description copied from interface: Recurrent
        Unset the recurrence of this possibly recurrent object. It is no more recurrent.
        Specified by:
        unsetRecurrence in interface Recurrent

      • withDescription

        public CalendarEvent withDescription​(String description)
        Sets a description ot this event.
        Parameters:
        description - the description to set.
        Returns:
        itself.

      • withAttribute

        public CalendarEvent withAttribute​(String attrName,
                                   String attrValue)
        Adds the specified attribute among the attributes of this event. Same as 
        
 getAttributes().add(attrName, attrValue);
 return this;
        Parameters:
        attrName - the name of the attribute to add.
        attrValue - the value of the attribute to add.
        Returns:
        itself.

      • withCategories

        public CalendarEvent withCategories​(String... categories)
        Adds the specified categories to the event. Same as 
        
 getCategories().addAll(categories);
 return this;
        Parameters:
        categories - one or more categories with which this event will be categorized.
        Returns:
        itself.

      • getRecurrence

        public Recurrence getRecurrence()
        Gets the recurrence of this recurring event. If the event isn't a recurring one, then returns NO_RECURRENCE.
        Specified by:
        getRecurrence in interface Recurrent
        Returns:
        this event recurrence or NO_RECURRENCE.

      • isOnAllDay

        public boolean isOnAllDay()
        Is this event occurring on all the day(s)?
        Specified by:
        isOnAllDay in interface PlannableOnCalendar
        Returns:
        true if this event is occurring on all its day(s).

      • identifiedBy

        public CalendarEvent identifiedBy​(String appId,
                                  String eventId)
        Sets explicitly the identifier of this event. This method is dedicated to create a transient event from some data, usually for information transfer. Don't use this method if you want to persist the event.

        Be careful: because the identifier is managed by the persistence system, the later cannot be used in the case the identifier is explicitly set.

        Parameters:
        appId - the identifier of the application to which this event is related.
        eventId - the identifier of the event. Once set, the event couldn't be persisted.
        Returns:
        itself

      • getStartDate

        public Temporal getStartDate()
        Description copied from interface: PlannableOnCalendar
        The start date or datetime of the plannable object. It is the inclusive lower bound of the period into which this object occurs in a calendar. If this plannable object is on all days, then gets a date. Otherwise, gets a datetime in UTC/Greenwich.
        Specified by:
        getStartDate in interface PlannableOnCalendar
        Returns:
        a temporal instance of LocalDate if the object is on all the day or a temporal instance of OffsetDateTime) otherwise.

      • getEndDate

        public Temporal getEndDate()
        Description copied from interface: PlannableOnCalendar
        The end date or datetime of the plannable object. It is the exclusive upper bound of the period into which this object occurs in a calendar. If this plannable object is on all days, then gets a date. Otherwise, gets a datetime in UTC/Greenwich. According to the type of the plannable object, the end datetime can be undefined; in this case, it must be indicated as such in the implemented method's documentation.
        Specified by:
        getEndDate in interface PlannableOnCalendar
        Returns:
        a temporal instance of LocalDate if the object is on all the day or a temporal instance of OffsetDateTime) otherwise.

      • setDay

        public void setDay​(LocalDate newDay)
        Changes the planning of this event in the calendar. The change will be effective only once the update method invoked.
        Parameters:
        newDay - the new day at which this event will occur or has actually occurred.

      • planOn

        public CalendarEvent planOn​(Calendar calendar)
        Description copied from interface: PlannableOnCalendar
        Saves this plannable object into the specified calendar. This will add this plannable object into the given calendar, and it will have hence a unique identifier that will uniquely identify it among all others plannable objects in the calendar. If this was already planned in a calendar, nothing is done.
        Specified by:
        planOn in interface PlannableOnCalendar
        Parameters:
        calendar - a calendar on which this object has to be planned.
        Returns:
        itself.

      • isPlanned

        public boolean isPlanned()
        Description copied from interface: PlannableOnCalendar
        Is this planned in a given calendar?
        Specified by:
        isPlanned in interface PlannableOnCalendar
        Returns:
        true if this event is planned in a calendar, false otherwise.

      • getAttendees

        public AttendeeSet getAttendees()
        Gets the attendees. The adding or the removing of an attendee should be done only by the creator of this event. Nevertheless, there is actually no validation of this rule, and it is left to the services to perform such a rule validation according to their own requirements.
        Returns:
        a stream of attendees to this event.

      • withAttendee

        public CalendarEvent withAttendee​(User user)
        Adds an attendee in this event and returns itself. It is a short write of event.getAttendees().add(InternalAttendee.fromUser(user).to(event))
        Parameters:
        user - the user in Silverpeas whose participation in this event is required.
        Returns:
        the event itself.

      • withAttendee

        public CalendarEvent withAttendee​(String email)
        Adds an attendee in this event and returns itself. It is a short write of event.getAttendees().add(ExternalAttendee.withEmail(email).to(event))
        Parameters:
        email - the email of a user external to Silverpeas and for whom the participation in this event is required.
        Returns:
        the event itself.

      • copy

        public CalendarEvent copy()
        Copies the specified event to another one. Only the specific business event attributes are copied. Others business attributes as well as technical ones are set to null: creation date, update date, creator, updater, identifier and version number.
        Returns:
        a shallow copy of this event.

      • deleteOnly

        public CalendarEvent.EventOperationResult deleteOnly​(CalendarEventOccurrence occurrence)
        Deletes only the specified occurrence of this event.

        If the event is non-recurrent, then the event is itself deleted. Otherwise, the original starting date of the occurrence is added into the exception dates of its recurrence rule and the event is updated. Keep in mind this last rule applies even if the occurrence is the single one of the recurrence rule. If the occurrence is persisted, it is then removed from the persistence context

        If this event isn't yet planned, or it has no occurrences, then an IllegalStateException exception is thrown.

        Parameters:
        occurrence - a reference to the occurrence to delete. If the occurrence doesn't come from this event, then an IllegalArgumentException exception is thrown.
        Returns:
        the result of the deletion. If the event is recurrent, it has the updated event (its recurrence rule has been modified). Otherwise, it is empty as the event was deleted.

      • deleteSince

        public CalendarEvent.EventOperationResult deleteSince​(CalendarEventOccurrence occurrence)
        Deletes for this event all the occurrences since and including the specified one.

        If the event is non-recurrent, then the event is itself deleted. Otherwise, the event is updated with its recurrence ending at the original starting date of the given occurrence.

        If this event isn't yet planned, or it has no occurrence, then an IllegalStateException exception is thrown.

        Parameters:
        occurrence - the occurrence since which all the forthcoming occurrences (and including the specified occurrence) have to be deleted. If the occurrence doesn't come from this event, then an IllegalArgumentException exception is thrown.
        Returns:
        the result of the deletion. If the event is recurrent, it has the updated event (its recurrence rule has been modified). Otherwise, it is empty as the event was deleted.

      • updateFrom

        public CalendarEvent.EventOperationResult updateFrom​(CalendarEvent event)
        Updates this event with the state of the specified calendar event.
        Parameters:
        event - the event from which this event should be updated. It must represent this event but with a new state, otherwise an IllegalStateException exception is thrown.
        Returns:
        the result of the update. It has the updated event.

      • updateSince

        public CalendarEvent.EventOperationResult updateSince​(CalendarEventOccurrence occurrence)
        Updates all the occurrences of this event since and including the specified occurrence with the modifications to this event. The modifications to this event are saved for all the occurrences since and including the specified occurrence. The occurrences occurring before the specified occurrence won't be updated.

        If the event isn't yet planned, or it has no occurrence then an IllegalStateException exception is thrown.

        If the specified occurrence is in fact the single one of this event, then this event is itself updated (this is equivalent to the update() method). Otherwise, a new event is created from the modifications to this event.

        Parameters:
        occurrence - the occurrence of the event since which the changes to the event should be applied. If the occurrence doesn't come from this event, then an IllegalArgumentException exception is thrown.
        Returns:
        the result of the update. If the event is recurrent, then it has the updated event (with its modified recurrence rule) and the newly created event (for all the forthcoming occurrences, including the specified one). Otherwise, it has only the updated event.

      • updateOnly

        public CalendarEvent.EventOperationResult updateOnly​(CalendarEventOccurrence occurrence)
        Updates only the specified occurrence among the occurrences of this event.

        If the event is recurrent, even if the given occurrence is the single one obtained from the recurrence rule, then only this occurrence is updated and the changes are persisted. The sequence number of the occurrence is incremented by one.

        If the event is non-recurrent then the changes are applied on this event itself from the state of the occurrence. The sequence number of the event is incremented by one.

        In the case the date at which the occurrence starts is modified, the participation status of all the attendees in this occurrence is cleared. If the occurrence comes from a non-recurrent event, then there are the participation status of all the attendees in this event that are cleared.

        If this event isn't yet planned, or it has no occurrences, then an IllegalStateException exception is thrown.
        Parameters:
        occurrence - a reference to an occurrence of the event with the data modified. If the occurrence doesn't come from this event, then an IllegalArgumentException exception is thrown.
        Returns:
        the result of the update. For a recurrent event, it has only the updated and persisted occurrence. Otherwise, it has the updated event.

      • canBeAccessedBy

        public boolean canBeAccessedBy​(User user)
        Description copied from interface: Contribution
        Is the specified user can access this contribution?

        By default Securable.canBeAccessedBy(User) is implemented so that a user can access a contribution if it has enough rights to access the application instance in which is managed this contribution.
        Indeed, this behavior is mostly the common one.
        But In the case the application instance distributes its contribution along of a categorization tree and the nodes of this tree support access rights, then the user must have also the rights to access the node to which belongs the content.
        Of course it could exist other access rules...

        Specified by:
        canBeAccessedBy in interface Contribution
        Specified by:
        canBeAccessedBy in interface Securable
        Parameters:
        user - a user in Silverpeas.
        Returns:
        true if the user can access this content, false otherwise.

      • getContributionType

        public String getContributionType()
        Description copied from interface: Contribution
        Gets the type of this contribution. The type is a label that identifies uniquely a kind of contribution handled by a Silverpeas application. By default, this method returns the simple name of the class implementing this interface.
        Specified by:
        getContributionType in interface Contribution
        Returns:
        the label of the type of this contribution.

      • 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.

      • asCalendarComponent

        public CalendarComponent asCalendarComponent()
        Gets the CalendarComponent representation of this event. Any change to the returned calendar component will change also the related event.
        Returns:
        a CalendarComponent instance representing this event (without the specific properties related to a calendar event).

      • afterLoadingFromPersistenceContext

        protected void afterLoadingFromPersistenceContext()

      • getPeriod

        public Period getPeriod()
        Gets the planning of this event in the calendar.
        Specified by:
        getPeriod in interface Plannable
        Returns:
        the period of time this event is spanning in the calendar.

      • setPeriod

        public void setPeriod​(Period newPeriod)
        Changes the planning of this event in the calendar. The change will be effective only once the update method invoked.
        Specified by:
        setPeriod in interface Plannable
        Parameters:
        newPeriod - a new period of time on which this event will occur or has actually occurred.

      • getPersistedOccurrences

        public List<CalendarEventOccurrence> getPersistedOccurrences()
        Gets all the occurrences linked to this event and explicitly persisted into persistence context. So, an occurrence providing by a computation (instead of the persistence context) is not included into result list.

        Please notice that the occurrences are retrieved on the demand and the returned list is not coming from an attribute of this event entity

        Returns:
        a list of persisted occurrences linked to this event. If the event isn't recurrent or the event isn't yet planned on a calendar, then an empty list is returned.

      • isModifiedSince

        public boolean isModifiedSince​(CalendarEvent previous)
        Is the properties of this calendar event was modified since its last specified state? The attendees in this event aren't taken into account as they aren't considered as a property of a calendar event.
        Parameters:
        previous - a previous state of this calendar event.
        Returns:
        true if the state of this calendar event is different with the specified one.

      • isIndexable

        public boolean isIndexable()
        Description copied from interface: Contribution
        Is this contribution indexable? By default true.
        Specified by:
        isIndexable in interface Contribution
        Returns:
        a boolean indicating if this contribution can be taken in charge by the Indexation Engine. By default, any contribution in Silverpeas are indexable unless specified otherwise.