Package com.compoze.collab

This package provides the core classes for the BEA WebLogic Personal Messaging API.

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 Personal Messaging API.
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 BEA WebLogic Personal Messaging API.

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 Personal Messaging API 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.

Personal Messaging 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 log, you do not need to use this package. The API 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 Personal Messaging API 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 Personal Messaging 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.