Package com.compoze.collab

This package provides the core classes for the Collaboration Framework.

See:
Description

Interface Summary

IAttachment	Represents an attachment to an item.
IAttachmentSource	Supplies data for adding an attachment.
IAttachmentSupport	Classes that implement this interface are items that are capable of having attachments added to and removed from them.
IContainer	An extension of IItem that implements a container that holds other items.
IItem	This class is the superclass of all containers and items in the Collaboration Services API.
IItemList	Represents a paginated slice of items from the backend store.
IMissingItem	The IMissingItem interface is used to represent items that were not found when requesting multiple IDs.
IProgress	This interface provides callbacks for reporting progress on time-consuming operations.
IProvider	Provides the abstract superclass for all collaboration service providers.
IRootContainer	This class implements a root container, which can be used to fetch any item or container in the hierarchy.
ISession	Provides a session to a collaboration service provider and an entry point to the Collaboration Framework.
IValue	This class stores a property value.

Class Summary

CollaborationManager	Maintains a registry of API providers and related information.
ContainerClass	Defines the class of a Container through an extension of ItemClass.
Enum	This class is the superclass of all enumerations in the API.
EnumElement	This class is an enumeration element.
FetchProfile	This class holds a list of keys to be retrieved from the server.
FileAttachmentSource	An IAttachmentSource that gets its data from a file.
InputStreamAttachmentSource	An IAttachmentSource that gets its data from an InputStream.
InvalidValue	A property value that is invalid.
ItemClass	Defines the class of an Item including its name, default keys, implementing Java class, containing item class and parent item class.
ItemComparator	Comparator for arbitrary properties on items.
ItemOperation	Defines an operation that can be performed on an item.
Key	A key for properties that are set on an item.
QueryProfile	Combines a Restriction, FetchProfile, Sort and depth to restrict what items and properties are retrieved and how the items are sorted.
Restriction	Restricts the items returned from a query.
RootContainerClass	Defines how to create a class of RootContainer instance.
Schema	Exposes information about a schema in the API.
SessionFactory	The SessionFactory class is used to construct session based on the creation parameters specified by a client.
SessionOption	Implements an option to a session property.
SessionProperty	This class represents a session property.
SessionPropertyElement	A superclass of classes used for the session properties.
Sort	Represents a list of fields to sort on, with the earlier properties having higher sort priority.
SortOrder	The element class for the SortOrderEnum enumeration.
SortOrderEnum	The enumeration class that contains SortOrder elements.
SortProperty	Represents a property to sort on and the order (ascending/descending)

Exception Summary

CollaborationException	Serves as the superclass of all exceptions thrown from the collaboration services API.
CollaborationRuntimeException	Serves as the superclass of all exceptions thrown from the collaboration services API.
ContainerAlreadyExistsException	Exception class that means that a container could not be created because a container with the same name already exists.
ContainerCycleException	Exception class that means that a container was copied or moved to a child of the source container.
ContainerNameException	Exception class that means that a container could not be created because the name specified for it is incompatible with the provider.
InvalidArgumentException	Exceptions of this class are thrown when a method argument has an invalid value.
InvalidStateException	Exceptions of this class are thrown when a method call or argument is invalid at the time it is called.
InvalidValueException	Exceptions of this class are thrown when a property value is invalid and the programmer attempts to access the value as a datatype with no logical support for values of type InvalidValue (anything but Object).
ItemNotFoundException	Exception class that means that an item that was requested was not found by the provider (it may not exist, or may have been externally deleted).
LicenseException	Exception class that's thrown when there was a problem with the Compoze license.
LoginException	This exception can be thrown when logging a user in to indicate that they specified some incorrect login parameters.
MoveSourceIsTargetException	Exception class that means that an item was moved to itself.
NullValueException	Exceptions of this class are thrown when a property value is null and the programmer attempts to access the value as a datatype with no logical support for null values (such as a primitive type).
OperationUnsupportedException	This exception is thrown by the API when an operation is not supported by the underlying provider.
PermissionException	Exceptions of this class represent permissions problems.
PropertyMissingException	Exception class that means that a property that was requested was not found by the provider (it may not exist, or may have been externally deleted).
ProviderException	Exceptions of this class are thrown by the provider with a provider specified message.
SessionTimeoutException	Exception class that means that the session timed out on the backend server.
StubBackendException	Exceptions of this class represent problems between a stub and a back-end server.
StubBindException	Exceptions of this class represent problems connecting to or communicating with a stub.
StubException	Exceptions of this class represent problems using a stub or back-end server.

