org.jivesoftware.smack.provider

Class ProviderManager

java.lang.Object

org.jivesoftware.smack.provider.ProviderManager

public final class ProviderManager
extends Object

Manages providers for parsing custom XML sub-documents of XMPP packets. Two types of providers exist:

• IQProvider -- parses IQ requests into Java objects.
• PacketExtension -- parses XML sub-documents attached to packets into PacketExtension instances.

IQProvider

By default, Smack only knows how to process IQ packets with sub-packets that are in a few namespaces such as:

• jabber:iq:auth
• jabber:iq:roster
• jabber:iq:register

Because many more IQ types are part of XMPP and its extensions, a pluggable IQ parsing mechanism is provided. IQ providers are registered programmatically or by creating a providers file. The file is an XML document that contains one or more iqProvider entries, as in the following example:

 <?xml version="1.0"?>
 <smackProviders>
     <iqProvider>
         <elementName>query</elementName>
         <namespace>jabber:iq:time</namespace>
         <className>org.jivesoftware.smack.packet.Time</className>
     </iqProvider>
 </smackProviders>

Each IQ provider is associated with an element name and a namespace. If multiple provider entries attempt to register to handle the same namespace, the first entry loaded from the classpath will take precedence. The IQ provider class can either implement the IQProvider interface, or extend the IQ class. In the former case, each IQProvider is responsible for parsing the raw XML stream to create an IQ instance. In the latter case, bean introspection is used to try to automatically set properties of the IQ instance using the values found in the IQ stanza XML. For example, an XMPP time stanza resembles the following:

 <iq type='result' to='joe@example.com' from='mary@example.com' id='time_1'>
     <query xmlns='jabber:iq:time'>
         <utc>20020910T17:58:35</utc>
         <tz>MDT</tz>
         <display>Tue Sep 10 12:58:35 2002</display>
     </query>
 </iq>

In order for this stanza to be automatically mapped to the Time object listed in the providers file above, it must have the methods setUtc(String), setTz(String), and setDisplay(String). The introspection service will automatically try to convert the String value from the XML into a boolean, int, long, float, double, or Class depending on the type the IQ instance expects.

A pluggable system for stanza extensions, child elements in a custom namespace for message and presence packets, also exists. Each extension provider is registered with a name space in the smack.providers file as in the following example:

 <?xml version="1.0"?>
 <smackProviders>
     <extensionProvider>
         <elementName>x</elementName>
         <namespace>jabber:iq:event</namespace>
         <className>org.jivesoftware.smack.packet.MessageEvent</className>
     </extensionProvider>
 </smackProviders>

If multiple provider entries attempt to register to handle the same element name and namespace, the first entry loaded from the classpath will take precedence. Whenever a stanza extension is found in a packet, parsing will be passed to the correct provider. Each provider can either implement the PacketExtensionProvider interface or be a standard Java Bean. In the former case, each extension provider is responsible for parsing the raw XML stream to construct an object. In the latter case, bean introspection is used to try to automatically set the properties of th class using the values in the stanza extension sub-element. When an extension provider is not registered for an element name and namespace combination, Smack will store all top-level elements of the sub-packet in DefaultPacketExtension object and then attach it to the packet.

Constructor Summary

Constructors

Constructor and Description
ProviderManager()

Method Summary

Modifier and Type	Method and Description
static void	addExtensionProvider(String elementName, String namespace, Object provider) Adds an extension provider with the specified element name and name space.
static void	addIQProvider(String elementName, String namespace, Object provider) Adds an IQ provider (must be an instance of IQProvider or Class object that is an IQ) with the specified element name and name space.
static void	addLoader(ProviderLoader loader)
static void	addStreamFeatureProvider(String elementName, String namespace, ExtensionElementProvider<ExtensionElement> provider)
static ExtensionElementProvider<ExtensionElement>	getExtensionProvider(String elementName, String namespace) Returns the stanza extension provider registered to the specified XML element name and namespace.
static List<ExtensionElementProvider<ExtensionElement>>	getExtensionProviders() Returns an unmodifiable collection of all PacketExtensionProvider instances.
static IQProvider<IQ>	getIQProvider(String elementName, String namespace) Returns the IQ provider registered to the specified XML element name and namespace.
static List<IQProvider<IQ>>	getIQProviders() Returns an unmodifiable collection of all IQProvider instances.
static ExtensionElementProvider<ExtensionElement>	getStreamFeatureProvider(String elementName, String namespace)
static String	removeExtensionProvider(String elementName, String namespace) Removes an extension provider with the specified element name and namespace.
static String	removeIQProvider(String elementName, String namespace) Removes an IQ provider with the specified element name and namespace.
static void	removeStreamFeatureProvider(String elementName, String namespace)

