com.compoze.collab
Interface IItem

All Superinterfaces:

java.io.Serializable

All Known Subinterfaces:

IAddressBook, IAddressEntry, IAddressEntryContainer, IAppointment, IAttachment, ICalendarContainer, ICalendarItem, IContact, IContactsContainer, IContainer, IDeliveryReport, IEmbeddedAttachment, IExchangeAddressEntry, IExchangeAppointment, IExchangeCalendarContainer, IExchangeCalendarItem, IExchangeContact, IExchangeContactsContainer, IExchangeMailContainer, IExchangeMessage, IExchangeNonDeliveryReport, IExchangeReadReport, IExchangeTask, IExchangeTasksContainer, IFriend, IFriendGroupContainer, IFriendsContainer, IGroupwareContainer, IGroupwareItem, IImRootContainer, IInstantMessage, ILcsFriend, IMailContainer, IMailMessage, IMailRecipient, IMapiAddressEntryContainer, IMapiAppointment, IMapiCalendarContainer, IMapiTask, IMapiTaskRequest, IMeetingCancellation, IMeetingNotice, IMeetingNoticeAccepted, IMeetingNoticeDeclined, IMeetingNoticeTentative, IMeetingRequest, IMessage, IMessagesContainer, IMessagingItem, IMissingItem, INonDeliveryReport, IReadReport, IRecipient, IRootContainer, ISametimeFriend, ITask, ITaskNotice, ITaskRequest, ITasksContainer, IWebdavCalendarContainer, IYahooFriend

public interface IItem

extends java.io.Serializable

This class is the superclass of all containers and items in the Collaboration Services API.

Field Summary

static ItemClass	CLASS The item class of IItem.
static Key	ID Key that represents the item ID.
static Key	ITEM_CLASS Key that represents the item type.
static int	KEYID_ID The int ID for the ID key.
static int	KEYID_ITEM_CLASS The int ID for the ITEM_CLASS key.
static int	KEYID_PARENT_ID The int ID for the PARENT_ID key.
static Key[]	MINIMUM_ITEM_KEYS The minimum required keys when fetching an item.
static Key	PARENT_ID Key that represents the id of the parent item.

Method Summary

void	commit() Commits any changed or removed properties on the item to the backend server.
boolean	containsKey(Key key) Determines if the item contains a particular property.
boolean	containsKey(Key key, boolean bAutoFetch) Determines if the item contains a particular property.
void	copyProperties(Key[] props, Key[] excludedProps, boolean bOverwrite, IItem target) Copy the keys specified from this item to the specified item.
void	copyTo(IContainer container) Copies the item to another container.
void	delete() Deletes the item from the backend.
IValue[]	fetchProperties(FetchProfile profile) Fetch unfetched properties for this item from the server into this item.
java.lang.Object	getAttribute(java.lang.String sKey) Returns a value that was set on this item for the given key.
Enum	getEnum(Key key) Gets the enumeration for the specified key.
java.lang.String	getID() Gets the ID of the item.
java.io.InputStream	getInputStream(Key key) Get a InputStream for reading the contents of a Key.VALUE_BINARY type Key.
ItemClass	getItemClass() Gets the item class for this item.
java.io.OutputStream	getOutputStream(Key key, int iLength) Get a OutputStream for outputting the value of a Key.VALUE_BINARY type Key.
IItem	getParent() Gets the parent of the item, fetching its minimum properties.
IItem	getParent(FetchProfile profile) Gets the parent of the item.
java.lang.String	getParentID() Gets the ID for the parent of the item.
IValue[]	getProperties() Gets all of the properties on the item that have already been retrieved.
IValue[]	getProperties(Key[] keys) Gets the properties on the item for the given set of keys.
IValue[]	getProperties(Key[] keys, boolean bAutoFetch) Gets the properties on the item for the given set of keys.
IValue	getProperty(Key key) Gets a property on the item.
IValue	getProperty(Key key, boolean bNonexistenceException) Gets a property on the item.
IValue	getProperty(Key key, boolean bNonexistenceException, boolean bAutoFetch) Gets a property on the item.
java.io.Reader	getReader(Key key) Get a Reader for reading the contents of a Key.VALUE_STRING type Key.
IRootContainer	getRootContainer() Returns the root container this item is under.
ISession	getSession() Gets the session that the item is associated with.
java.io.Writer	getWriter(Key key, int iLength) Get a Writer for writing the value of a Key.VALUE_STRING type Key.
boolean	isMissing() Gets whether the current item was not found when requested by its ID during a batch search for items.
void	moveTo(IContainer container) Moves the item to another container.
java.lang.Object	removeAttribute(java.lang.String sKey) Remove the value for the given key from this item.
IValue	removeProperty(Key key) Removes the specified property from the item.
void	setAttribute(java.lang.String sKey, java.lang.Object value) Set a value on this item that will not be saved when the item is committed.
void	setProperties(Key[] keys, java.lang.Object[] values) Sets properties on an item (changes are not saved until commit is called).
void	setProperty(Key key, boolean bValue) Sets a property on the item to a boolean value (changes are not saved until commit is called).
void	setProperty(Key key, int iValue) Sets a property on the item to an int value (changes are not saved until commit is called).
void	setProperty(Key key, java.lang.Object value) Sets a property on the item (changes are not saved until commit is called).

Field Detail

KEYID_ID

public static final int KEYID_ID

The int ID for the ID key.

KEYID_PARENT_ID

public static final int KEYID_PARENT_ID

The int ID for the PARENT_ID key.

KEYID_ITEM_CLASS

public static final int KEYID_ITEM_CLASS

The int ID for the ITEM_CLASS key.

ID

public static final Key ID

Key that represents the item ID.

PARENT_ID

public static final Key PARENT_ID

Key that represents the id of the parent item.

ITEM_CLASS

public static final Key ITEM_CLASS

Key that represents the item type.

MINIMUM_ITEM_KEYS

public static final Key[] MINIMUM_ITEM_KEYS

The minimum required keys when fetching an item.

CLASS

public static final ItemClass CLASS

The item class of IItem.

Method Detail

containsKey

public boolean containsKey(Key key)
                    throws CollaborationException

Determines if the item contains a particular property.

Parameters:

key - the key to check

Returns:

true if there is a property with the specified key, false if not or if the key has not been retrieved

Throws:

CollaborationException - if there was a problem looking up the key for inclusion.

containsKey

public boolean containsKey(Key key,
                           boolean bAutoFetch)
                    throws CollaborationException

Determines if the item contains a particular property.

Parameters:

key - the key to check

bAutoFetch - if true, fetch the property from the server if it has not already been retrieved

Returns:

true if there is a property with the specified key, false if not or if the key has not been retrieved

Throws:

CollaborationException - if there was a problem retrieving the property with the specified key

setProperties

public void setProperties(Key[] keys,
                          java.lang.Object[] values)
                   throws CollaborationException

Sets properties on an item (changes are not saved until commit is called).

Parameters:

keys - the keys for the properties (not null)

values - the values for the properties (not null, and in the same order as the keys)

Throws:

CollaborationException - if there was a problem setting the value to the specified key (possible nested exceptions include: RuntimeException, ParseException)

setProperty

public void setProperty(Key key,
                        java.lang.Object value)
                 throws CollaborationException

Sets a property on the item (changes are not saved until commit is called).

Parameters:

key - the property key (must not be null)

value - the value (must be able to coerce the specified object to the final type specified by the key)

Throws:

CollaborationException - if there was a problem setting the value to the specified key (possible nested exceptions include: RuntimeException, ParseException)

setProperty

public void setProperty(Key key,
                        int iValue)
                 throws CollaborationException

Sets a property on the item to an int value (changes are not saved until commit is called).

Parameters:

key - the property key (must not be null)

iValue - the value (must be able to coerce the corresponding Integer to the final type specified by the key)

Throws:

CollaborationException - if there was a problem setting the value to the specified key (possible nested exceptions include: RuntimeException, ParseException)

setProperty

public void setProperty(Key key,
                        boolean bValue)
                 throws CollaborationException

Sets a property on the item to a boolean value (changes are not saved until commit is called).

Parameters:

key - the property key (must not be null)

bValue - the value (must be able to coerce the corresponding Boolean to the final type specified by the key)

Throws:

CollaborationException - if there was a problem setting the value to the specified key (possible nested exceptions include: RuntimeException, ParseException)

getProperty

public IValue getProperty(Key key)
                   throws CollaborationException

Gets a property on the item. Based on the setting of Session.PROP_AUTO_FETCH, this method may query the server to get the specified property if it has not already been retrieved.

Parameters:

key - the property key (must not be null)

Returns:

the value (or null if there is no value on the item with the specified key)

Throws:

CollaborationException - if there was a problem retrieving the property

getProperty

public IValue getProperty(Key key,
                          boolean bNonexistenceException)
                   throws CollaborationException

Gets a property on the item. If bAutoFetch is true, retrieve the property from the server if it has not been retrieved already. If key is a default property and it needs to be retrieved, then all default properties will be retrieved at the same time.

Parameters:

key - the property key (must not be null)

bNonexistenceException - if true, throw an exception rather than returning null when the property does not exist and could not be fetch if bAutoFetch is specified

Returns:

the value (null if there is no value on the item with the specified key and bNonexistenceException was false)

