com.compoze.collab
Interface IContainer

All Superinterfaces:

IItem, java.io.Serializable

All Known Subinterfaces:

IAddressBook, IAddressEntryContainer, ICalendarContainer, IContactsContainer, IExchangeCalendarContainer, IExchangeContactsContainer, IExchangeMailContainer, IExchangeTasksContainer, IFriendGroupContainer, IFriendsContainer, IGroupwareContainer, IImRootContainer, IMailContainer, IMapiAddressEntryContainer, IMapiCalendarContainer, IMessagesContainer, IRootContainer, ITasksContainer, IWebdavCalendarContainer

public interface IContainer

extends IItem, java.io.Serializable

An extension of IItem that implements a container that holds other items. Containers have a hierarchical relationship to one another. The IItem.getParent() call for a container returns the parent container that holds this container. Containers can sometimes not hold either items or subcontainers. If this is the case, either the HOLDS_SUBCONTAINERS or HOLDS_ITEMS properties (or both) will be false

Field Summary

static ContainerClass	CLASS The default type of container for collaboration services.
static Key	CONTAINER_CLASS Key that represents a container type.
static Key	HAS_SUBCONTAINERS Key that represents whether the container has subcontainers.
static Key	HOLDS_ITEMS Key that represents whether the container can hold items.
static Key	HOLDS_SUBCONTAINERS Key that represents whether the container can hold subcontainers.
static int	KEYID_CONTAINER_CLASS The int ID for the CONTAINER_CLASS key.
static int	KEYID_HAS_SUBCONTAINERS The int ID for the HAS_SUBCONTAINERS key.
static int	KEYID_HOLDS_ITEMS The int ID for the HOLDS_ITEMS key.
static int	KEYID_HOLDS_SUBCONTAINERS The int ID for the HOLDS_SUBCONTAINERS key.
static int	KEYID_NAME The int ID for the NAME key.
static int	KEYID_SUBCONTAINER_COUNT The int ID for the SUBCONTAINER_COUNT key.
static Key[]	MINIMUM_CONTAINER_KEYS The minimum required keys when fetching a container.
static Key	NAME Key that represents the name of a container.
static Key	SUBCONTAINER_COUNT Key that represents the number of subcontainers on this container.

Fields inherited from interface com.compoze.collab.IItem

ID, ITEM_CLASS, KEYID_ID, KEYID_ITEM_CLASS, KEYID_PARENT_ID, MINIMUM_ITEM_KEYS, PARENT_ID

Method Summary

IItem	add() Adds an item to a container.
IItem	add(boolean bCommit) Adds an item to a container that is of the default item class for the container.
IItem	add(ItemClass type, boolean bCommit) Adds an item of the specified type.
IContainer	addSubcontainer(java.lang.String sName) Adds a subcontainer with the given name to this container.
void	copyTo(IContainer container) Copies the container to another container.
ContainerClass	getContainerClass() Gets the container class for this container.
int	getItemCount() Gets the number of items in this container.
int	getItemCount(Restriction restriction) Gets the number of items in this container.
IItem[]	getItems() Gets all of the items in the container.
void	getItems(IProgress progress, boolean bCreateThread, QueryProfile queryProfile) Gets all of the items in the container matching the specified QueryProfile.
void	getItems(IProgress progress, boolean bCreateThread, QueryProfile queryProfile, int iPageSize, int iPage) Gets items in the container given a number of items per 'page' and a page number, with progress reporting.
IItem[]	getItems(QueryProfile queryProfile) Gets all of the items in the container matching the specified QueryProfile.
IItemList	getItems(QueryProfile queryProfile, int iPageSize, int iPage) Gets items in the container given a number of items per 'page' and a page number.
java.lang.String	getName() Gets the name of the container.
IContainer	getSubcontainer(java.lang.String sName) Gets a container with the specified name that is held inside this container.
IContainer	getSubcontainer(java.lang.String sName, FetchProfile fetchProfile) Gets a container with the specified name that is held inside this container.
IContainer[]	getSubcontainers() Gets the subcontainers in this container.
IContainer[]	getSubcontainers(QueryProfile queryProfile) Gets the subcontainers in this container.
boolean	hasSubcontainer(java.lang.String sName) Determines if this container has a subcontainer with the specified name.
boolean	holdsItems() Determines whether this container is capable of holding items.
boolean	holdsSubcontainers() Determines whether this container is capable of holding subcontainers.
boolean	isUnder(IContainer container) Gets whether a container is in the hierarchy of another container.
void	moveTo(IContainer container) Moves the container to another container.
void	setName(java.lang.String sName) Sets the name of the container.

Methods inherited from interface com.compoze.collab.IItem

commit, containsKey, containsKey, copyProperties, delete, fetchProperties, getAttribute, getEnum, getID, getInputStream, getItemClass, getOutputStream, getParent, getParent, getParentID, getProperties, getProperties, getProperties, getProperty, getProperty, getProperty, getReader, getRootContainer, getSession, getWriter, isMissing, removeAttribute, removeProperty, setAttribute, setProperties, setProperty, setProperty, setProperty

