|
Smack | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.jivesoftware.smack.provider.ProviderManager
public class ProviderManager
Manages providers for parsing custom XML sub-documents of XMPP packets. Two types of providers exist:
By default, Smack only knows how to process IQ packets with sub-packets that are in a few namespaces such as:
<?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 packet XML. For example, an XMPP time packet 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 packet 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 packet 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 packet 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 contruct an object. In the latter case, bean introspection is used to try to automatically set the properties of the class using the values in the packet 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.
It is possible to provide a custom provider manager instead of the default implementation
provided by Smack. If you want to provide your own provider manager then you need to do it
before creating any Connection
by sending the static
setInstance(ProviderManager)
message. Trying to change the provider manager after
an Connection was created will result in an IllegalStateException
error.
Method Summary | |
---|---|
void |
addExtensionProvider(String elementName,
String namespace,
Object provider)
Adds an extension provider with the specified element name and name space. |
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. |
Object |
getExtensionProvider(String elementName,
String namespace)
Returns the packet extension provider registered to the specified XML element name and namespace. |
Collection<Object> |
getExtensionProviders()
Returns an unmodifiable collection of all PacketExtensionProvider instances. |
static ProviderManager |
getInstance()
Returns the only ProviderManager valid instance. |
Object |
getIQProvider(String elementName,
String namespace)
Returns the IQ provider registered to the specified XML element name and namespace. |
Collection<Object> |
getIQProviders()
Returns an unmodifiable collection of all IQProvider instances. |
protected void |
initialize()
|
void |
removeExtensionProvider(String elementName,
String namespace)
Removes an extension provider with the specified element name and namespace. |
void |
removeIQProvider(String elementName,
String namespace)
Removes an IQ provider with the specified element name and namespace. |
static void |
setInstance(ProviderManager providerManager)
Sets the only ProviderManager valid instance to be used by all Connections. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method Detail |
---|
public static ProviderManager getInstance()
setInstance(ProviderManager)
to configure your own provider manager. If non was provided then an instance of this
class will be used.
public static void setInstance(ProviderManager providerManager)
providerManager
- the only ProviderManager valid instance to be used.
IllegalStateException
- if a provider manager was already configued.protected void initialize()
public Object getIQProvider(String elementName, String namespace)
<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.
elementName
- the XML element name.namespace
- the XML namespace.
public Collection<Object> getIQProviders()
public void addIQProvider(String elementName, String namespace, Object provider)
elementName
- the XML element name.namespace
- the XML namespace.provider
- the IQ provider.public void removeIQProvider(String elementName, String namespace)
addIQProvider
method.
elementName
- the XML element name.namespace
- the XML namespace.public Object getExtensionProvider(String elementName, String namespace)
<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.
elementName
- element name associated with extension provider.namespace
- namespace associated with extension provider.
public void addExtensionProvider(String elementName, String namespace, Object provider)
elementName
- the XML element name.namespace
- the XML namespace.provider
- the extension provider.public void removeExtensionProvider(String elementName, String namespace)
addExtensionProvider
method.
elementName
- the XML element name.namespace
- the XML namespace.public Collection<Object> getExtensionProviders()
|
Smack | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |