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

## Package com.compoze.collab.im

This package provides the classes for the instant messaging schema.

See:
Description

Interface Summary
IFriend | Provides the interface to the `Friend` item.
IFriendGroupContainer | Container class that holds a group of IM friends (as opposed to the top level `IFriendsContainer`, which holds all friends and groups).
IFriendsContainer | Container class that holds IM friends.
IImListener | Classes that implement this interface can listen for instant messaging events.
IImRootContainer | Container class for the IM root container.
IImSession | Extends the collab `ISession` with additional instant messaging specific functionality.
IInstantMessage | Provides the interface to the instant message item.
IMessagesContainer | Container class that holds instant messages.

Class Summary
FriendStatus | The element class for the `FriendStatusEnum` enumeration.
FriendStatusEnum | The enumeration class that contains `FriendStatus` elements.
ImEvent | This class is used to notify listeners on a container that some changed has occurred in the container.
QueueEventListener | This class implements an event listener that stores events internally until they are retrieved.
QueueImEventListener | An event listener that queues IM events.

## Package com.compoze.collab.im Description

This package provides the classes for the instant messaging schema.

Before understanding how this API is used you must first understand the Collaboration Framework in general. See the package description of the com.compoze.collab package for more information on this.

Access to instant messaging is provided through special in-memory containers and items held in a single, fixed root container. Starting at the root of the container tree, there is a `Friends` container and a `Messages` container, as follows:

The `Friends` container holds `Friend` items, one per friend. Friends may be a part of multiple friend groups at the same time, so this layout gives the ability to access the full friends list or lists of friends by group. Underneath the `Friends` container is a container for each friend group. Getting a list of items in one of these friend group subcontainers returns only the friends in that group. The `Friend` items that are returned in the friend group subcontainers may not be the same exact instances as the ones in the `Friends` container itself and as such must be compared for equality using the `equals` method.

The `Messages` container both holds incoming instant messages and provides the ability to create outgoing messages.

Creating a new message

        // let's get the Messages container from root
        IContainer messagesContainer = rootContainer.getSubcontainer("Messages");

        // create a new instant message
        IInstantMessage message = (IInstantMessage) messagesContainer.add();

Getting all messages from the Messages container

        IContainer messagesContainer = rootContainer.getSubcontainer("Messages");
        IItem[] messages = messagesContainer.getItems();

        for (int i = 0; i < messages.length; ++i)
            {
            IInstantMessage message = (IInstantMessage) messages[i];
            // handle the message
            }

Applications that use the IM API are likely to fall into two types: polling and realtime. Polling applications require the API to queue incoming events and messages. Realtime applications require immediate notification of events and messages as they arrive. Either method may be used with the API, and they may be used at the same time if a hybrid is required.

Provider statuses
Yahoo | LCS | Sametime | CollabEnum value
|  | Active | `SametimeFriendStatusEnum.ACTIVE`
|  | Idle | `SametimeFriendStatusEnum.IDLE`
|  | Do Not Disturb | `SametimeFriendStatusEnum.DO_NOT_DISTURB`
| Active |  | `LcsFriendStatusEnum.ACTIVE`
| Temporary Unavailable |  | `LcsFriendStatusEnum.TEMPORARY_UNAVAILABLE`
| In Call |  | `LcsFriendStatusEnum.IN_CALL`
| At Lunch |  | `LcsFriendStatusEnum.AT_LUNCH`
| Away |  | `LcsFriendStatusEnum.AWAY`
Available |  |  | `YahooFriendStatusEnum.AVAILABLE`
Be Right Back |  |  | `YahooFriendStatusEnum.BE_RIGHT_BACK`
Busy |  |  | `YahooFriendStatusEnum.BUSY`
Not at Home |  |  | `YahooFriendStatusEnum.NOT_AT_HOME`
Not at Desk |  |  | `YahooFriendStatusEnum.NOT_AT_DESK`
Not in Office |  |  | `YahooFriendStatusEnum.NOT_IN_OFFICE`
On Phone |  |  | `YahooFriendStatusEnum.ON_PHONE`
On Vacation |  |  | `YahooFriendStatusEnum.ON_VACATION`
Out to Lunch |  |  | `YahooFriendStatusEnum.OUT_TO_LUNCH`
Stepped Out |  |  | `YahooFriendStatusEnum.STEPPED_OUT`
Invisible |  |  | `YahooFriendStatusEnum.INVISIBLE`
Bad |  |  | `YahooFriendStatusEnum.BAD`
Locked |  |  | `YahooFriendStatusEnum.LOCKED`
Typing |  |  | `YahooFriendStatusEnum.TYPING`
Custom |  |  | `YahooFriendStatusEnum.CUSTOM`
Idle |  |  | `YahooFriendStatusEnum.IDLE`
Offline | Offline | Offline | `FriendStatusEnum.OFFLINE`

