org.glassfish.cafe.api
Interface PresenceSource

All Superinterfaces:
UserProcedure

public interface PresenceSource
extends UserProcedure

This entity is responsible for publishing presence information on behalf of a presentity. A presentity is in this case a real user who has mandated an application to publish presence information on his behalf, or an application acting as a user itself.

A Presence Source implements the Event Publication Agent function. Presence Source is a UserProcedure. Each invocation of the update() method results in sending a PUBLISH method in the network, publishing the associated PresenceDocument to the presence service. The expiration time of the User procedure applies to the validity of the published presence document.

Events received after after invoking the update() method indicate whether the PresenceDocument is published or not. If it is, the last published PresenceDocument can be retrieved with the getConfirmedPresenceDocument() method. However, if the application wants to have a complete picture of the published presence information, including the presence information published by other sources, it may be necessary to start a subscription on its presence information with a PresenceWatcher.

The entity contains a number of convenience methods to change the content of the associated PresenceDocument easily. However, the PresenceDocument class itself provides more flexibility and more details.

The default PresenceDocument associated with a newly created PresenceSource is a PresenceDocument as generated by the createPersonOnline() method. So the minimum code to publish presence information for an ImsPresenceSource is:

 PresenceSource source = communicationSession.createPresenceSource(userId);
 source.update();
 

The Presence Source procedures are described in [RFC3903]. It supports the "application/pidf+xml" content type, according to [RFC3863].


Nested Class Summary
 
Nested classes/interfaces inherited from interface org.glassfish.cafe.api.UserProcedure
UserProcedure.State
 
Method Summary
 void createDocument(String xml)
          Overwrites the associated presence document with a presence document based on the content of an existing presence document.
 void createEmptyDocument()
          Overwrites the associated presence document with an empty one based on the user ID of this Presence Source.
 void createPersonOnline()
          Overwrites the associated presence document with a new one with status open and, in the person information, willingness set to open and the note set to online The presence document is based on the user ID of the Presence Source.
 void createPersonOnlineActivity(String activity)
          Overwrites the associated presence document with a new one with status open and an activity in the person information.
 PresenceDocument getConfirmedPresenceDocument()
          Returns the last presence document that has been acknowledged.
 PresenceDocument getPresenceDocument()
          Returns the actual version of the associated presence document.
 
Methods inherited from interface org.glassfish.cafe.api.UserProcedure
addAgent, end, getAgent, getAgents, getExpirationTime, getMessage, getState, getUserId, removeAgent, setExpirationTime, update
 

Method Detail

getPresenceDocument

PresenceDocument getPresenceDocument()
Returns the actual version of the associated presence document.

Returns:
the associated Presence document.

getConfirmedPresenceDocument

PresenceDocument getConfirmedPresenceDocument()
Returns the last presence document that has been acknowledged.

Returns:
the confirmed Presence document.

createDocument

void createDocument(String xml)
                    throws CommunicationException
Overwrites the associated presence document with a presence document based on the content of an existing presence document.

Throws:
CommunicationException - if the user ID in the XML document does not match the user ID of the Presence Source.

createEmptyDocument

void createEmptyDocument()
Overwrites the associated presence document with an empty one based on the user ID of this Presence Source.


createPersonOnline

void createPersonOnline()
Overwrites the associated presence document with a new one with status open and, in the person information, willingness set to open and the note set to online The presence document is based on the user ID of the Presence Source.


createPersonOnlineActivity

void createPersonOnlineActivity(String activity)
Overwrites the associated presence document with a new one with status open and an activity in the person information. The presence document is based on the user ID of the Presence Source.



Copyright © 2010. All Rights Reserved.