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

## 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();

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.