org.bedework.calsvci

Interface EventsI

All Superinterfaces:

Serializable

public interface EventsI
extends Serializable

Interface for handling bedework event objects.

Author:

Mike Douglass

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	EventsI.CopyMoveStatus Result from copy or move operations.
static class	EventsI.RealiasResult
static class	EventsI.SetEntityCategoriesResult

Method Summary

Modifier and Type	Method and Description
EventInfo.UpdateResult	add(EventInfo ei, boolean noInvites, boolean scheduling, boolean autoCreateCollection, boolean rollbackOnError) Add an event and ensure its location and contact exist.
void	claim(BwEvent ev) Claim ownership of this event
EventsI.CopyMoveStatus	copyMoveNamed(EventInfo from, BwCalendar to, String name, boolean copy, boolean overwrite, boolean newGuidOK) Copy or move the given named entity to the destination calendar and give it the supplied name.
boolean	delete(EventInfo ei, boolean sendSchedulingMessage) Delete an event.
EventInfo	get(BwCalendar col, String name, String recurrenceId, List<String> retrieveList) Get events given the calendar and String name.
EventInfo	get(String colPath, String name) Get events given the calendar and String name.
EventInfo	get(String colPath, String name, String recurrenceId) Get events given the calendar and String name.
Collection<EventInfo>	getByUid(String colPath, String guid, String recurrenceId, RecurringRetrievalMode recurRetrieval) Return one or more events for the current user using the calendar, guid and the recurrence id as a key.
Collection<EventInfo>	getEvents(BwCalendar cal, org.bedework.caldav.util.filter.FilterBase filter, BwDateTime startDate, BwDateTime endDate, List<BwIcalPropertyInfo.BwIcalPropertyInfoEntry> retrieveList, BwIndexer.DeletedState delState, RecurringRetrievalMode recurRetrieval) Return the events for the current user within the given date and time range.
InstancesResponse	getInstances(GetInstancesRequest req) Return the instances for a given combination of start date, rrule, exdates and rdates.
void	markDeleted(BwEvent event) For an event to which we have write access we simply mark it deleted.
EventsI.RealiasResult	reAlias(BwEvent ev) Realias the event - set categories according to the set of aliases.
void	reindex(EventInfo ei) Reindex an event.
EventsI.SetEntityCategoriesResult	setEntityCategories(CategorisedEntity ent, Set<BwCategory> extraCats, Set<String> defCatUids, Set<String> allDefCatUids, Collection<String> strCatUids, ChangeTable changes) Set the entity categories based on multivalued request parameter "categoryKey".
EventInfo.UpdateResult	update(EventInfo ei, boolean noInvites) Update an event.
EventInfo.UpdateResult	update(EventInfo ei, boolean noInvites, String fromAttUri) Update an event in response to an attendee.
EventInfo.UpdateResult	update(EventInfo ei, boolean noInvites, String fromAttUri, boolean alwaysWrite) Update an event in response to an attendee.

Method Detail

getByUid

Collection<EventInfo> getByUid(String colPath,
                               String guid,
                               String recurrenceId,
                               RecurringRetrievalMode recurRetrieval)
                        throws CalFacadeException

Return one or more events for the current user using the calendar, guid and the recurrence id as a key.

For non-recurring events, in normal calendar collections, one and only one event should be returned.

For non-recurring events, in special calendar collections, more than one event might be returned if the guid uniqueness requirement is relaxed, for example, in the inbox. For recurring events, the 'master' event defining the rules together with any exceptions should be returned.

Parameters:

colPath - String collection path

guid - String guid for the event

recurrenceId - String recurrence id or null

recurRetrieval - How recurring event is returned.

Returns:

Collection of EventInfo objects representing event(s).

Throws:

CalFacadeException - on error

get

EventInfo get(String colPath,
              String name)
       throws CalFacadeException

Get events given the calendar and String name. Return null for not found. There should be only one event or none. For recurring, the overrides and possibly the instances will be attached. NOTE: this does not provide alias filtering.

Parameters:

colPath - String collection path fully resolved to target

name - String possible name

Returns:

