org.glassfish.cafe.api.presence
Interface PresenceDocument

public interface PresenceDocument

Represents presence information which is either associated with a PresenceSource, or received in a Notification as part of a PresenceWatcherprocedure. Contains several instances of PresenceInformation. Contains information related to one presentity.

The PresenceDocument may contain zero or more Device Information elements in tupples, zero or one Person Information elements and zero or more Device Information elements. According to RCS no Device Information elements are included.

For more flexibility, it is also possible to add DOM elements, or to obtains the xml format of the document.

Information structured according to the OMA presence data model is exchanged in an XML document that conforms to the basic Presence Information Data Format as defined in [RFC3863], and extended in other documents for the purpose of interworking. A time stamp is automatically inserted when the document is published.

Field Summary

static String	NS_CIPID CIPID Namespace definition
static String	NS_CIVICLOC GEOPRIV CIVICLOC Namespace definition
static String	NS_GEOPRIV10 GEOPRIV Namespace definition
static String	NS_OMAPRES OMA-PRES Namespace definition
static String	NS_PDM Presence Document Model (PDM) Namespace definintion
static String	NS_PIDF PIDF Namespace definition
static String	NS_RPID RPID Namespace definition

Method Summary

void	addElement(Element element) Adds Element to your Presence Document.
String[]	getAllActivities() Convenience method to get all activities of all the person information elements.
Collection<DeviceInformation>	getAllDeviceInformation() Returns the collection of device information ID's defined on this document
Collection<ServiceInformation>	getAllServiceInformation() Returns the collection of Service Information elements defined on this document.
DeviceInformation	getDeviceInformation(String aDeviceId) Returns the DeviceInformation connected to the presence document and with the specified device ID.
DeviceInformation	getDeviceInformationAnyway(String aDeviceId) Returns the DeviceInformation if an instance with this device ID exists, creates an instance of DeviceInformation with this device ID if it does not exist and returns it.
Element	getElementNS(String uri, String name) Returns an Element object belonging to this Presence Document.
NodeList	getElementsNS(String uri, String name) Returns an Element object belonging to this Presence Document.
String	getIdentity() Returns the identity associated to this presence document
PersonInformation	getPersonInformation() Returns the Person Information associated to this presence document, if any.
PersonInformation	getPersonInformationAnyway() Returns the Person Information associated to this presence document, or a newly created one if there was none before.
Collection<PersonInformation>	getPersonInformations() Get all the person information elements in the document.
ServiceInformation	getServiceInformation(String aServiceId) Returns the Service Information with the specified service ID.
ServiceInformation	getServiceInformation(String aServiceId, String version) Returns the Service Information with the specified service ID and version.
ServiceInformation	getServiceInformationAnyway(String aServiceId, String version) Returns the ServiceInformation if an instance with this service ID and version exists, creates an instance of ServiceInformation with this service ID and version if it did not exist and returns it.
String	getXML() Returns the raw XML content of this presence container.
void	mergeAccordingToOMA() Modify the document according to OMA by merging all the person information element into one person information element.
void	mergeAccordingToRCS() Modify the document according to RCS by merging all the person information element into one person information element.
void	removeDeviceInformation(String aDeviceId)
void	removePersonInformation() Removes the person information from the Presence Document.
void	removePersonInformation(String personId) Remove the specified person information element from the document.
void	removeServiceInformation(String aServiceId) Removes the Service Information indicated by the service ID.

Field Detail

NS_PIDF

static final String NS_PIDF

PIDF Namespace definition

See Also:

Constant Field Values

NS_OMAPRES

static final String NS_OMAPRES

OMA-PRES Namespace definition

See Also:

Constant Field Values

NS_RPID

static final String NS_RPID

RPID Namespace definition

See Also:

Constant Field Values

NS_PDM

static final String NS_PDM

Presence Document Model (PDM) Namespace definintion

See Also:

Constant Field Values

NS_CIPID

static final String NS_CIPID

CIPID Namespace definition

See Also:

Constant Field Values

NS_GEOPRIV10

static final String NS_GEOPRIV10

GEOPRIV Namespace definition

See Also:

Constant Field Values

NS_CIVICLOC

static final String NS_CIVICLOC

GEOPRIV CIVICLOC Namespace definition

See Also:

Constant Field Values

Method Detail

getIdentity

String getIdentity()

Returns the identity associated to this presence document

