iPlanet Collaboration API   Overview iPlanet Portal Server : Instant Collaboration Pack allows portal users to communicate in real-time, using the Conference, Presence, News and Notification services.

See:
          Description

Packages
com.sun.im.desktop Sun Messenger Beans API   Overview The goal of the Sun Messenger Beans API is to allow developers to extend the Sun Messenger user interface.
com.sun.im.provider Sun ONE Instant Messaging Service Provider Interfaces

Sun ONE Instant Messaging supports the following types of service provider modules: Authentication/SSO providers and message archive providers.
com.sun.im.service Sun ONE IM Service API   Overview Sun ONE Instant Messaging allows users to communicate in real-time, using the Conference, Presence, News and Notification services.

 

iPlanet Collaboration API

 

Overview

iPlanet Portal Server : Instant Collaboration Pack allows portal users to communicate in real-time, using the Conference, Presence, News and Notification services. The iPlanet Collaboration API (iCAPI) allows developers to create applications which leverage these services. Possible applications include

Overview diagram

Available services


 

How to use iCAPI

 

Creating a Session and accessing services

A session is a service-independent authentication handle.  It is created by passing credentials and having them validated by the services infrastructure.

In order to create sessions, an application must fisrt instantiate CollaborationSessionFactory. Then the factory can be used to create session objects for specific users. Example:

CollaborationSessionFactory fac = new CollaborationSessionFactory();
// create a session listener for asynchronous session events
CollaborationSessionListener listener = new MyCollaborationSessionListener();
// create a session
Session session = fac.getSession("myserver.example.com:9909",
                                 "fred@example.com", "secret",
                                 listener);


Accessing a service

Once a Session is created, individual services can  be accessed using the accessService method.  So for example with the Conference service:

// access the Conference Service
ConferenceSession cSession = (ConferenceSession)session.accessService(CollaborationSessionFactory.CONFERENCE);
Note that it is important to make sure that the session listener associated with a Session implements all the relevant methods for accessed services.
 
 

The Conference Service

Once the ConferenceSession object has been created, a conference can be initiated by inviting one or more other users.  For Example:
// create a Conference Listener for asynchronous chat events (e.g. messages).
MyConferenceListener cListener = new MyConferenceListener();
// create the conference.
Conference c = cSession.setupConference(cListener, Conference.MANAGE)
To invite users to this conference, one needs to setup an invite message and call invite using this message.

// create invite message
Message newMsg = c.createInviteMessage();
newMsg.addRecipient("roscoe@example.com");
newMsg.addRecipient("yolanda@example.com");
MessagePart part = newMsg.newPart();
part.setContent("Let's talk");
newMsg.addPart(part);

// send the invite
e.invite(newMsg);
One can also join an already existing public conference, by using its well-known address:
// join public conference conf123@example.com
Conference c = cSession.join("conf123@example.com", cListener);
Once a Conference object is created, it can be used to build and send messages, as if it was a private conference.
 

The News Service

To use the news functionality, one needs to create a NewsChannel object for each news channel of interest, as follows
// create a news channel listener for asynchronous events (e.g. messages added or removed).
// note: MyNewsChannelListener implements the NewsChannelListener interface.
MyNewsChannelListener bbListener = new MyNewsChannelListener();
// subscribe to the news channel.  news channel messages are received
// asynchronously, through the listener.  One may also pass a null
NewsChannel  bb = nSession.getNewsChannel("hugo@example.com", bbListener)


Once created, the NewsChannel object can be used to generate, add or remove messages.

// generate a new message
Message message = bb.createMessage();
// add content to message
// publish it
bb.addMessage(message);


To find out which news channels are available, use the listNewsChannels method:

// get a Collection of news channels.
java.util.Collection bbList = session.listNewsChannels();

// loop through the list until you find the one you want
if (bbList != null) {
    java.util.Iterator bbIter = bbList.iterator();
    while (bbIter.hasNext()) {
        NewsChannel bb = (NewsChannel)bbIter.next();
        if (bb.getDestination.equals("theOneIWant")) {
            break;
        }
    }
}