The following table lists common tasks that need to be performed and what needs to be done to accomplish them:
Open a session
Call `SessionFactory.createSession(Map)`, specifying the name of the provider as the value for the `PROP_PROVIDER` session property (such as `yahoo`) and specifying properties documented in provider implementation packages. The resulting session may be cast to an `IImSession`. Before opening the session, you may set your initial presence status (see Set presence status). Open a session

        // first we must set all the properties the provider will use to connect to LCS
        Map props = new HashMap();

        props.put(ISession.PROP_PROVIDER, " -- provider name here -- ");

        props.put(IImSession.PROP_IM_USERNAME, " -- provider specific user name here --");
        props.put(IImSession.PROP_IM_PASSWORD, " -- provider specific password here -- ");

        // <b>DO NOT forget to specify additional provider specific properties</b>

        // get the factory to create appropriate session
        IImSession session = (IImSession) SessionFactory.createSession(props);

        // now we can log in
        session.login();

Send an instant message
Add an item to the `Messages` container off of the root container. You will receive an instance of `IInstantMessage`, on which you can then call `IMessage.addRecipient(String)`, `IMessagingItem.setBody(String)`, `IMessage.send()`. Sending a message

        // get the messages container
        IContainer messagesContainer = rootContainer.getSubcontainer("Messages");

        // create new message
        IInstantMessage message = (IInstantMessage) messagesContainer.add();

        // add some text
        message.setBody("foo bar");

        // send the message to a user
        message.addRecipient(" -- provider specific recipient URI -- ");

        // send the message
        message.send();

Send typing notification
Add an item to the `Messages` container off of the root container. You will receive an instance of `IInstantMessage`, on which you can then call `IMessage.addRecipient(String)` and `IInstantMessage.setTypingStatus(boolean)`. If you wish, you may later call `IMessagingItem.setBody(String)` and `IMessage.send()` on the same message. Sending a typing notificaiton

        // sending a typing notification to a user
        session.setTypingStatus(" -- provider specific recipient URI -- ", true);

Receive incoming messages (realtime)
You will receive an IM event when items arrive and you may call `ImEvent.getSource()` on that event to retrieve the instant message.
Receive incoming messages (polled)
When you wish to poll for new messages, call `IContainer.getItems()` on the `Messages` container. When you get the items, you will receive instances of `IInstantMessage` (which are then removed permanently from the `Messages` container), on which you can then call `IMessage.getRecipients()` and `IMessagingItem.getBody()`. NOTE: There are two levels of polling, your polling the API for new messages and the API polling the instant messaging server for new messages. is `true`. Sending a typing notificaiton

        // instantiate a listener
        QueueImEventListener listener = new QueueImEventListener();

        // add listener to session
        session.addImListener(listener);

        List events;
        synchronized (listener)
            {
            while ((events = listener.getEvents()).size() == 0)
                {
                listener.wait();
                }
            }
        Iterator iter = events.iterator();
        while (iter.hasNext())
            {
            ImEvent event = (ImEvent) iter.next();
            // handle event
            }

Receive presence changes and typing notifications (realtime)
You will receive an IM event when a friend's information changes and you may call `ImEvent.getSource()()` on that event to get the friend that is affected by the event and determine what has been updated.
Receive presence changes and typing notifications (polled)
Add a `QueueImEventListener` to the `IImSession`. You will be able to call `QueueEventListener.getEvents()` to poll and receive any events that have arrived.
Set presence status Call `IImSession.setPresence(FriendStatus)`. This may be done prior to or after opening the `Session`. Setting presence status

        session.setPresence(FriendStatusEnum.OFFLINE);

Get friend groups
Get the container in the `Friends` container using `IContainer.getSubcontainers()`. Get all groups

        IRootContainer rootContainer = session.getDefaultRootContainer();

        IContainer friendsContainer = rootContainer.getSubcontainer("Friends");

        IContainer[] groups = friendsContainer.getSubcontainers();

        for (int i = 0; i < groups.length; i++)
            {
            IContainer group = groups[i];
            // handle this group
            }

Get friends
Get the items in the `Friends` container using `IContainer.getItems()`. These will be instances of `IFriend`, on which you can check presence status and other information. Get all groups

        IRootContainer rootContainer = session.getDefaultRootContainer();

        IContainer friendsContainer = rootContainer.getSubcontainer("Friends");

        IItem[] friends = friendsContainer.getItems();

        for (int i = 0; i < friends.length; i++)
            {
            IItem friend = friends[i];
            // handle this friend
            }

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

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