Methods inherited from class java.lang.Object

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

Constructor Detail

ProviderManager

public ProviderManager()

Method Detail

addLoader

public static void addLoader(ProviderLoader loader)

getIQProvider

public static IQProvider<IQ> getIQProvider(String elementName,
                                           String namespace)

Returns the IQ provider registered to the specified XML element name and namespace. For example, if a provider was registered to the element name "query" and the namespace "jabber:iq:time", 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:time'>
         <utc>20020910T17:58:35</utc>
         <tz>MDT</tz>
         <display>Tue Sep 10 12:58:35 2002</display>
     </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 IQ provider.

getIQProviders

public static List<IQProvider<IQ>> getIQProviders()

Returns an unmodifiable collection of all IQProvider instances. Each object in the collection will either be an IQProvider instance, or a Class object that implements the IQProvider interface.

Returns:

all IQProvider instances.

addIQProvider

public static void addIQProvider(String elementName,
                                 String namespace,
                                 Object provider)

Adds an IQ provider (must be an instance of IQProvider or Class object that is an IQ) 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 IQ provider.

removeIQProvider

public static String removeIQProvider(String elementName,
                                      String namespace)

Removes an IQ provider with the specified element name and namespace. This method is typically called to cleanup providers that are programmatically added using the addIQProvider method.

Parameters:

elementName - the XML element name.

namespace - the XML namespace.

Returns:

the key of the removed IQ Provider

getExtensionProvider

public static ExtensionElementProvider<ExtensionElement> getExtensionProvider(String elementName,
                                                                              String namespace)

Returns the stanza extension provider registered to the specified XML element name and namespace. For example, if a provider was registered to the element name "x" and the namespace "jabber:x:event", then the following stanza would trigger the provider:

 <message to='romeo@montague.net' id='message_1'>
     <body>Art thou not Romeo, and a Montague?</body>
     <x xmlns='jabber:x:event'>
         <composing/>
     </x>
 </message>

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

Parameters:

elementName - element name associated with extension provider.

namespace - namespace associated with extension provider.

Returns:

the extension provider.

addExtensionProvider

public static void addExtensionProvider(String elementName,
                                        String namespace,
                                        Object provider)

Adds an extension provider with the specified element name and name space. The provider will override any providers loaded through the classpath. The provider must be either a PacketExtensionProvider instance, or a Class object of a Javabean.

Parameters:

elementName - the XML element name.

namespace - the XML namespace.

provider - the extension provider.

removeExtensionProvider

public static String removeExtensionProvider(String elementName,
                                             String namespace)

Removes an extension provider with the specified element name and namespace. This method is typically called to cleanup providers that are programmatically added using the addExtensionProvider method.

Parameters:

elementName - the XML element name.

namespace - the XML namespace.

Returns:

the key of the removed stanza extension provider

getExtensionProviders

public static List<ExtensionElementProvider<ExtensionElement>> getExtensionProviders()

Returns an unmodifiable collection of all PacketExtensionProvider instances. Each object in the collection will either be a PacketExtensionProvider instance, or a Class object that implements the PacketExtensionProvider interface.

Returns:

all PacketExtensionProvider instances.

getStreamFeatureProvider

public static ExtensionElementProvider<ExtensionElement> getStreamFeatureProvider(String elementName,
                                                                                  String namespace)

addStreamFeatureProvider

public static void addStreamFeatureProvider(String elementName,
                                            String namespace,
                                            ExtensionElementProvider<ExtensionElement> provider)

removeStreamFeatureProvider

public static void removeStreamFeatureProvider(String elementName,
                                               String namespace)