Package com.compoze.collab.lcs

This package provides classes for LCS schema.

See:
Description

Interface Summary

ILcsFriend	Describes an LCS friend
ILcsGroup	Describes a SIP friends group
ILcsInstantMessage	Interface defines an extension to the Collab instant message that is specific to SIP messages
ILcsSession	Specifies an LCS specific extension to IImSession

Class Summary

LcsFont	The element class for the LcsFontEnum enumeration.
LcsFontColor	The element class for the LcsFontColorEnum enumeration.
LcsFontColorEnum	The enumeration class that contains LcsFontColor elements.
LcsFontEnum	The enumeration class that contains LcsFont elements.
LcsFontStyle	The element class for the LcsFontStyleEnum enumeration.
LcsFontStyleEnum	The enumeration class that contains LcsFontStyle elements.
LcsFriendStatus	The element class for the LcsFriendStatusEnum enumeration.
LcsFriendStatusEnum	The enumeration class that contains LcsFriendStatus elements.

Package com.compoze.collab.lcs Description

This package provides classes for LCS schema.

Please see the com.compoze.collab.im package for general instructions on using instant messaging in Collaboration Framework.

This package provides classes to communicate with the Microsoft Live Communication Server.

Open a session

Required parameters
Parameter key	Description
ISession.PROP_PROVIDER	This must be a string "lcs"
IImSession.PROP_IM_USERNAME	Login name of a valid LCS user
IImSession.PROP_IM_PASSWORD	Password of a valid LCS user
ILcsSession.PROP_IM_DOMAIN	Windows domain of the valid LCS user
ILcsSession.PROP_IM_URI	User's URI
IImSession.PROP_IM_SERVER	LCS server machine name or IP address
IImSession.PROP_IM_PORT	LCS server port. This parameter is optional
ILcsSession.PROP_IM_DISPLAYNAME	Full name of the valid LCS user
ILcsSession.PROP_IM_DOMAINCONTROLLER	Name or IP address of the domain controller of the Windows domain specified by ILcsSession.PROP_IM_DOMAIN

Opening an LCS session is done the same as described in com.compoze.collab.im with the only difference being the six additional session properies documented in ILcsSession.

Here is an example of opening a session

    // first we must set all the properties the provider will use to connect to LCS
    Map props = new HashMap();
    // must be set to "lcs" to use the LCS provider
    props.put(ISession.PROP_PROVIDER, "lcs");
    props.put(IImSession.PROP_IM_USERNAME, "myusername");
    props.put(IImSession.PROP_IM_PASSWORD, "mypassword");
    props.put(com.compoze.collab.lcs.ILcsSession.PROP_IM_DOMAIN, "mydomain");
    props.put(com.compoze.collab.lcs.ILcsSession.PROP_IM_URI, "myusername@mydomain.mycompany.com");
    props.put(com.compoze.collab.lcs.ILcsSession.PROP_IM_SERVER, "192.168.100.100");
    // default LCS port is 5060
    props.put(com.compoze.collab.lcs.ILcsSession.PROP_IM_PORT, "5060");
    props.put(com.compoze.collab.lcs.ILcsSession.PROP_IM_DISPLAYNAME, "John H. Smith");
    props.put(com.compoze.collab.lcs.ILcsSession.PROP_IM_DOMAINCONTROLLER, "DOMAIN_COROLLER_MACHINE_NAME");

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

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

Additionally, client code may check for session status by using the ILcsSession.isEstablished() method

    // check session validity
    if(session.isEstablished())
        System.out.println("SUCCESS");
    else
        System.out.println("FAILED");
    

Send an instant message

Sending a message is also done similarly to the way it's done in com.compoze.collab.im. The only difference is the way recipients are name in LCS. LCS provides three ways to refer to a friend. Friend's user name, URI, or display name. When sending a message from Collaboration Framework, you must use the URI associated with the intended recipient.

    // 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 user identified by URI myfriend@mydomain.mycompany.com
    message.addRecipient("myfriend@mydomain.mycompany.com");

    // send the message
    message.send();
    

Send typing notification

Sending out a typing notification is done as describe in com.compoze.collab.im. Use the URI of the friend with whom you are having a conversation to indicate which friend should recieve the notification. Please note that a conversation must be in progress for typing notification to occur. Sending a typing notification before any message exchange has occured will result in CollaborationException being thrown.

    // sending a typing notification to user identified by URI myfriend@mydomain.mycompany.com
    session.setTypingStatus("myfriend@mydomain.mycompany.com", true);
    

Receive incoming messages (realtime)

Receiving incoming message in real time can be accomplished in two ways First, client code can create a custom listener by implementing IImListener interface and registering the instance with the session.

    // instantiate the custom listener
    IImListener listener = new MyImListener();
    // add listener to session
    session.addImListener (listener);
    

