Package 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.

See:
          Description

Interface Summary
AccessRule access rule.
AuthenticationListener Listener which is used to query the choice of authentication mechanism to be used.
CollaborationGroup  
CollaborationPrincipal  
CollaborationSession Authenticated instant communication session.
CollaborationSessionListener abstract Basic listener Listeners are implemented by the application and invoked by the provider to communicate asynchronous event to the application.
CollaborationSessionProvider Interface defining a Collaboratio Session Provider.
Conference A Conference is an instant messaging session between 2 or more users.
ConferenceEvent An Event is a piece of information originated by the service, as opposed to a Message which is originated by another user of the service.
ConferenceEventListener interface to receive conference events as object.
ConferenceListener  
ConferenceService The Conference service.
ConferenceServiceListener The ConferenceServiceListener.
ConferenceSession  
ConferenceSessionListener Callback object allowing invites and errors to be communicated asynchronously
ContentStream  
ContentStreamListener  
Delegation This interface is used to get the Delegated object
InviteMessage  
InviteMessageStatusListener  
Message  
MessagePart a message body part
MessageProcessingListener  
MessageProcessingRule This class allows the application to define rules governing how messages should be processed by the service.
MessageStatusListener A MessageStatusListener is instantiated by the application, passed to the alert method in Session and later used to convey statusses and responses to the sender.
NewsChannel NewsChannels inherit all the attributes and behaviors of a conference, in particular, members can be instantly notified of new messages, access control rules are created and manages the same way.
NewsChannelListener A NewsChannelListener is a callback object instantiated by the application and used by the ICAPI provider to provide asynchronous notifications of news channel changes, namely new postings messages removed messages modified administrative events, such as changes in access levels
NewsService The NewsService
NewsSession  
NotificationService A Notification service is used to send and receive messages.
NotificationServiceListener The NotificationServiceListener Alert messages received are delivered through this listener.
NotificationSession A notification session is a context in which an authenticated user can use the Notification Service, that is send and receive messages.
NotificationSessionListener Callback object allowing invites and errors to be communicated asynchronously
PersonalConference This class represents a record of a public conference in a personal store.
PersonalContact a personal contact is essentially a person listed in an address book
PersonalGateway  
PersonalGroup a personal group is a LDAP group referenced in the personal store
PersonalProfile a personal profile is essentially a set of preference properties for the person
PersonalStoreEntry  
PersonalStoreFolder A folder is an entry which can contain other entries
PersonalStoreService The PersonalStore Service The service should be intialized by calling intialize() before using any of the methods.
PersonalStoreServiceListener Callback object to notify any asynchromous changes in the PersonalStoreEntry objects.
PersonalStoreSession  
PersonalStoreSessionListener Callback object to notify any asynchromous changes in the PersonalStoreEntry objects.
PresenceAccessRule Presence access rule
PresenceInfoListener object instantiated by the application allowing the provider to return data to the application asynchronously.
PresenceService presence service session.
PresenceServiceListener Callback object allowing the implementation to invoke the application when a presence notification needs to be relayed to the user.
PresenceSession presence service session.
PresenceSessionListener Callback object allowing the iCAPI implementation to invoke the application when a presence notification needs to be relayed to the user.
PresenceSubscription  
PrivacyItem an access control item is one element in a list of items defining the access rule to a particular resource.
PrivacyList  
ReadOnlyMessage  
ReadOnlyMessagePart a message body part
ReceiverFileStreamingProfile  
ReceiverStreamingProfile  
RegistrationListener Interface for listening to the events generated for user and gateway registration
SecureRegistrationListener Listener to be used for Registration when using SSL
SecureSessionListener abstract Session listener Listeners are implemented by the application and invoked by the provider to communicate asynchronous event to the application.
SecurityListener  
StreamingService  
StreamingServiceListener  
Watcher This class represents the watchers in the personal store
 

Class Summary
ApplicationInfo This class can be used to set the characteristics/properties of all CollaborationSession objects that will be created using a given SessionProvider.
CollaborationSessionFactory This class is a Factory class, which can be used to create CollborationSessions.
ConferenceEventHelper Helper class for recipients of a poll message.
ConferenceEventTuple  
ConferenceHistory This class should be used to convey the parameters desired for getting the message history for the conference room.
MessageProcessingRule.Action This class defines an action that the service can take on a message in transit
MessageProcessingRule.Condition base condition class
MessageProcessingRule.DispositionCondition A message disposition describes how the service plans to dispose of a message.
MessageProcessingRule.ExpirationCondition expiration condition
MessageProcessingRule.SessionCondition A recipient may access the service using multiple sessions.
MessageStatus This class defines message delivery status constants.
PersonalStoreEvent This object will be used to notify the changes in the PersonalStoreEntry objects.
Poll Helper class for application using the poll functionality.
PollHelper Helper class for recipients of a poll message.
PollResponse This class is used to parse the xml from the poll response
PolsterHelper Helps Collaboration client create poll messages and collect poll responses
Presence  
PresenceHelper Presence Document parser.
PresenceTuple  
SenderFileStreamingProfile  
SenderStreamingProfile  
 

Exception Summary
AuthenticationException  
AuthorizationException  
CertificateRejectedException This exception is used to signal that client has rejected the certificate
CollaborationException  
ConflictException  
ItemNotFoundException  
RecipientUnvailableException  
RoutingException  
ServiceUnavailableException Exception thrown when the application attempts to access a service which is not available.
TimeoutException Exception raised when a request to the service times out.
 

Package com.sun.im.service Description

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. The IM Service API allows developers to create applications which leverage these services. Possible applications include:

Available services

Architecture


 

How to use the API

 

Creating a Session

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 services

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

Using an alternative session provider

The instructions listed above will let you create an IM session, similar to a session that would be created by Sun ONE Instant Messenger. However, it is possible to create other types of session, by using alternative session providers. the IM Service API can be told to use a specific session provider, by setting the com.sun.im.service.provider system property to the class of the provider yopu want to use. For instance, com.example.SessionProvider being a Session Provider, one would call:
System.setProperty(CollaborationSessionFactory.systemProperty, "com.example.SessionProvider");
The IM Service API includes two alternative session providers: The following block diagram shows relationships between the various providers, the IM Service API implementation, IM components, and custom application.
 
 

How to set up the build and execution environment

Class Path

The the IM Service API implementation delivered in Sun ONE Instant Messaging 6.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 IM 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 the IM Service API 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. Sun ONE IM 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

Other System properties

Incoming notifications, or conference invitations are processed by a dedicated group of threads so as not to impact other traffic if the onMessage or onInvite callbacks block or take a long time. It also allows the application to send a reply from the onMessage or onInvite callback. The system property com.iplanet.im.client.api.concurrency specify the number of thread dedicated to processing notifications or invites. It is set to 2 by default.
 

Source code

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

Default API Provider's documentation

Default API Provider's documentation