Field Detail

KEYID_CONTAINER_CLASS

public static final int KEYID_CONTAINER_CLASS

The int ID for the CONTAINER_CLASS key.

KEYID_NAME

public static final int KEYID_NAME

The int ID for the NAME key.

KEYID_SUBCONTAINER_COUNT

public static final int KEYID_SUBCONTAINER_COUNT

The int ID for the SUBCONTAINER_COUNT key.

KEYID_HAS_SUBCONTAINERS

public static final int KEYID_HAS_SUBCONTAINERS

The int ID for the HAS_SUBCONTAINERS key.

KEYID_HOLDS_ITEMS

public static final int KEYID_HOLDS_ITEMS

The int ID for the HOLDS_ITEMS key.

KEYID_HOLDS_SUBCONTAINERS

public static final int KEYID_HOLDS_SUBCONTAINERS

The int ID for the HOLDS_SUBCONTAINERS key.

CONTAINER_CLASS

public static final Key CONTAINER_CLASS

Key that represents a container type.

NAME

public static final Key NAME

Key that represents the name of a container. Containers can be renamed.

SUBCONTAINER_COUNT

public static final Key SUBCONTAINER_COUNT

Key that represents the number of subcontainers on this container.

HAS_SUBCONTAINERS

public static final Key HAS_SUBCONTAINERS

Key that represents whether the container has subcontainers.

HOLDS_ITEMS

public static final Key HOLDS_ITEMS

Key that represents whether the container can hold items.

HOLDS_SUBCONTAINERS

public static final Key HOLDS_SUBCONTAINERS

Key that represents whether the container can hold subcontainers.

MINIMUM_CONTAINER_KEYS

public static final Key[] MINIMUM_CONTAINER_KEYS

The minimum required keys when fetching a container.

CLASS

public static final ContainerClass CLASS

The default type of container for collaboration services.

Method Detail

add

public IItem add()
          throws CollaborationException

Adds an item to a container.

Returns:

the new item (not null and not saved in the store until the IItem.commit() method is called)

Throws:

OperationUnsupportedException - if the operation is not supported on this container (the value of HOLDS_ITEMS is false)

add

public IItem add(ItemClass type,
                 boolean bCommit)
          throws CollaborationException

Adds an item of the specified type. The actual item classes that may be used depends on what provider you're using and what container you're adding it to. The ItemClasses to pass in may be obtained from the interfaces of the item class itself, for example, IItem.ITEM_CLASS.

Parameters:

type - the type of item to add (not null)

bCommit - saves the type into the store

Returns:

the new item (not null)

Throws:

OperationUnsupportedException - if the operation is not supported on this container (the value of HOLDS_ITEMS is false)

add

public IItem add(boolean bCommit)
          throws CollaborationException

Adds an item to a container that is of the default item class for the container.

Parameters:

bCommit - saves the type into the store

Returns:

the new item (not null)

Throws:

OperationUnsupportedException - if the operation is not supported on this container (the value of HOLDS_ITEMS is false)

addSubcontainer

public IContainer addSubcontainer(java.lang.String sName)
                           throws CollaborationException

Adds a subcontainer with the given name to this container. The resulting subcontainer is of the same type as the container it is added under. If the parent container is a root container, then the child being added will be of type IContainer.CLASS.

Parameters:

sName - the container name (not null)

Returns:

the new container (not saved in the store until the IItem.commit() method is called)

Throws:

OperationUnsupportedException - if the operation is not supported on this container (the value of HOLDS_SUBCONTAINERS is false)

hasSubcontainer

public boolean hasSubcontainer(java.lang.String sName)
                        throws CollaborationException

Determines if this container has a subcontainer with the specified name.

Parameters:

sName - the name

Returns:

true if this container has a subcontainer with the specified name

Throws:

UnsupportedOperationException - if the getSubcontainer(String) operation is not supported on this container

getSubcontainer

public IContainer getSubcontainer(java.lang.String sName)
                           throws CollaborationException

Gets a container with the specified name that is held inside this container.

Parameters:

sName - the name

Returns:

the container (or null if no subcontainer with the specified name exists)

Throws:

UnsupportedOperationException - if the operation is not supported on this container

getSubcontainer

public IContainer getSubcontainer(java.lang.String sName,
                                  FetchProfile fetchProfile)
                           throws CollaborationException

Gets a container with the specified name that is held inside this container.

Parameters:

sName - the name

fetchProfile - the FetchProfile to use

Returns:

the container (or null if no subcontainer with the specified name exists)

Throws:

UnsupportedOperationException - if the operation is not supported on this container

getSubcontainers

public IContainer[] getSubcontainers()
                              throws CollaborationException

Gets the subcontainers in this container.

Returns:

the subcontainers (an empty array if there are no subcontainers, never null)

Throws:

UnsupportedOperationException - if the operation is not supported on this container

getSubcontainers

public IContainer[] getSubcontainers(QueryProfile queryProfile)
                              throws CollaborationException

Gets the subcontainers in this container.

Parameters:

queryProfile - the query profile to use when getting items

