Overview | Package | Class | Tree | Deprecated | Index | Help
| Compoze Software, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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, IGroupwareContainer, IGroupwareItem, IMailContainer, IMailMessage, IMailRecipient, IMeetingCancellation, IMeetingNotice, IMeetingNoticeAccepted, IMeetingNoticeDeclined, IMeetingNoticeTentative, IMeetingRequest, com.compoze.collab.messaging.IMessage, com.compoze.collab.messaging.IMessagingItem, IMissingItem, INonDeliveryReport, IReadReport, com.compoze.collab.messaging.IRecipient, IRootContainer, ITask, ITaskNotice, ITaskRequest, ITasksContainer, IWebdavCalendarContainer

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.
`CollabEnum` | `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.

  See Also:
    Constant Field Values

### KEYID_PARENT_ID

    public static final int KEYID_PARENT_ID

  The `int` ID for the `PARENT_ID` key.

  See Also:
    Constant Field Values

### KEYID_ITEM_CLASS

    public static final int KEYID_ITEM_CLASS

  The `int` ID for the `ITEM_CLASS` key.

  See Also:
    Constant Field Values

### 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 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

    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)`

Overview | Package | Class | Tree | Deprecated | Index | Help
| Compoze Software, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright ©1999-2003 Compoze Software, Inc. All rights reserved.