Package com.compoze.collab Description

This package provides the core classes for the Collaboration Framework.

Quick Start

If you wish to get started quickly, you must first create a session. See the SessionFactory class for information on how to do this. Read on for more information about the API, what it does and what it contains.

API Scope

The Collaboration Framework offers a hybrid API usable for two main types of collaboration:

1. Message-centric collaboration- involves message transmission, storage and management and is commonly used in groupware systems such as Microsoft Exchange and Lotus Domino
2. Interaction-centric collaboration- focuses on conversational sessions among two or more individuals in real-time, examples including text based instant messaging and interactive whiteboard applications

The same abstract API is used for both types of collaboration, as both share many of the same required software patterns. Service providers provide implementations for different collaboration back-ends.

Collaboration API Functionality

The following table lists the abstract functionality and interfaces that exist in the API:

Functionality	Description	Classes
Providers	Providers supply the backend collaboration implementation.	IProvider
Sessions	The main entry point for the API. The programmer must open a session for a specific provider to start using the API.	ISession
Items	Items represent some entity in the collaboration system that contains properties. Examples of items include mail messages, appointments, instant messages and buddies in an IM buddy list.	IItem
Properties	Properties are key/value pairs of data stored on items.	Key IValue
Containers	Containers are a specialized type of item that holds items, creating a container/item hierarchy. What a container actually is is provider specific. Examples of containers include user mail folders and instant messaging buddy groups.	IContainer
Root Containers	Sessions have multiple trees of containers and items. Each tree begins at a single root container.	IRootContainer
Query Profiles	Query Profiles give a programmer the ability to retrieve a subset of items and containers that meet some specified constraints.	IContainer.getItems(QueryProfile), QueryProfile, Restriction, Sort, FetchProfile
Schemas	A schema is a defined set of item classes, container classes and the operations performed on those containers and items. Schemas may be extended. Extended schemas have all of the item classes and container classes of their parent and may add additional ones as well.	Schema

Containers and Items

The root of the hybrid between these two types of collaboration lies in the abstract concepts of containers, items and properties. Containers are a specialized type of item can hold other items. Properties are key/value pairs stored on items. Items, while concrete, typically represent different things based on the provider in use. For example, an item in a groupware provider could be an email message or an appointment while an item in an instant messaging provider could be an instant message.

Message-centric collaboration is typically done by accessing items (in this case messages) in a user's mail store and calling item specific methods to send messages, make meeting requests, assign tasks, etc. Interaction-centric collaboration involves getting and adding items to specialized containers and registering event handlers to be notified of item changes.

Schemas

The two main schemas are the groupware schema (in com.compoze.collab.groupware) and the instant messaging schema (in com.compoze.collab.im). They share a common super messaging schema (in com.compoze.collab.messaging). See the referenced package descriptions for more information on those schemas and what functionality they provide.

Logging

The API is delivered with a package of logging classes in com.compoze.collab.log. Unless you want to write to the Compoze log, you do not need to use this package. The Compoze API code will occasionally log important messages and can also be configured for tracing so that you can see provider specific interaction. You can set the log level with per-session granularity using ISession.setLogLevel(LogLevel).

The Session

The Collaboration Framework begins at the ISession. A session must be opened using a specified provider before any interaction with the API can occur. Please see the JavaDoc for the SessionFactory class, which is the factory class for creating instances of ISession.