// subscribe to it to get messages
bb.subscribe(bbListener);
 
 

Finally, it is also possible to create new news channels, as follows:
bb = session.newNewsChannel("hugo@example.com", bbListener,
                              Conference.PUBLISH);

The Notification Service

To send a message, first create one
// start a message to noah@example.com
Message message = nSession.createMessage("noah@example.com");
fill it with appropriate content and headers,
message.setHeader("Subject", "just a demo");
MessagePart part = message.newPart();
String content = "the body of the message";
part.setContentType("text/plain");
part.setContent(content.bytes());
create a message status listener if you expect status or replies,
MyMessageStatusListener mListener = new MyMessageStatusListener();
and send it:
session.sendMessage(message, mListener);


Messages can also be received.  This is done through the NotificationSessionListener.onMessage method.  Received messages may be acknowledged or replied-to through the MessageHandler argument to onMessage.
 

// mark a message read.
handler.sendStatus(MessageStatus.READ);

// reply to a message
replyMessage = nSession.createMessage();
...
handler.sendReply(replayMessage);


 

The Presence Service

To use the presence service, first create a PresenceSession using CollaborationSession.accessService

To access the presence information of a user of the service, use the fetch or subscribe methods

// subscribe to hugo's presentity // Note: MyPresenceInfoListener implements PresenceInfoListener
MyPresenceInfoListener piListener = new MyPresenceInfoListener();
java.util.Date expiration =
PresenceSubscription subs = pSession.subscribe("hugo@example.com", piListener, expiration);
...

// unsubscribe
subs.cancel();

Presence information is received asynchronously by the presence info listener in the form of an XML String. This String may be parsed using the PresenceHelper class. The following prints out presence info.

PresenceHelper ph = new PresenceHelper(pi /* XML string */);
for (Iterator i = ph.getTuples().iterator(); i.hasNext() ; ) {
    PresenceTuple t = (PresenceTuple)i.next();
    System.out.println(t.destination + " " + t.status + " " + t.note);
}

To publish presence information updates, use the publish method. The argument is an XML String which can be genberated with the help of the PresenceHelper class.

PresenceTuple pt = new PresenceTuple("hugo@example.com",
            PresenceSession.STATUS_AWAY);
PresenceHelper ph = new PresenceHelper();
ph.addTuple(pt);
pSession.publish(ph.toString());

 

The Personal Store Service

To use the Personal Store service, first create a PersonalStoreSession using CollaborationSession.accessService

To retrieve the contact list of the user who owns the current session, retrieve the contact folders

Collection folders = psSession.getFolders(PersonalStoreFolder.CONTACT_FOLDER);
For each folder fthe list of contacts can be obtained as follows:
Collection entries = f.getEntries();
System.out.println(" - " + f.getDisplayName());
for (Iterator j = entries.iterator() ; j.hasNext() ;) {
    PersonalContact c = (PersonalContact)j.next();
    System.out.println("Found " + c.getDisplayName() + " in " + f.getDisplayName());
}

 

How to set up the build and execution environment

Class Path

The iCAPI implementation delivered in iPS:ICP 3.0 is contained in the following jar files. It depends on JAXP 1.1, which is composed of All these jar files are included in the $installdir/classes directory after installing the iPS:ICP server component. They must be included in the classpath used to build or run you application. Note that your application may not use JAXP 1.0 and iCAPI at the same time, as the 2 versions of JAXP will step in each other.

Administrative user

Though not recommended, it is often practical for an application to authenticate as a non-ldap user. iPS:ICP allows the use of administrative credentials not stored in ldap, through the existence of the users.cfg and groups.cfg files in the config directory.

To create an administrative set of credentials, follow these steps


 

Source code

These are a few simple but actual examples written with iCAPI. They are provided here for educational purposes only and should not be used for other purposes.