org.jivesoftware.smackx
Class PrivateDataManager

java.lang.Object
  org.jivesoftware.smackx.PrivateDataManager

public class PrivateDataManager
extends Object

Manages private data, which is a mechanism to allow users to store arbitrary XML data on an XMPP server. Each private data chunk is defined by a element name and XML namespace. Example private data:

 <color xmlns="http://example.com/xmpp/color">
     <favorite>blue</blue>
     <leastFavorite>puce</leastFavorite>
 </color>
 

PrivateDataProvider instances are responsible for translating the XML into objects. If no PrivateDataProvider is registered for a given element name and namespace, then a DefaultPrivateData instance will be returned.

Warning: this is an non-standard protocol documented by JEP-49. Because this is a non-standard protocol, it is subject to change.

Author:

Matt Tucker

Nested Class Summary

static class

PrivateDataManager.PrivateDataIQProvider An IQ provider to parse IQ results containing private data.

Constructor Summary

PrivateDataManager(XMPPConnection connection)
Creates a new private data manager.

PrivateDataManager(XMPPConnection connection, String user)
Creates a new private data manager for a specific user (special case).

Method Summary

static void	addPrivateDataProvider(String elementName, String namespace, PrivateDataProvider provider) Adds a private data provider with the specified element name and name space.
PrivateData	getPrivateData(String elementName, String namespace) Returns the private data specified by the given element name and namespace.
static PrivateDataProvider	getPrivateDataProvider(String elementName, String namespace) Returns the private data provider registered to the specified XML element name and namespace.
static void	removePrivateDataProvider(String elementName, String namespace) Removes a private data provider with the specified element name and namespace.
void	setPrivateData(PrivateData privateData) Sets a private data value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PrivateDataManager

public PrivateDataManager(XMPPConnection connection)

Creates a new private data manager. The connection must have undergone a successful login before being used to construct an instance of this class.

Parameters:

connection - an XMPP connection which must have already undergone a successful login.

PrivateDataManager

public PrivateDataManager(XMPPConnection connection,
                          String user)

Creates a new private data manager for a specific user (special case). Most servers only support getting and setting private data for the user that authenticated via the connection. However, some servers support the ability to get and set private data for other users (for example, if you are the administrator). The connection must have undergone a successful login before being used to construct an instance of this class.

Parameters:

connection - an XMPP connection which must have already undergone a successful login.

user - the XMPP address of the user to get and set private data for.

Method Detail

getPrivateDataProvider

public static PrivateDataProvider getPrivateDataProvider(String elementName,
                                                         String namespace)

Returns the private data provider registered to the specified XML element name and namespace. For example, if a provider was registered to the element name "prefs" and the namespace "http://www.xmppclient.com/prefs", then the following packet would trigger the provider:

 <iq type='result' to='joe@example.com' from='mary@example.com' id='time_1'>
     <query xmlns='jabber:iq:private'>
         <prefs xmlns='http://www.xmppclient.com/prefs'>
             <value1>ABC</value1>
             <value2>XYZ</value2>
         </prefs>
     </query>
 </iq>

Note: this method is generally only called by the internal Smack classes.

Parameters:

elementName - the XML element name.

namespace - the XML namespace.

Returns:

the PrivateData provider.

addPrivateDataProvider

public static void addPrivateDataProvider(String elementName,
                                          String namespace,
                                          PrivateDataProvider provider)

Adds a private data provider with the specified element name and name space. The provider will override any providers loaded through the classpath.

Parameters:

elementName - the XML element name.

namespace - the XML namespace.

provider - the private data provider.

removePrivateDataProvider

public static void removePrivateDataProvider(String elementName,
                                             String namespace)

Removes a private data provider with the specified element name and namespace.

Parameters:

elementName - The XML element name.

namespace - The XML namespace.

getPrivateData

public PrivateData getPrivateData(String elementName,
                                  String namespace)
                           throws XMPPException

Returns the private data specified by the given element name and namespace. Each chunk of private data is uniquely identified by an element name and namespace pair.

If a PrivateDataProvider is registered for the specified element name/namespace pair then that provider will determine the specific object type that is returned. If no provider is registered, a DefaultPrivateData instance will be returned.

Parameters:

elementName - the element name.

namespace - the namespace.

Returns:

the private data.

Throws:

XMPPException - if an error occurs getting the private data.

setPrivateData

public void setPrivateData(PrivateData privateData)
                    throws XMPPException

Sets a private data value. Each chunk of private data is uniquely identified by an element name and namespace pair. If private data has already been set with the element name and namespace, then the new private data will overwrite the old value.

Parameters:

privateData - the private data.

Throws:

XMPPException - if setting the private data fails.