documentation/providers.html

   1 <html>
   2 <head>
   3         <title>Smack: Provider Architecture - Jive Software</title>
   4         <link rel="stylesheet" type="text/css" href="style.css" />
   5 </head>
   6
   7 <body>
   8
   9 <div class="header">
  10 Provider Architecture: Packet Extensions and Custom IQ's
  11 </div>
  12
  13 <div class="nav">
  14 &laquo; <a href="index.html">Table of Contents</a>
  15 </div>
  16
  17 <p>
  18
  19 The Smack provider architecture is a system for plugging in
  20 custom XML parsing of packet extensions and IQ packets. The
  21 standard  <a href="extensions/index.html">Smack Extensions</a>
  22 are built using the provider architecture. Two types of
  23 providers exist:<ul>
  24       <li><tt>IQProvider</tt> -- parses IQ requests into Java objects.
  25       <li><tt>PacketExtension</tt> -- parses XML sub-documents attached to
  26       packets into PacketExtension instances.</ul>
  27
  28 <p class="subheader">IQProvider</p>
  29
  30 By default, Smack only knows how to process IQ packets with sub-packets that
  31 are in a few namespaces such as:<ul>
  32       <li>jabber:iq:auth
  33       <li>jabber:iq:roster
  34       <li>jabber:iq:register</ul>
  35
  36 Because many more IQ types are part of XMPP and its extensions, a pluggable IQ parsing
  37 mechanism is provided. IQ providers are registered programatically or by creating a
  38 smack.providers file in the META-INF directory of your JAR file. The file is an XML
  39 document that contains one or more iqProvider entries, as in the following example:
  40
  41 <pre>
  42  &lt;?xml version="1.0"?&gt;
  43  &lt;smackProviders&gt;
  44      &lt;iqProvider&gt;
  45          &lt;elementName&gt;query&lt;/elementName&gt;
  46          &lt;namespace&gt;jabber:iq:time&lt;/namespace&gt;
  47          &lt;className&gt;org.jivesoftware.smack.packet.Time&lt/className&gt;
  48      &lt;/iqProvider&gt;
  49  &lt;/smackProviders&gt;</pre>
  50
  51 Each IQ provider is associated with an element name and a namespace. In the
  52 example above, the element name is <tt>query</tt> and the namespace is
  53 <tt>abber:iq:time</tt>. If multiple provider entries attempt to register to
  54 handle the same namespace, the first entry loaded from the classpath will
  55 take precedence. <p>
  56
  57 The IQ provider class can either implement the IQProvider
  58 interface, or extend the IQ class. In the former case, each IQProvider is
  59 responsible for parsing the raw XML stream to create an IQ instance. In
  60 the latter case, bean introspection is used to try to automatically set
  61 properties of the IQ instance using the values found in the IQ packet XML.
  62 For example, an XMPP time packet resembles the following:
  63
  64 <pre>
  65 &lt;iq type='result' to='joe@example.com' from='mary@example.com' id='time_1'&gt;
  66     &lt;query xmlns='jabber:iq:time'&gt;
  67         &lt;utc&gt;20020910T17:58:35&lt;/utc&gt;
  68         &lt;tz&gt;MDT&lt;/tz&gt;
  69         &lt;display&gt;Tue Sep 10 12:58:35 2002&lt;/display&gt;
  70     &lt;/query&gt;
  71 &lt;/iq&gt;</pre>
  72
  73 In order for this packet to be automatically mapped to the Time object listed in the
  74 providers file above, it must have the methods setUtc(String), setTz(String), and
  75 setDisplay(String). The introspection service will automatically try to convert the String
  76 value from the XML into a boolean, int, long, float, double, or Class depending on the
  77 type the IQ instance expects.<p>
  78
  79 <p class="subheader">PacketExtensionProvider</p>
  80
  81 Packet extension providers provide a pluggable system for
  82 packet extensions, which are child elements in a custom namespace
  83 of IQ, message and presence packets.
  84 Each extension provider is registered with an element name and namespace
  85 in the smack.providers file as in the following example:
  86
  87 <pre>
  88 &lt;?xml version="1.0"?&gt;
  89 &lt;smackProviders&gt;
  90     &lt;extensionProvider&gt;
  91         &lt;elementName&gt;x&lt;/elementName&gt;
  92         &lt;namespace&gt;jabber:iq:event&lt;/namespace&gt;
  93         &lt;className&gt;org.jivesoftware.smack.packet.MessageEvent&lt/className&gt;
  94     &lt;/extensionProvider&gt;
  95 &lt;/smackProviders&gt;</pre>
  96
  97 If multiple provider entries attempt to register to handle the same element
  98 name and namespace, the first entry loaded from the classpath will take
  99 precedence.<p>
 100
 101 Whenever a packet extension is found in a packet, parsing will
 102 be passed to the correct provider. Each provider can either implement the
 103 PacketExtensionProvider interface or be a standard Java Bean. In the
 104 former case, each extension provider is responsible for parsing the raw
 105 XML stream to contruct an object. In the latter case, bean introspection
 106 is used to try to automatically set the properties of the class using
 107 the values in the packet extension sub-element.<p>
 108
 109 When an extension provider is not registered for an element name and
 110 namespace combination, Smack will store all top-level elements of the
 111 sub-packet in DefaultPacketExtension object and then attach it to the packet.
 112
 113
 114 <br clear="all" /><br><br>
 115
 116 <div class="footer">
 117 Copyright &copy; Jive Software 2002-2008
 118 </div>
 119
 120 </body>
 121 </html>