Package org.jivesoftware.smackx.iqprivate

Class PrivateDataManager

java.lang.Object

org.jivesoftware.smack.Manager

org.jivesoftware.smackx.iqprivate.PrivateDataManager

public final class PrivateDataManager
extends Manager

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 XEP-49. Because this is a non-standard protocol, it is subject to change.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	PrivateDataManager.PrivateDataIQProvider	An IQ provider to parse IQ results containing private data.

Method Summary

Modifier and Type	Method	Description
static void	addPrivateDataProvider(java.lang.String elementName, java.lang.String namespace, PrivateDataProvider provider)	Adds a private data provider with the specified element name and name space.
static PrivateDataManager	getInstanceFor(XMPPConnection connection)
PrivateData	getPrivateData(java.lang.String elementName, java.lang.String namespace)	Returns the private data specified by the given element name and namespace.
static PrivateDataProvider	getPrivateDataProvider(java.lang.String elementName, java.lang.String namespace)	Returns the private data provider registered to the specified XML element name and namespace.
boolean	isSupported()	Check if the service supports private data.
static void	removePrivateDataProvider(java.lang.String elementName, java.lang.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 org.jivesoftware.smack.Manager

connection, getAuthenticatedConnectionOrThrow, schedule, schedule, scheduleBlocking

Methods inherited from class java.lang.Object

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

Method Detail

getInstanceFor

public static PrivateDataManager getInstanceFor(XMPPConnection connection)

getPrivateDataProvider

public static PrivateDataProvider getPrivateDataProvider(java.lang.String elementName,
                                                         java.lang.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 stanza 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(java.lang.String elementName,
                                          java.lang.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(java.lang.String elementName,
                                             java.lang.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(java.lang.String elementName,
                                  java.lang.String namespace)
                           throws SmackException.NoResponseException,
                                  XMPPException.XMPPErrorException,
                                  SmackException.NotConnectedException,
                                  java.lang.InterruptedException

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.XMPPErrorException - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

setPrivateData

public void setPrivateData(PrivateData privateData)
                    throws SmackException.NoResponseException,
                           XMPPException.XMPPErrorException,
                           SmackException.NotConnectedException,
                           java.lang.InterruptedException

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.XMPPErrorException - if there was an XMPP error returned.

SmackException.NoResponseException - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

isSupported

public boolean isSupported()
                    throws SmackException.NoResponseException,
                           SmackException.NotConnectedException,
                           java.lang.InterruptedException,
                           XMPPException.XMPPErrorException

Check if the service supports private data.

Returns:

true if the service supports private data, false otherwise.

Throws:

SmackException.NoResponseException - if there was no response from the remote entity.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

XMPPException.XMPPErrorException - if there was an XMPP error returned.

Since:

4.2