EventInfo or null

Throws:

CalFacadeException - on error

get

EventInfo get(String colPath,
              String name,
              String recurrenceId)
       throws CalFacadeException

Get events given the calendar and String name. Return null for not found. There should be only one event or none. For recurring, the overrides and possibly the instances will be attached. NOTE: this does not provide alias filtering.

Parameters:

colPath - String collection path

name - String possible name

recurrenceId - non-null for single instance

Returns:

EventInfo or null

Throws:

CalFacadeException - on error

get

EventInfo get(BwCalendar col,
              String name,
              String recurrenceId,
              List<String> retrieveList)
       throws CalFacadeException

Get events given the calendar and String name. Return null for not found. There should be only one event or none. For recurring, the overrides and possibly the instances will be attached. This does provide alias filtering.

Parameters:

col - Collection - possibly a filtered alias

name - String name

recurrenceId - non-null for single instance

retrieveList - List of properties to retrieve or null for a full event.

Returns:

EventInfo or null

Throws:

CalFacadeException - on error

getEvents

Collection<EventInfo> getEvents(BwCalendar cal,
                                org.bedework.caldav.util.filter.FilterBase filter,
                                BwDateTime startDate,
                                BwDateTime endDate,
                                List<BwIcalPropertyInfo.BwIcalPropertyInfoEntry> retrieveList,
                                BwIndexer.DeletedState delState,
                                RecurringRetrievalMode recurRetrieval)
                         throws CalFacadeException

Return the events for the current user within the given date and time range. If retrieveList is supplied only those fields (and a few required fields) will be returned.

Parameters:

cal - BwCalendar object - non-null means limit to given calendar null is limit to current user

filter - BwFilter object restricting search or null.

startDate - BwDateTime start - may be null

endDate - BwDateTime end - may be null.

retrieveList - List of properties to retrieve or null for a full event.

recurRetrieval - How recurring event is returned.

Returns:

Collection populated event value objects

Throws:

CalFacadeException - on error

delete

boolean delete(EventInfo ei,
               boolean sendSchedulingMessage)
        throws CalFacadeException

Delete an event.

Parameters:

ei - BwEvent object to be deleted

sendSchedulingMessage - Send a declined or cancel scheduling message

Returns:

true if event deleted

Throws:

CalFacadeException - on error

add

EventInfo.UpdateResult add(EventInfo ei,
                           boolean noInvites,
                           boolean scheduling,
                           boolean autoCreateCollection,
                           boolean rollbackOnError)
                    throws CalFacadeException

Add an event and ensure its location and contact exist. The calendar path must be set in the event.

For public events some calendar implementors choose to allow the dynamic creation of locations and contacts. For each of those, if we have an id, then the object represents a preexisting database item.

Otherwise the client has provided information which will be used to locate an already existing location or contact. Failing that we use the information to create a new entry.

For user clients, we generally assume no contact and the location is optional. However, both conditions are enforced at the application level.

On return the event object will have been updated. In addition the location and contact may have been updated.

If this is a scheduling event and noInvites is set to false then invitations wil be sent out to the attendees.

The event to be added may be a reference to another event. In this case a number of fields should have been copied from that event. Other fields will come from the target.

Parameters:

ei - EventInfo object to be added

noInvites - True for don't send invitations.

scheduling - True if this is to be added to an inbox - affects required access.

autoCreateCollection - - true if we should add a missing collection

rollbackOnError - true to roll back if we get an error

Returns:

UpdateResult Counts of changes.

Throws:

CalFacadeException - on error

reindex

void reindex(EventInfo ei)

Reindex an event.

Parameters:

ei - EventInfo object to be reindexed

update

EventInfo.UpdateResult update(EventInfo ei,
                              boolean noInvites)
                       throws CalFacadeException

Update an event. Any changeset should be embedded in the event info object.

Parameters:

ei - EventInfo object to be added

noInvites - True for don't send invitations.

Returns:

UpdateResult Counts of changes.

Throws:

CalFacadeException - on error

update

EventInfo.UpdateResult update(EventInfo ei,
                              boolean noInvites,
                              String fromAttUri)
                       throws CalFacadeException

Update an event in response to an attendee. Exactly as normal update if fromAtt is null. Otherwise no status update is sent to the given attendee

Any changeset should be embedded in the event info object.

Parameters:

ei - EventInfo object to be added

noInvites - True for don't send invitations.

fromAttUri - attendee responding

Returns:

UpdateResult Counts of changes.

Throws:

CalFacadeException - on error

update

EventInfo.UpdateResult update(EventInfo ei,
                              boolean noInvites,
                              String fromAttUri,
                              boolean alwaysWrite)
                       throws CalFacadeException

Update an event in response to an attendee. Exactly as normal update if fromAtt is null. Otherwise no status update is sent to the given attendee

Any changeset should be embedded in the event info object.

Parameters:

ei - EventInfo object to be added

noInvites - True for don't send invitations.

fromAttUri - attendee responding

alwaysWrite - write and reindex whatever changetable says

Returns:

UpdateResult Counts of changes.

Throws:

CalFacadeException - on error

markDeleted

void markDeleted(BwEvent event)
          throws CalFacadeException

For an event to which we have write access we simply mark it deleted.

Otherwise we add an annotation maarking the event as deleted.

Parameters:

event - the event

Throws:

CalFacadeException - on error

copyMoveNamed

EventsI.CopyMoveStatus copyMoveNamed(EventInfo from,
                                     BwCalendar to,
                                     String name,
                                     boolean copy,
                                     boolean overwrite,
                                     boolean newGuidOK)
                              throws CalFacadeException

Copy or move the given named entity to the destination calendar and give it the supplied name.

Parameters:

from - Source named entity

to - Destination calendar

name - String name of new entity

copy - true for copying

overwrite - if destination exists replace it.

newGuidOK - set a new guid if needed (e.g. copy in same collection)

Returns:

CopyMoveStatus

Throws:

CalFacadeException - on error

claim

void claim(BwEvent ev)
    throws CalFacadeException

Claim ownership of this event

Parameters:

ev - event

Throws:

CalFacadeException - on error

reAlias

EventsI.RealiasResult reAlias(BwEvent ev)

Realias the event - set categories according to the set of aliases.

This is a bedework function in which we specify which set of aliases we used to add the event. Aliases are used to filter the data and provide a view for users, e.g category="Films"

We need these aliases to provide a way of informing the user what they can subscribe to in order to see the events of interest.

We also use them to set and unset categories, allowing event submitters to consider only topic areas and leave it up to system administrators to define which categories get set

Each alias is a virtual path. For example "/user/adgrp_Eng/Lectures/Lectures" might be a real path with two components
"/user/adgrp_Eng/Lectures" and
"Lectures"

"/user/adgrp_Eng/Lectures" is aliased to "/public/aliases/Lectures" which is a folder containing the alias "/public/aliases/Lectures/Lectures" which is aliased to the single calendar.

Parameters:

ev - event

Returns:

Response containing set of categories referenced by the aliases. Status unknown for unknown alias(es)

getInstances

InstancesResponse getInstances(GetInstancesRequest req)

Return the instances for a given combination of start date, rrule, exdates and rdates. A date/time window may be supplied to limit the result.

Parameters:

req - parameters for the method

Returns:

instances or error response

setEntityCategories

EventsI.SetEntityCategoriesResult setEntityCategories(CategorisedEntity ent,
                                                      Set<BwCategory> extraCats,
                                                      Set<String> defCatUids,
                                                      Set<String> allDefCatUids,
                                                      Collection<String> strCatUids,
                                                      ChangeTable changes)
                                               throws CalFacadeException

Set the entity categories based on multivalued request parameter "categoryKey".

We build a list of categories then update the membership of the entity category collection to correspond.

Parameters:

ent - categorised entity to be adjusted

extraCats - Categories to add as a result of other operations

defCatUids - uids of default categories for current user

allDefCatUids - uids of all public default categories

strCatUids - Categories to add from request

changes - a change table

Returns:

setEventCategoriesResult

Throws:

CalFacadeException - on error