Throws:

CollaborationException - if there was a problem retrieving the property, or if the property does not exist and bNonexistenceException was specified as true

getProperty

public IValue getProperty(Key key,
                          boolean bNonexistenceException,
                          boolean bAutoFetch)
                   throws CollaborationException

Gets a property on the item. If bAutoFetch is true, retrieve the property from the server if it has not been retrieved already. If key is a default property and it needs to be retrieved, then all default properties will be retrieved at the same time.

Parameters:

key - the property key (must not be null)

bNonexistenceException - if true, throw an exception rather than returning null when the property does not exist and could not be fetch if bAutoFetch is specified

bAutoFetch - if true, fetch the property from the server if it has not already been retrieved

Returns:

the value (null if there is no value on the item with the specified key and bNonexistenceException was false)

Throws:

CollaborationException - if there was a problem retrieving the property, or if the property does not exist and bNonexistenceException was specified as true

removeProperty

public IValue removeProperty(Key key)
                      throws CollaborationException

Removes the specified property from the item. This method adds the property to a remove list and removes it from the server when the item is committed, even if the property was not retrieved in the item to begin with.

Parameters:

key - the key to remove

Returns:

the old value, or null if the key did not exist or was not retrieved

Throws:

CollaborationException - if the Key is read only or IContainer.NAME

getProperties

public IValue[] getProperties()

Gets all of the properties on the item that have already been retrieved.

Returns:

the properties on the item

getProperties

public IValue[] getProperties(Key[] keys)
                       throws CollaborationException

Gets the properties on the item for the given set of keys. Depending on the setting of the Session.AUTO_FETCH property, this method may hit the server to retrieve additional properties.

Parameters:

keys - the keys to retrieve values for on this item (not null)

Returns:

the properties on the item

Throws:

CollaborationException - if any of the properties could not retrieved

fetchProperties

public IValue[] fetchProperties(FetchProfile profile)
                         throws CollaborationException

Fetch unfetched properties for this item from the server into this item. Returns an array containing the values fetched, which can safely be ignored, as the values will be accessible through getProperty(Key).

Parameters:

profile - the additional properties to fetch (not null)

Returns:

the values that were actually fetched. If none were fetched, returns Value[0].

Throws:

CollaborationException - if any of the properties could not be fetched

getProperties

public IValue[] getProperties(Key[] keys,
                              boolean bAutoFetch)
                       throws CollaborationException

Gets the properties on the item for the given set of keys.

Parameters:

keys - the keys to retrieve values for on this item (not null)

bAutoFetch - if true, get the properties from the server that have not already been retrieved

Returns:

the properties on the item (values in the same order as the keys that were specified)

Throws:

CollaborationException - if any of the properties could not be retrieved

commit

public void commit()
            throws CollaborationException

Commits any changed or removed properties on the item to the backend server. Note: If the item is a container, does not committed uncommitted items in the container.

Throws:

CollaborationException - if there was a problem committing the item to the backend

copyProperties

public void copyProperties(Key[] props,
                           Key[] excludedProps,
                           boolean bOverwrite,
                           IItem target)
                    throws CollaborationException

Copy the keys specified from this item to the specified item.

Parameters:

props - the keys to copy from this item (null means to copy all items)

excludedProps - the keys not to copy if copying all items (null means exclude nothing)

bOverwrite - if set to true, overwrite the keys in the target

target - the target item to copy to

Throws:

CollaborationException - if there was a problem copying items to the target

delete

public void delete()
            throws CollaborationException

Deletes the item from the backend. This method implies an immediate commit, and once it has been called the item may no longer be used.

Throws:

CollaborationException - if there was a problem removing this item from the backend

getID

public java.lang.String getID()

Gets the ID of the item.

Returns:

the ID (or null if this item has not yet been committed)

See Also:

ID

getItemClass

public ItemClass getItemClass()

Gets the item class for this item.

Returns:

this item's item class (not null)

See Also:

ITEM_CLASS

getSession

public ISession getSession()

Gets the session that the item is associated with.

Returns:

the session (not null)

getRootContainer

public IRootContainer getRootContainer()

Returns the root container this item is under.

Returns:

the root container this item is under (not null)

getParent

public IItem getParent()
                throws CollaborationException

Gets the parent of the item, fetching its minimum properties.

Returns:

the parent item (or null if this item is the root container)

Throws:

CollaborationException - if there was a problem retrieving the parent

getParentID

public java.lang.String getParentID()

Gets the ID for the parent of the item.

Returns:

the parent item ID (or null if this item has no parent, for example if it is the root container)

getParent

public IItem getParent(FetchProfile profile)
                throws CollaborationException

