|
Compoze Software, Inc. | ||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
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. |
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.
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();
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();
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);
ImEvent.getSource()
on that event to retrieve
the instant message.
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 }
ImEvent.getSource()()
on that event to get
the friend that is affected by the event and determine what has been
updated.
QueueImEventListener
to the
IImSession
. You will be able to call
QueueEventListener.getEvents()
to poll and
receive any events that have arrived.
IImSession.setPresence(FriendStatus)
.
This may be done prior to or after opening the Session
.
Setting presence statussession.setPresence(FriendStatusEnum.OFFLINE);
Friends
container using
IContainer.getSubcontainers()
.
Get all groupsIRootContainer 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 }
Friends
container using
IContainer.getItems()
. These will be instances of
IFriend
, on which you can check presence
status and other information.
Get all groupsIRootContainer 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. | ||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |