Compoze Software, Inc.

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
        }
    


Compoze Software, Inc.

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