Gets the parent of the item. Each item class can have a different kind of parent depending on what it is. For a standard item, its parent is the container that it's in. For a standard container, its parent is the container that it's in, or the root container if it's a top level container. The parent of the root container is null.

Parameters:

profile - the profile to use that defines the keys (not null)

Returns:

the parent container (or null if this item is the root container)

Throws:

CollaborationException - if there was a problem retrieving the parent

See Also:

PARENT_ID

moveTo

public void moveTo(IContainer container)
            throws MoveSourceIsTargetException,
                   CollaborationException

Moves the item to another container.

Parameters:

container - the destination container

Throws:

ContainerCycleException - if the item being moved is a container and an attempt was made to move it to a child of the source container (if this exception is thrown, some of the operation may have completed)

MoveSourceIsTargetException - if the item is moved to its own container

ContainerAlreadyExistsException - if the item being moved is a container and a container with the same name already exists in the destination container

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

copyTo

public void copyTo(IContainer container)
            throws CollaborationException

Copies the item to another container.

Parameters:

container - the destination container

Throws:

ContainerCycleException - if the item being copied is a container and an attempt was made to copy it to a child of the source container (if this exception is thrown, some of the operation may have completed)

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

setAttribute

public void setAttribute(java.lang.String sKey,
                         java.lang.Object value)

Set a value on this item that will not be saved when the item is committed. This can be used for setting properties on items that are not to be persisted to the backend.

Parameters:

sKey - the key to store the value for

value - the value to place in memory for this item

getAttribute

public java.lang.Object getAttribute(java.lang.String sKey)

Returns a value that was set on this item for the given key. These values are not persisted when the item is committed.

Parameters:

sKey - the key used to store the value on this item

Returns:

the value stored or null if no value is found for the given key

getEnum

public Enum getEnum(Key key)
             throws CollaborationException

Gets the enumeration for the specified key. Providers may return different enumerations for a specified key.

Parameters:

key - the key (not null)

Returns:

the enumeration (or null if there is no defined enumeration for the specified key)

Throws:

InvalidArgumentException - if the specified key is not for an enumeration CollaborationException if there was a problem resolving the key with the provider

removeAttribute

public java.lang.Object removeAttribute(java.lang.String sKey)

Remove the value for the given key from this item. These values are not persisted when the item is committed.

Parameters:

sKey - the key (must not be null)

Returns:

the attribute that was removed, or null if there was no attribute with the specified key

getReader

public java.io.Reader getReader(Key key)
                         throws CollaborationException

Get a Reader for reading the contents of a Key.VALUE_STRING type Key. Reader.close() must be called on the returned Reader after reading is finished.

Parameters:

key - the key to get a reader for

Returns:

a Reader to read the key's value; null if this item does not have that value

Throws:

CollaborationException - if unable to create the Reader

InvalidArgumentException - if key is not for a String value

getWriter

public java.io.Writer getWriter(Key key,
                                int iLength)
                         throws CollaborationException

Get a Writer for writing the value of a Key.VALUE_STRING type Key. Any existing value will be overwritten. Writer.close() must be called on the returned Writer after writing is finished.

Parameters:

key - the key to get a writer for

iLength - the exact number of characters to be written; -1 if not known

Returns:

a Writer to write the key's value

Throws:

CollaborationException - if unable to create the Writer

InvalidArgumentException - if key is not for a String value

getInputStream

public java.io.InputStream getInputStream(Key key)
                                   throws CollaborationException

Get a InputStream for reading the contents of a Key.VALUE_BINARY type Key. InputStream.close() must be called on the returned InputStream after input is finished.

Parameters:

key - the key to get an InputStream for

Returns:

an InputStream to input the key's value; null if this item does not have that value

Throws:

CollaborationException - if unable to create the InputStream

InvalidArgumentException - if key is not for a binary value

getOutputStream

public java.io.OutputStream getOutputStream(Key key,
                                            int iLength)
                                     throws CollaborationException

Get a OutputStream for outputting the value of a Key.VALUE_BINARY type Key. Any existing value will be overwritten. OutputStream.close() must be called on the returned OutputStream after output is finished.

Parameters:

key - the key to get an OutputStream for

iLength - the exact number of bytes to be written; -1 if unknown

Returns:

an OutputStream to output the key's value

Throws:

CollaborationException - if unable to create the OutputStream

InvalidArgumentException - if key is not for a String value

isMissing

public boolean isMissing()

Gets whether the current item was not found when requested by its ID during a batch search for items. Items that were not found during batch requests will be of the type IMissingItem.

Returns:

true if this item wasn't found when requested with other items by their IDs, false otherwise.

See Also:

IRootContainer.getItemsByID(String[], FetchProfile)