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.