getServiceInformationAnyway

ServiceInformation getServiceInformationAnyway(String aServiceId,
                                               String version)

Returns the ServiceInformation if an instance with this service ID and version exists, creates an instance of ServiceInformation with this service ID and version if it did not exist and returns it.

Parameters:

aServiceId - identifies the service.

version - the version of the service.

Returns:

Found or created instance of Service Information.

getServiceInformation

ServiceInformation getServiceInformation(String aServiceId,
                                         String version)

Returns the Service Information with the specified service ID and version.

Parameters:

aServiceId - identifies the service.

version - the version of the service.

Returns:

The found Service Information.

getServiceInformation

ServiceInformation getServiceInformation(String aServiceId)

Returns the Service Information with the specified service ID.

Parameters:

aServiceId - identifies the service.

Returns:

The found Service Information.

removeServiceInformation

void removeServiceInformation(String aServiceId)

Removes the Service Information indicated by the service ID.

Parameters:

aServiceId - identifies the service.

getAllServiceInformation

Collection<ServiceInformation> getAllServiceInformation()

Returns the collection of Service Information elements defined on this document.

Returns:

the collection of Service Information elements.

getPersonInformation

PersonInformation getPersonInformation()

Returns the Person Information associated to this presence document, if any.

Returns:

a Person Information element.

getPersonInformationAnyway

PersonInformation getPersonInformationAnyway()

Returns the Person Information associated to this presence document, or a newly created one if there was none before.

Returns:

a Person Information element.

removePersonInformation

void removePersonInformation()

Removes the person information from the Presence Document.

getDeviceInformationAnyway

DeviceInformation getDeviceInformationAnyway(String aDeviceId)

Returns the DeviceInformation if an instance with this device ID exists, creates an instance of DeviceInformation with this device ID if it does not exist and returns it.

Parameters:

aDeviceId - uniquely identifies the device.

Returns:

Found or created instance of DeviceInformation.

getDeviceInformation

DeviceInformation getDeviceInformation(String aDeviceId)

Returns the DeviceInformation connected to the presence document and with the specified device ID.

Parameters:

aDeviceId - uniquely identifies the device.

Returns:

The device information connected to this presence document.

removeDeviceInformation

void removeDeviceInformation(String aDeviceId)

Parameters:

aDeviceId - identifies the device information to remove. In case the identifier does not exists, the method returns without throwing an exception.

getAllDeviceInformation

Collection<DeviceInformation> getAllDeviceInformation()

Returns the collection of device information ID's defined on this document

Returns:

a collection of Device Information.

getPersonInformations

Collection<PersonInformation> getPersonInformations()

Get all the person information elements in the document.

This is only useful on incoming documents, which can contain multiple elements Outgoing (constructed) documents documents contain only one person information element.
To get from a document with multiple person information elements to a document with only one person information element you can use the merge methods.

removePersonInformation

void removePersonInformation(String personId)

Remove the specified person information element from the document.

getAllActivities

String[] getAllActivities()

Convenience method to get all activities of all the person information elements.

Returns:

mergeAccordingToRCS

void mergeAccordingToRCS()

Modify the document according to RCS by merging all the person information element into one person information element. All but the most recent person information element in the document is removed. An RCS compliant application would apply this method after receiving an incoming presence document.

mergeAccordingToOMA

void mergeAccordingToOMA()

Modify the document according to OMA by merging all the person information element into one person information element. All but the most recent person information element in the document is removed. The information from the other person information elements is merged into the remaining element (e.g., union of the moods, union of the activities etc.) An OMA compliant application would apply this method after receiving an incoming presence document.

getXML

String getXML()

Returns the raw XML content of this presence container.

Returns:

the string representation of the XML document.

addElement

void addElement(Element element)

Adds Element to your Presence Document.

Parameters:

element - a DOM Element instance.

getElementNS

Element getElementNS(String uri,
                     String name)

Returns an Element object belonging to this Presence Document.

Parameters:

uri - the namespace uri. For instance "urn:ietf:params:xml:ns:pidf:rpid"

name - the tag name.

Returns:

the DOM element.

getElementsNS

NodeList getElementsNS(String uri,
                       String name)

Returns an Element object belonging to this Presence Document.

Parameters:

uri - the namespace uri. For instance "urn:ietf:params:xml:ns:pidf:rpid"

name - the tag name.

Returns:

the DOM element.