com.compoze.collab
Interface IItem

All Superinterfaces

Serializable

All Known Subinterfaces:

IAddressBook, IAddressEntry, IAddressEntryContainer, IAppointment, IAttachment, ICalendarContainer, ICalendarItem, ICmAppointment, ICmCalendarContainer, ICmForum, ICmForumCategory, ICmForumRootContainer, ICmMailContainer, ICmMailDefaultContainer, ICmMailMessage, ICmTask, ICmTopic, IContact, IContactsContainer, IContainer, IEmbeddedAttachment, IGroupwareContainer, IGroupwareItem, IMailContainer, IMailMessage, IMailRecipient, IMessage, IMessagingItem, IMissingItem, INonDeliveryReport, IReadReport, IRecipient, IRootContainer, ITask, ITasksContainer

public interface IItem
extends 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.
Object	getAttribute(String sKey) Returns a value that was set on this item for the given key.
CollabEnum	getEnum(Key key) Gets the enumeration for the specified key.
String	getID() Gets the ID of the item.
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.
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.
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.
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.
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.
Object	removeAttribute(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(String sKey, Object value) Set a value on this item that will not be saved when the item is committed.
void	setProperties(Key[] keys, 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, Object value) Sets a property on the item (changes are not saved until commit is called).

Field Detail

KEYID_ID

static final int KEYID_ID

The int ID for the ID key.

See Also

Constants Summary

KEYID_PARENT_ID

static final int KEYID_PARENT_ID

The int ID for the PARENT_ID key.

See Also

Constants Summary

KEYID_ITEM_CLASS

static final int KEYID_ITEM_CLASS

The int ID for the ITEM_CLASS key.

See Also

Constants Summary

ID

static final Key ID

Key that represents the item ID.

PARENT_ID

static final Key PARENT_ID

Key that represents the id of the parent item.

ITEM_CLASS

static final Key ITEM_CLASS

Key that represents the item type.

MINIMUM_ITEM_KEYS

static final Key[] MINIMUM_ITEM_KEYS

The minimum required keys when fetching an item.

CLASS

static final ItemClass CLASS

The item class of IItem.

Method Detail

containsKey

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

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

void setProperties(Key[] keys,
                   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

void setProperty(Key key,
                 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

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

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

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

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

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

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

IValue[] getProperties()

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

Returns

the properties on the item

getProperties

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

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

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

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

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

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

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

ItemClass getItemClass()

Gets the item class for this item.

Returns

this item's item class (not null)

See Also

ITEM_CLASS

getSession

ISession getSession()

Gets the session that the item is associated with.

Returns

the session (not null)

getRootContainer

IRootContainer getRootContainer()

Returns the root container this item is under.

Returns

the root container this item is under (not null)

getParent

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

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

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

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

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

void setAttribute(String sKey,
                  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

Object getAttribute(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

CollabEnum 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

CollaborationException

removeAttribute

Object removeAttribute(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

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

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

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

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

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)