Overview | Package | Class | Tree | Deprecated | Index | Help
| Compoze Software, Inc.
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## 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
CollabEnum | This class is the superclass of all enumerations in the API.
CollaborationManager | Maintains a registry of API providers and related information.
ContainerClass | Defines the class of a `Container` through an extension of `ItemClass`.
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`.

### Caching

#### Introduction

The Compoze Collaboration Services API includes the ability to cache the results of read-only method calls at the stub level. Providers optionally implement cache dependency checks to determine quickly if the cache needs to be updated with new results. With caching enabled, it is possible for applications to display the results of post-initial, read-only queries with little or no back-end processing time.

#### Checked and Unchecked Caching

Both checked and unchecked caching are supported by the SPI. With checked caching, dependency information is obtained from the backend server to determine if a query needs to be re-performed. With unchecked caching, cached results may be used for some time period without re-querying the back-end server at all to determine if those results are up to date. Checked caching will always result in queries that are up to date, whereas the results when unchecked caching is enabled may be stale. Checked and unchecked caching may be used in combination.

#### Dependency Checks

It is up to the provider to determine when dependency checks need to be performed and to what granularity. For example, dependency checks may occur at the level of the root container, causing any changes anywhere in the root container to invalidate all queries in the cache. Alternatively, they may occur at the container level, isolating cached query invalidation to modifications made within a given container. The `collab.xml` file contains a cache element in each provider definition that indicates whether or not the provider supports dependency checks. If a provider does not support dependency checks, then only unchecked caching is possible, as indicated by the following table:

Provider Supports Dependency Checks | Checked Caching Supported | Unchecked Caching Supported
No | No | Yes
Yes | Yes | Yes

#### Cache Purge Policy

When the determination is made that the cache for a given session has reached its maximum size, cache results are purged. The cache purge policy is to first purge entries that have been referenced the fewest number of times, and to second purge entries that are the least recently used.

#### Explicit Cache Invalidation

The method `ISession.invalidateCache()` may be used to explicitly purge any cache entries associated with a session. This is particularly useful when using unchecked caching and the application requires a way to purge all cache entries and retrieve the latest results from the backend.

#### Provider Cache Support

The following table details the cache support in each provider:

Provider | Dependency Check Granularity | Details
Domino | Root container level | The Notes C API function `NSFDbModifiedTime` is used to check the last modified time of the database. `NSFDbOpenExtended` is used when opening the database such that it is never even opened if it was not modified after the dependency time.
Exchange/MAPI | Container level | Currently unimplemented. Plans are to use `PR_LOCAL_COMMIT_TIME_MAX` for container level dependency checks.
Exchange/WebDAV | None | Due to the dependency check penalty (all dependency checks would be a separate, expensive query) only unchecked caching is possible.
Live Communications Server | None | Caching of limited use for IM
Sametime | None | Caching of limited use for IM
Yahoo | None | Caching of limited use for IM

Overview | Package | Class | Tree | Deprecated | Index | Help
| Compoze Software, Inc.
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

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