diff --git a/documentation/providers.html b/documentation/providers.html index f6be5a540..d11216bba 100644 --- a/documentation/providers.html +++ b/documentation/providers.html @@ -16,7 +16,100 @@ Provider Architecture: Packet Extensions and Custom IQ's

-Content to be added. +The Smack provider architecture is a system for plugging in +custom XML parsing of packet extensions and IQ packets. The +standard Smack Extensions +are built using the provider architecture. Two types of +providers exist:

+ +

IQProvider

+ +By default, Smack only knows how to process IQ packets with sub-packets that +are in a few namespaces such as: + +Because many more IQ types are part of XMPP and its extensions, a pluggable IQ parsing +mechanism is provided. IQ providers are registered programatically or by creating a +smack.providers file in the META-INF directory of your JAR 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. In the +example above, the element name is query and the namespace is +abber:iq:time. 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.

+ +

PacketExtensionProvider

+ +Packet extension providers provide a pluggable system for +packet extensions, which are child elements in a custom namespace +of message and presence packets (IQ packets cannot have packet extensions). +Each extension provider is registered with an element name and namespace +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. +