Returns:

the subcontainers (an empty array if there are no subcontainers, never null)

Throws:

UnsupportedOperationException - if the operation is not supported on this container

getName

public java.lang.String getName()

Gets the name of the container.

Returns:

the name

getItemCount

public int getItemCount()
                 throws CollaborationException

Gets the number of items in this container.

Returns:

the item count

Throws:

CollaborationException - if unable to perform the operation

getItemCount

public int getItemCount(Restriction restriction)
                 throws CollaborationException

Gets the number of items in this container.

Parameters:

restriction - the restriction for the item count (null for no restriction)

Returns:

the item count

Throws:

CollaborationException - if unable to perform the operation

getItems

public IItem[] getItems()
                 throws CollaborationException

Gets all of the items in the container.

Returns:

the items (empty array if there are no items, never null)

getItems

public IItem[] getItems(QueryProfile queryProfile)
                 throws CollaborationException

Gets all of the items in the container matching the specified QueryProfile.

Parameters:

queryProfile - the query profile to use when getting items

Returns:

the items (empty array if there are no items, never null)

getItems

public void getItems(IProgress progress,
                     boolean bCreateThread,
                     QueryProfile queryProfile)

Gets all of the items in the container matching the specified QueryProfile. If bCreateThread is true, this method will return immediately and a separate thread will be spawned to do the work and report the progress. The argument to progress.setResults will be an IItem[].

Parameters:

progress - an IProgress instance to receive progress reports and the results

bCreateThread - if true, create a new thread to do the work

queryProfile - the query profile to use when getting items; do not re-use until IProgress.setResults(Object) has been called

getItems

public IItemList getItems(QueryProfile queryProfile,
                          int iPageSize,
                          int iPage)
                   throws CollaborationException

Gets items in the container given a number of items per 'page' and a page number. This method can potentially overwrite the start index and length value provided in QueryProfile.

Parameters:

queryProfile - the query profile to use when getting items

iPageSize - the count of items that makes a 'page' (<=0 for all)

iPage - the page number to fetch (must be >=1)

Returns:

the items

getItems

public void getItems(IProgress progress,
                     boolean bCreateThread,
                     QueryProfile queryProfile,
                     int iPageSize,
                     int iPage)

Gets items in the container given a number of items per 'page' and a page number, with progress reporting. This method can potentially overwrite the start index and length value provided in QueryProfile. If bCreateThread is true, this method will return immediately and a separate thread will be spawned to do the work and report the progress. The argument to progress.setResults will be an IItemList.

Parameters:

progress - an IProgress instance to receive progress reports and the results

bCreateThread - if true, create a new thread to do the work

queryProfile - the query profile to use when getting items; do not re-use until IProgress.setResults(Object) has been called

iPageSize - the count of items that makes a 'page' (<=0 for all)

iPage - the page number to fetch (must be >=1)

getContainerClass

public ContainerClass getContainerClass()

Gets the container class for this container.

Returns:

this container's container class (not null)

See Also:

CONTAINER_CLASS

moveTo

public void moveTo(IContainer container)
            throws CollaborationException

Moves the container to another container. A container may not be moved into one of its children.

Specified by:

moveTo in interface IItem

Parameters:

container - the destination container

Throws:

CollaborationException - if there was a problem moving this item to a container.

copyTo

public void copyTo(IContainer container)
            throws CollaborationException

Copies the container to another container. Does a deep copy of everything in the container. A container may not be copied into one of its children.

Specified by:

copyTo in interface IItem

Parameters:

container - the destination container

Throws:

CollaborationException - if there was a problem copying this item to a container.

isUnder

public boolean isUnder(IContainer container)
                throws CollaborationException

Gets whether a container is in the hierarchy of another container.

Parameters:

container - the container to check

Returns:

true if the current container is a child of the specified one

Throws:

CollaborationException - if there was an error checking the relationship

holdsSubcontainers

public boolean holdsSubcontainers()
                           throws CollaborationException

Determines whether this container is capable of holding subcontainers. If a container is not capable of holding subcontainers, all of the subcontainer retrievel and count methods will return no containers. Calls to addSubcontainer(String) will fail with an exception.

Returns:

true if this container is capable of holding subcontainers, false if not

Throws:

CollaborationException - if there was an error retrieving the property (should not happen)

See Also:

HOLDS_SUBCONTAINERS, addSubcontainer(String)

holdsItems

public boolean holdsItems()
                   throws CollaborationException

Determines whether this container is capable of holding items. If a container is not capable of holding items, all of the item retrieval and count methods will return no items. Calls to add(), add(boolean) and add(ItemClass, boolean) will fail with an exception.

Returns:

true if this container is capable of holding items, false if not

Throws:

CollaborationException - if there was an error retrieving the property (should not happen)

See Also:

HOLDS_ITEMS, add(), add(boolean), add(ItemClass, boolean)

setName

public void setName(java.lang.String sName)
             throws CollaborationException

Sets the name of the container.

Parameters:

sName - the name (not null)

Throws:

CollaborationException - if there was an error setting the name