Provider Architecture: Packet Extensions and Custom IQ's
========================================================
[Back](index.html)
Introduction
------------
The Smack provider architecture is a system for plugging in custom XML parsing
of packet extensions and IQ packets. The standard [Smack
Extensions](extensions/index.html) are built using the provider architecture.
There are two types of providers:
* `IQProvider` -- parses IQ requests into Java objects.
* `Extension Provider` -- parses XML sub-documents attached to packets into PacketExtension instances. By default, Smack only knows how to process a few standard packets and sub-packets that are in a few namespaces such as:
* jabber:iq:auth
* jabber:iq:roster
* jabber:iq:register There are many more IQ types and extensions that are part of XMPP standards, and of course an endless number that can be added as custom extensions. To support this, an extensible parsing mechanism is provided via Smack and user build providers.
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,
via the [XML Pull Parser](http://www.xmlpull.org/), 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 no extension provider is registered for an element name and namespace
combination, Smack will store all top-level elements of the sub-packet in the
DefaultPacketExtension object and then attach it to the packet.
Management of these providers is accomplished via the [ProviderManager]()
class. There are multiple ways to add providers to the manager.
* Call addXXProvider methods - You can call the appropriate add methods directly.
```
ProviderManager.addIQProvider("element", "namespace", new MyIQProvider());
ProviderManager.addExtensionProvider("element", "namespace", new MyExtProvider());
```
* Add a loader - You can add a ProviderLoader which will inject a means of loading multiple providers (both types) into the manager. This is the mechanism used by Smack to load from the Smack specific file format (via ProviderFileLoader). Implementers can provide the means to load providers from any source they wish, or simply reuse the ProviderFileLoader to load from their own provider files.
ProviderManager.addLoader(new ProviderFileLoader(FileUtils.getStreamForUrl("classpath:com/myco/provider/myco_custom.providers", null)));
* VM Argument - You can add a provider file via the VM argument _smack.provider.file_. This will load the file at the specified URL during startup when Smack initializes. This also assumes the default configuration, since it requires that the **VmArgInitializer** was part of the startup configuration.
`-Dsmack.provider.file=classpath:com/myco/provider/myco_custom.provider`s
or
`-Dsmack.provider.file=file:///c:/myco/provider/myco_custom.providers`
IQ Providers
------------
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:
### Introspection
_Time Packet_
20020910T17:58:35
MDT
Tue Sep 10 12:58:35 2002
_Time IQ Class_
class Time extends IQ {
private Date utc;
private TimeZone timeZone;
private String display;
@Override
public String getChildElementXML() {
return null;
}
public void setUtc(String utcString) {
try {
utc = StringUtils.parseDate(utcString);
} catch (ParseException e) {
}
}
public void setTimeZone(String zone) {
timeZone = TimeZone.getTimeZone(zone);
}
public void setDisplay(String timeDisplay) {
display = timeDisplay;
}
}
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.
_IQProvider Implementation_
_Disco Items Packet_