org.bedework.calsvci

Interface CalendarsI

All Superinterfaces:

Serializable

public interface CalendarsI
extends Serializable

This is the calendars interface for the bedework system. Calendars is something of a misnomer - we're really talking collections here. The type property defines which type of collection we are dealing with. The CalDAV spec defines what is allowable, e.g. no collections inside a calendar collection.

To allow us to enforce access checks we wrap the object inside a wrapper class which blocks access to the getChildren method. To retrieve the children of a calendar object call the getCalendars(BwCalendar) method. The resulting collection is a set of access checked, wrapped objects. Only accessible children will be returned.

Author:

Mike Douglass

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	CalendarsI.CheckSubscriptionResult
static class	CalendarsI.SynchStatusResponse

Method Summary

Modifier and Type	Method and Description
BwCalendar	add(BwCalendar val, String parentPath) Add a calendar object
CalendarsI.CheckSubscriptionResult	checkSubscription(String path) Check the subscription if this is an external subscription.
Collection<BwCalendar>	decomposeVirtualPath(String vpath) A virtual path might be for example "/user/adgrp_Eng/Lectures/Lectures" which has two two components "/user/adgrp_Eng/Lectures" and "Lectures"
boolean	delete(BwCalendar val, boolean emptyIt, boolean sendSchedulingMessage) Delete a calendar.
BwCalendar	get(String path) Get a calendar given the path.
Set<BwCalendar>	getAddContentCollections(boolean includeAliases) Return a list of calendars in which calendar objects can be placed by the current user.
AliasesInfo	getAliasesInfo(String collectionHref, String entityName) Called to get information about aliases to a collection containing the named entity.
Set<BwCategory>	getCategorySet(String href)
Collection<BwCalendar>	getChildren(BwCalendar cal) Returns children of the given calendar to which the current user has some access.
Collection<BwCalendar>	getChildrenIdx(BwCalendar col) Returns children of the given collection to which the current user has some access.
BwCalendar	getHome() Returns root of calendars owned by the current user.
BwCalendar	getHome(BwPrincipal principal, boolean freeBusy) Returns root of calendars owned by the given principal.
BwCalendar	getHomeDb(BwPrincipal principal, boolean freeBusy) Returns root of calendars owned by the given principal.
String	getHomePath() Returns root path of calendars owned by the current user.
BwCalendar	getIdx(String path) Get a calendar given the path.
String	getPreferred(String entityType) Get the default calendar for the current user for the given entity type.
BwCalendar	getPublicCalendars() Returns the root of the tree of public calendars.
String	getPublicCalendarsRootPath() Returns the href of the root of the public calendars tree.
BwCalendar	getSpecial(BwPrincipal owner, int calType, boolean create, int access)
BwCalendar	getSpecial(int calType, boolean create) Get a special calendar (e.g.
BwCalendar	getSpecial(String principal, int calType, boolean create) Get a special calendar (e.g.
CalendarsI.SynchStatusResponse	getSynchStatus(String path)
String	getSyncToken(String path) Return the value to be used as the sync-token property for the given path.
boolean	isEmpty(BwCalendar val) Check to see if a collection is empty.
boolean	isUserRoot(BwCalendar cal) Return true if cal != null and it represents a (local) user root
void	move(BwCalendar val, BwCalendar newParent) Move a calendar object from one parent to another
void	rename(BwCalendar val, String newName) Change the name (path segment) of a calendar object.
BwCalendar	resolveAlias(BwCalendar val, boolean resolveSubAlias, boolean freeBusy) Attempt to get calendar referenced by the alias.
BwCalendar	resolveAliasIdx(BwCalendar val, boolean resolveSubAlias, boolean freeBusy) Attempt to get calendar referenced by the alias.
void	setPreferred(BwCalendar val) set the default calendar for the current user.
void	update(BwCalendar val) Update a calendar object

Method Detail

getPublicCalendarsRootPath

String getPublicCalendarsRootPath()
                           throws CalFacadeException

Returns the href of the root of the public calendars tree.

Returns:

String root path

Throws:

CalFacadeException

getPublicCalendars

BwCalendar getPublicCalendars()
                       throws CalFacadeException

Returns the root of the tree of public calendars. This is NOT a live hibernate object.

Returns:

BwCalendar root

Throws:

CalFacadeException

getHomePath

String getHomePath()
            throws CalFacadeException

Returns root path of calendars owned by the current user. For unauthenticated this will be the public calendar root.

Returns:

String principal home.

Throws:

CalFacadeException

getHome

BwCalendar getHome()
            throws CalFacadeException

Returns root of calendars owned by the current user.

For authenticated, personal access this always returns the user entry in the /user calendar tree, e.g. for user smithj it would return an entry /user/smithj

Returns:

BwCalendar user home.

Throws:

CalFacadeException

getHome

BwCalendar getHome(BwPrincipal principal,
                   boolean freeBusy)
            throws CalFacadeException

Returns root of calendars owned by the given principal.

For authenticated, personal access this always returns the user entry in the /user calendar tree, e.g. for user smithj it would return an entry smithj with path /user/smithj Note: the returned object is NOT a live hibernate object.

Parameters:

principal - whose home we want

freeBusy - true if this is for freebusy access

Returns:

BwCalendar user home.

Throws:

CalFacadeException

getHomeDb

BwCalendar getHomeDb(BwPrincipal principal,
                     boolean freeBusy)
              throws CalFacadeException

Returns root of calendars owned by the given principal.

For authenticated, personal access this always returns the user entry in the /user calendar tree, e.g. for user smithj it would return an entry smithj with path /user/smithj Note: the returned object is a live hibernate object.

Parameters:

principal - whose home we want

freeBusy - true if this is for freebusy access

Returns:

BwCalendar user home.

Throws:

CalFacadeException

decomposeVirtualPath

Collection<BwCalendar> decomposeVirtualPath(String vpath)
                                     throws CalFacadeException

A virtual path might be for example "/user/adgrp_Eng/Lectures/Lectures" which has two two components

• "/user/adgrp_Eng/Lectures" and
• "Lectures"

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

Parameters:

vpath -

Returns:

collection of collection objects - null for bad vpath

Throws:

CalFacadeException

getChildren

Collection<BwCalendar> getChildren(BwCalendar cal)
                            throws CalFacadeException

Returns children of the given calendar to which the current user has some access.

Parameters:

cal - parent calendar

Returns:

Collection of BwCalendar

Throws:

CalFacadeException

getChildrenIdx

Collection<BwCalendar> getChildrenIdx(BwCalendar col)
                               throws CalFacadeException

Returns children of the given collection to which the current user has some access.

The returned objects are from the indexer and are not live hibernate objects

Parameters:

col - parent collection

Returns:

Collection of BwCalendar

Throws:

CalFacadeException

getAddContentCollections

Set<BwCalendar> getAddContentCollections(boolean includeAliases)
                                  throws CalFacadeException

Return a list of calendars in which calendar objects can be placed by the current user.

Caldav currently does not allow collections inside collections so that calendar collections are the leaf nodes only.

Parameters:

includeAliases - - true to include aliases - for public admin we don't want aliases

Returns:

Set of BwCalendar

Throws:

CalFacadeException

isEmpty

boolean isEmpty(BwCalendar val)
         throws CalFacadeException

Check to see if a collection is empty. A collection is not empty if it contains other collections or calendar entities.

Parameters:

val - BwCalendar object to check

Returns:

boolean true if the calendar is empty

Throws:

CalFacadeException

get

BwCalendar get(String path)
        throws CalFacadeException

Get a calendar given the path. If the path is that of a 'special' calendar, for example the deleted calendar, it may not exist if it has not been used.

Parameters:

path - String path of calendar

Returns:

BwCalendar null for unknown calendar

Throws:

CalFacadeException

getIdx

BwCalendar getIdx(String path)
           throws CalFacadeException

Get a calendar given the path. If the path is that of a 'special' calendar, for example the deleted calendar, it may not exist if it has not been used. Returns the non-persisted version from the index

Parameters:

path - String path of calendar

Returns:

BwCalendar null for unknown calendar

Throws:

CalFacadeException

getSpecial

BwCalendar getSpecial(int calType,
                      boolean create)
               throws CalFacadeException

Get a special calendar (e.g. Notifications) for the current user. If it does not exist and is supported by the target system it will be created.

Parameters:

calType - int special calendar type.

create - true if we should create it if non-existent.

Returns:

BwCalendar null for unknown calendar

Throws:

CalFacadeException

getSpecial

BwCalendar getSpecial(String principal,
                      int calType,
                      boolean create)
               throws CalFacadeException

Get a special calendar (e.g. Notifications) for the given user. If it does not exist and is supported by the target system it will be created.

Parameters:

principal - the principal href.

calType - int special calendar type.

create - true if we should create it if non-existent.

Returns:

BwCalendar null for unknown calendar

Throws:

CalFacadeException

setPreferred

void setPreferred(BwCalendar val)
           throws CalFacadeException

set the default calendar for the current user.

Parameters:

val - BwCalendar

Throws:

CalFacadeException

getPreferred

String getPreferred(String entityType)
             throws CalFacadeException

Get the default calendar for the current user for the given entity type.

Parameters:

entityType -

Returns:

path or null for unknown calendar

Throws:

CalFacadeException

add

BwCalendar add(BwCalendar val,
               String parentPath)
        throws CalFacadeException

Add a calendar object

The new calendar object will be added to the db. If the indicated parent is null it will be added as a root level calendar.

Certain restrictions apply, mostly because of interoperability issues. A calendar cannot be added to another calendar which already contains entities, e.g. events etc.

Names cannot contain certain characters - (complete this)

Name must be unique at this level, i.e. all paths must be unique

Parameters:

val - BwCalendar new object

parentPath - String path to parent.

Returns:

BwCalendar object as added. Parameter val MUST be discarded

Throws:

CalFacadeException - on fatal error

rename

void rename(BwCalendar val,
            String newName)
     throws CalFacadeException

Change the name (path segment) of a calendar object.

Parameters:

val - BwCalendar object

newName - String name

Throws:

CalFacadeException - on fatal error

move

void move(BwCalendar val,
          BwCalendar newParent)
   throws CalFacadeException

Move a calendar object from one parent to another

Parameters:

val - BwCalendar object

newParent - BwCalendar potential parent

Throws:

CalFacadeException - on fatal error

update

void update(BwCalendar val)
     throws CalFacadeException

Update a calendar object

Parameters:

val - BwCalendar object

Throws:

CalFacadeException - on fatal error

delete

boolean delete(BwCalendar val,
               boolean emptyIt,
               boolean sendSchedulingMessage)
        throws CalFacadeException

Delete a calendar. Also remove it from the current user preferences (if any).

Parameters:

val - BwCalendar calendar

emptyIt - true to delete contents

sendSchedulingMessage - true if we should send cancels

Returns:

boolean true if it was deleted. false if it didn't exist

Throws:

CalFacadeException - for in use or marked as default calendar

isUserRoot

boolean isUserRoot(BwCalendar cal)
            throws CalFacadeException

Return true if cal != null and it represents a (local) user root

Parameters:

cal -

Returns:

boolean

Throws:

CalFacadeException

resolveAlias

BwCalendar resolveAlias(BwCalendar val,
                        boolean resolveSubAlias,
                        boolean freeBusy)
                 throws CalFacadeException

Attempt to get calendar referenced by the alias. For an internal alias the result will also be set in the aliasTarget property of the parameter.

Parameters:

val - the alias

resolveSubAlias - - if true and the alias points to an alias, resolve down to a non-alias.

freeBusy - to determine trequired access

Returns:

a BwCalendar object

Throws:

CalFacadeException

resolveAliasIdx

BwCalendar resolveAliasIdx(BwCalendar val,
                           boolean resolveSubAlias,
                           boolean freeBusy)
                    throws CalFacadeException

Attempt to get calendar referenced by the alias. For an internal alias the result will also be set in the aliasTarget property of the parameter.

This uses the index only. The returned object will not be a live hibernate object

Parameters:

val - the alias

resolveSubAlias - - if true and the alias points to an alias, resolve down to a non-alias.

freeBusy - to determine trequired access

Returns:

a BwCalendar object

Throws:

CalFacadeException

getAliasesInfo

AliasesInfo getAliasesInfo(String collectionHref,
                           String entityName)
                    throws CalFacadeException

Called to get information about aliases to a collection containing the named entity.

Parameters:

collectionHref - the collection

entityName - the entity

Returns:

the information

Throws:

CalFacadeException

getSynchStatus

CalendarsI.SynchStatusResponse getSynchStatus(String path)
                                       throws CalFacadeException

Parameters:

path - to collection

Returns:

never null - requestStatus set for not an external subscription.

Throws:

CalFacadeException

checkSubscription

CalendarsI.CheckSubscriptionResult checkSubscription(String path)
                                              throws CalFacadeException

Check the subscription if this is an external subscription. Will contact the synch server and check the validity. If there is no subscription onthe synch server will attempt to resubscribe.

Parameters:

path - to collection

Returns:

result of call

Throws:

CalFacadeException

getSyncToken

String getSyncToken(String path)
             throws CalFacadeException

Return the value to be used as the sync-token property for the given path. This is effectively the max sync-token of the collection and any child collections.

Parameters:

path - to collection

Returns:

a sync-token

Throws:

CalFacadeException

getCategorySet

Set<BwCategory> getCategorySet(String href)
                        throws CalFacadeException

Throws:

CalFacadeException

getSpecial

BwCalendar getSpecial(BwPrincipal owner,
                      int calType,
                      boolean create,
                      int access)
               throws CalFacadeException

Throws:

CalFacadeException