Second, client code can utilize a QueueImEventListener instance and use the QueueEventListener.getEvents() method to get a list of new events.

    // 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();
        // handl event
        }
    

Receive typing notification from a friend

Notwithstanding provider implementations, Collaboration Framework doesn't treat typing notifications as friend status changes. When a typing notification is received, an ImEvent of type ImEvent.FRIEND_UPDATED is generated and IFriend.isTyping() returns true. Client code should use the IFriend.isTyping() method to check whether a friend is currently typing. LCS only sends notifications of keyboard activity. It does not send any messages indicating the end of such activity. Therefore, Collaboration Framework will automatically reset the typing flag and fire a ImEvent.FRIEND_UPDATED event after a timeout of 500 ms unless more typing notifications are received, in which case the timer is reset. The automatic ImEvent.FRIEND_UPDATED event will be fired 500 ms after the last typing notification is received by the API.

Example of handling a typing notification

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

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

    // check to see if any events have arrived
    List events;
    if( (events = listener.getEvents()) != null)
        {
        Iterator iter = events.iterator();

        // iterate over events
        while(iter.hasNext())
            {
            ImEvent event = (ImEvent)iter.next();

            // must make sure we are dealing with a message received event
            if(event.getType() == ImEvent.FRIEND_UPDATED)
                {
                IFriend friend = (IFriend)event.getSource();
                if(friend.isTyping())
                    {
                    System.out.println("Friend "+friend.getUsername()+" is typing");
                    }
                else
                    {
                    System.out.println("Friend "+friend.getUsername()+" finished typing");
                    }
                }
            }
        }
    

Add a friend to friends list

In LCS, friends always belong to a group. If group is not specified when adding to the list, new friend will be placed into the default group. This default group has an ID 1 and a name "~".
To be successfully added to the list, LCS users must:

• be registered as Windows users
• belong to the same or trusted domain as the LCS server
• have Live Communication Services enabled for their Windows account

If the user that is being added to the list does not meet any of the above criteria, a CollaborationException will be thrown. Here is an example of adding a valid use to the default ("~") group

    IRootContainer rootContainer = session.getDefaultRootContainer ();

    // get the Friends container
    IContainer friendsContainer = rootContainer.getSubcontainer ("Friends");

    // create the new friend
    ILcsFriend newFriend = (ILcsFriend)friendsContainer.add();

    // set the URI.
    newFriend.setUri("myfriend@mydomain.mycompany.com");

    // commit the new friend.  No change occurs on the server until this method is called.
    newFriend.commit();
    

Here is an example of adding a friend to an existing group:

    IRootContainer rootContainer = session.getDefaultRootContainer ();

    // get the Friends container
    IContainer friendsContainer = rootContainer.getSubcontainer ("Friends");

    // get the group to add the friend to
    IContainer myGroup = friendsContainer.getSubcontainer("mygroup");
    // create the new friend
    ILcsFriend newFriend = (ILcsFriend)myGroup.add();

    // set the URI.
    newFriend.setUri("myfriend@mydomain.mycompany.com");

    // commit the new friend.  No change occurs on the server until this method is called.
    newFriend.commit();
    

Delete friends from the list

Deleting friends is accomplished by calling IItem.delete() on the friend you wish to remove from the list. There is no need to call IItem.commit(). Changes on the LCS server will occur when IItem.delete() is called.
This example will delete the entire friends list

    IRootContainer rootContainer = session.getDefaultRootContainer ();

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

    IItem [] friends = friendsContainer.getItems();

    for(int i=0; i < friends.length; ++i)
        friends[i].delete();
    

Create groups

Creating a group is as simple as invoking a IContainer.addSubcontainer(java.lang.String) on the Friends container.
Important: LCS only allows for one level of nesting for groups. It is not possible to have a group contain another group within it. Invoking a IContainer.addSubcontainer(java.lang.String) on any container other then Friends will result in a CollaborationException being thrown.

Example of creating a new group

    // get the Friends container
    IContainer friendsContainer = rootContainer.getSubcontainer ("Friends");
    // create a new group called "mygroup"
    IContainer myGroup = friendsContainer.addSubcontainer("mygroup");

    // commit.  No changes will take place on the server until this method is called
    myGroup.commit();
    

Delete groups

Deleting a group is accomplished by envoking IItem.delete() on an IContainer instance. Please note that the top level group cannot be deleted. Attempting to delete the top level group ("~") WILL NOT generate an exception, but no changes will take place.

    // get the group
    IContainer myGroup = friendsContainer.getSubcontainer("mygroup");
    // delete the group
    myGroup.delete();