No Description
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

xep-0075.xml 80KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819
  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd'
  3. [ <!ENTITY % ents SYSTEM "xep.ent"> %ents;
  4. <!ENTITY xmlrpc "XML-RPC<note><link url='http://www.xmlrpc.org/spec'>The XML-RPC Specification</link></note>">
  5. ]
  6. >
  7. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  8. <xep>
  9. <header>
  10. <title>Jabber Object Access Protocol (JOAP)</title>
  11. <abstract>The Jabber Object Access Protocol, or JOAP, defines a
  12. mechanism for creating Jabber-accessible object servers, and
  13. manipulating objects provided by those servers. It is intended
  14. for development of business applications with Jabber.</abstract>
  15. &LEGALNOTICE;
  16. <number>0075</number>
  17. <status>Deferred</status>
  18. <type>Standards Track</type>
  19. <sig>Standards</sig>
  20. <dependencies/>
  21. <supersedes/>
  22. <supersededby/>
  23. <shortname>N/A</shortname>
  24. <author>
  25. <firstname>Evan</firstname>
  26. <surname>Prodromou</surname>
  27. <email>evan@prodromou.san-francisco.ca.us</email>
  28. <jid>EvanProdromou@jabber.org</jid>
  29. </author>
  30. <revision>
  31. <version>0.3</version>
  32. <date>2003-05-22</date>
  33. <initials>esp</initials>
  34. <remark>For consistency, renamed hyphenated elements
  35. 'new-address' and 'return-type' to 'newAddress' and 'returnType'
  36. respectively. Added 'desc' element for human-readable
  37. descriptions to object servers and classes. Changed the
  38. 'writeable' [sic] attribute to the more correct
  39. 'writable'. Added experimental namespace recommendation in
  40. XMPP Registrar section.</remark>
  41. </revision>
  42. <revision>
  43. <version>0.2</version>
  44. <date>2003-03-05</date>
  45. <initials>esp</initials>
  46. <remark>Added a schema and DTD, a number of new examples, and
  47. ensured that all examples validate against the DTD and
  48. schema.</remark>
  49. </revision>
  50. <revision>
  51. <version>0.1</version>
  52. <date>2003-01-28</date>
  53. <initials>esp</initials>
  54. <remark>Initial version (unpublished).</remark>
  55. </revision>
  56. </header>
  57. <section1 topic='Introduction'>
  58. <p>This document defines the Jabber Object Access Protocol (JOAP)
  59. as an extension to the Jabber protocol. It outlines the
  60. addressing scheme and IQ stanzas that comprise the protocol as
  61. well as the data types that the protocol models. Example
  62. applications are discussed, as well as security
  63. considerations.</p>
  64. <p>Jabber has a number of attractive features that give it an
  65. advantage over existing frameworks for building multi-tier
  66. applications, such as the Simple Object Access Protocol (SOAP)
  67. or Java 2, Enterprise Edition (J2EE). Among these are:</p>
  68. <ul>
  69. <li><strong>Built-in authentication.</strong> All clients in the
  70. Jabber network must be authenticated with their server before
  71. sending messages to other Jabber entities. Inter-server
  72. communication requires additional authentication, in the form
  73. of dialback connections or other trust mechanisms. This
  74. ensures that, when a message is delivered to a JOAP object
  75. server, there is little doubt as to the authenticity of its
  76. originator.</li>
  77. <li><strong>Global namespace.</strong> Jabber allows namespacing
  78. of addresses according to domain names. This allows objects to
  79. be accessed globally, according to authorization rules.</li>
  80. <li><strong>An asynchronous messaging model.</strong> Jabber is
  81. built on a store-and-forward mechanism that allows a single
  82. client to send messages to multiple servers concurrently. Of
  83. course, synchronous messaging can be simulated on the client
  84. side.</li>
  85. <li><strong>Cross-enterprise messaging.</strong> Jabber is
  86. designed to allow cross-enterprise messaging. Using Jabber for
  87. multitier applications makes development of cross-enterprise
  88. systems as easy as intra-enterprise development.</li>
  89. <li><strong>Message routing.</strong> The architecture of Jabber
  90. is based on clients that connect to a local server, and then
  91. can send messages through that server to other clients,
  92. servers, or components. Topographically, this contrasts well
  93. with the one-to-one connections required with, for example,
  94. HTTP.</li>
  95. <li><strong>Factoring network connections out of
  96. scalability.</strong> Because messages in Jabber are routed,
  97. components need to maintain only one connection -- to their
  98. upstream Jabber server. This removes the number of network
  99. connections from the scalability equation for object
  100. servers.</li>
  101. <li><strong>Language independence.</strong> Jabber protocol
  102. implementations exist for Java, C, and C++ as well as a number
  103. of scripting languages such as Perl and Python.</li>
  104. <li><strong>Platform independence.</strong> The Jabber protocol
  105. is implemented on most major modern platforms.</li>
  106. </ul>
  107. <p>For existing Jabber development efforts, there are significant
  108. advantages to building applications within a JOAP
  109. framework. It should go without saying that, for developers creating
  110. business applications on top of Jabber, a uniform object access
  111. protocol provides significant advantage for cross-product
  112. integration.</p>
  113. <p>In addition, implementers of special-purpose components, such as
  114. multi-user chat servers or whiteboarding components, can use an
  115. object-server interface to allow fine-grained control of the
  116. implementations, especially where such control is not specified
  117. by the applicable Jabber protocol.</p>
  118. </section1>
  119. <section1 topic='Requirements'>
  120. <p>JOAP has the following design goals:</p>
  121. <ul>
  122. <li>Create a protocol for client programs to access object
  123. server components.</li>
  124. <li>Create a model for addressing object servers, classes, and
  125. instances.</li>
  126. <li>Define a language for manipulating data.</li>
  127. <li>Define a language for describing data structures.</li>
  128. <li>Maintain compatibility with &xep0009;.</li>
  129. <li>Make classes and instances directly addressable.</li>
  130. <li>Allow human- and programming-language independence.</li>
  131. <li>Allow easy dynamic mapping of JOAP classes to local classes
  132. in Perl, Python, and other dynamic languages.</li>
  133. </ul>
  134. <p>The following are non-goals:</p>
  135. <ul>
  136. <li>Enable object-oriented access to all parts of the Jabber
  137. network (e.g., clients, other components).</li>
  138. <li>Define a language for creating or altering classes on an
  139. object server.</li>
  140. <li>Define a language for describing or defining the
  141. authorization of given users for given objects.</li>
  142. <li>Define a programming interface between object servers and
  143. classes in those servers (like Enterprise Java Beans).</li>
  144. </ul>
  145. </section1>
  146. <section1 topic='Overview'>
  147. <p>The JOAP interface is made up of three key parts:</p>
  148. <ul>
  149. <li>A scheme for defining the addresses of object servers,
  150. classes, and instances (collectively known as
  151. "objects").</li>
  152. <li>A set of message stanzas in the <tt>jabber:iq:joap</tt>
  153. namespace for manipulating data in object servers, classes,
  154. and instances. The stanzas allow client programs to analyze
  155. the structure of objects, to read object attributes, to edit
  156. object attributes, to add new instances, to delete instances,
  157. and to search classes.</li>
  158. <li>An application of XEP-0009 for calling methods on
  159. objects.</li>
  160. </ul>
  161. </section1>
  162. <section1 topic='Entities in the JOAP Universe'>
  163. <p>This section describes the various entities in the JOAP
  164. universe. Some entities are directly addressable with Jabber IDs
  165. (JIDs), as described below. Others are not considered outside of
  166. their enclosing entities.</p>
  167. <section2 topic='Object Server Component'>
  168. <p>An object server component is a Jabber component that
  169. provides object services. It is addressed like any other
  170. Jabber component, i.e., with a DNS hostname or
  171. pseudo-hostname. Some examples would be:</p>
  172. <ul>
  173. <li><tt>payroll.example.com</tt> - A payroll application
  174. server.</li>
  175. <li><tt>jukebox.example.com</tt> - An MP3 jukebox server.</li>
  176. </ul>
  177. <p>An object server has zero or more attributes, methods, and
  178. classes.</p>
  179. </section2>
  180. <section2 topic='Class'>
  181. <p>A class is a category of object instances. It defines the
  182. structure and interface of these instances. Each class is
  183. addressed using the class name as the node identifier, and the
  184. object server as the domain identifier. Class names must
  185. conform to the node identifier restrictions defined for
  186. XMPP. Class names must also be unique, regardless of case,
  187. within an object server.</p>
  188. <p>For example:</p>
  189. <ul>
  190. <li><tt>Employee@payroll.example.com</tt> - An employee class
  191. at the payroll.example.com server.</li>
  192. <li><tt>Song@jukebox.example.net</tt> - A song class on the
  193. jukebox server.</li>
  194. <li><tt>Board@circuit-design.example.com</tt> - A class for
  195. circuit boards.</li>
  196. <li><tt>Board@surf-shop.example.net</tt> - A class for
  197. surfboards -- distinct from above class!</li>
  198. </ul>
  199. <p>Beside uniqueness and XMPP compliance, no further requirements are
  200. made on class names. However, good design suggests mnemonic names.</p>
  201. <p>Classes define the attributes and methods of their instances. In
  202. addition, they can have attributes and methods of their own. Finally,
  203. classes can have superclasses, which indicate an inheritance structure
  204. as well as implementation of a defined interface.</p>
  205. <p>JOAP allows for no relative addressing of classes. Classes
  206. are always referred to by their full address (node identifier
  207. plus domain identifier).</p>
  208. </section2>
  209. <section2 topic='Instance'>
  210. <p>An instance is a collection of data with identity, state, and
  211. behavior. Each instance is a member of a class, which defines the
  212. attributes (data) and methods (behavior) of the instance
  213. itself.</p>
  214. <p>An instance is addressed using the node plus server that identifies
  215. its class, as well as a unique string that occupies the resource
  216. identifier section of the Jabber ID. The resource is only unique over
  217. the space of the corresponding class. Some example instance addresses:</p>
  218. <ul>
  219. <li><tt>Room@hotel.example.com/103</tt> - Room 103 in the
  220. Example Hotel.</li>
  221. <li><tt>Element@periodic-table.example.net/103</tt> - Element
  222. 103 (rutherfordium) in the periodic table.</li>
  223. <li><tt>Employee@payroll.example.com/JohnSmith</tt> - An
  224. employee named "John Smith".</li>
  225. <li><tt>Customer@videorental.example.net/JohnSmith</tt> - A
  226. customer named "John Smith" (not necessarily the
  227. same person as the above employee!).</li>
  228. </ul>
  229. <p>Besides uniqueness within a class, and compliance with the
  230. rules for resource identifiers in the XMPP standard, there are
  231. no further requirements on instance identifiers in JOAP. In
  232. particular, the instance identifier is opaque -- that is, no
  233. further information about the state of the object can or
  234. should be discerned from the identifier. What visible part of
  235. the instance, if any, makes up the unique resource identifier
  236. is implementation dependent.</p>
  237. <p>That said, it is recommended that the instance identifier be
  238. persistent through the life of the instance. In addition, using
  239. mnemonic identifiers can greatly enhance the usability of JOAP
  240. objects.</p>
  241. <p>As with other resource identifiers, instance identifiers are
  242. case-sensitive.</p>
  243. <p>The instance identifier roughly corresponds to a primary key in a
  244. relational database, and for object servers that provide access to
  245. relational databases, it is recommended to use the primary key of a
  246. table as the instance identifier. For tables with a compound key, a
  247. comma (',') dash ('-'), or other non-alphanumeric character can be
  248. used to separate parts of the key for better readability. For
  249. example:</p>
  250. <ul>
  251. <li><tt>Date@calendar.example.net/2003-01-26</tt> -- The date
  252. January 26th, 2003.</li>
  253. <li><tt>City@canada.example.com/Montréal,QC</tt> -- The city
  254. of Montréal, in the province of Québec.</li>
  255. </ul>
  256. <p>JOAP allows for no relative addressing of
  257. instances. Instances are always referred to using their full
  258. address (node identifier plus domain identifier plus resource
  259. identifier).</p>
  260. </section2>
  261. <section2 topic='Attribute'>
  262. <p>An attribute is a unit of state that makes up part of an object
  263. server, instance, or class. Each attribute has a name and a
  264. type.</p>
  265. <p>Attribute names must be strings of characters containing only
  266. the characters [a-zA-Z0-9_]. The first character must be an
  267. underscore or alphabetic character. <note>This requirement is
  268. intended to allow easy mapping of attributes in JOAP to
  269. attributes of objects in client programming languages. The
  270. restriction is the lowest common denominator for variable
  271. names in most modern programming languages.</note></p>
  272. <p>Attributes cannot be addressed individually. Attributes are
  273. manipulated by sending JOAP messages to the object that owns
  274. them.</p>
  275. </section2>
  276. <section2 topic='Method'>
  277. <p>A method is a unit of behavior that makes up part of an
  278. object. Methods in JOAP are compatible with &xmlrpc;, as
  279. specified in &xep0009;. In particular, methods have a name, a
  280. return type, and 0 or more parameters, each of which has a
  281. type.</p>
  282. <p>The one exception to XML-RPC compatibility is that method
  283. names for JOAP are restricted to the characters
  284. [a-zA-z0-9_]. <note>This is to avoid conceptual mismatch in
  285. programming languages where the other three characters allowed
  286. by XML-RPC, namely ".", ":", and
  287. "/", are used to separate class or instance names
  288. from methods.</note></p>
  289. <p>Methods cannot be directly addressed using JOAP. Methods are
  290. described and executed by sending messages to the object
  291. server, class, or instance that owns them.</p>
  292. </section2>
  293. </section1>
  294. <section1 topic='JOAP Data Types'>
  295. <p>The range of JOAP data types is borrowed directly from
  296. XML-RPC.</p>
  297. <section2 topic='Scalar Types'>
  298. <p>The scalar types include the following:</p>
  299. <ul>
  300. <li><strong>int</strong> or <strong>i4</strong>: a 32-bit
  301. signed integer</li>
  302. <li><strong>boolean</strong>: a one-digit integer representing
  303. "true" (1) or "false" (0)</li>
  304. <li><strong>string</strong>: a string of characters</li>
  305. <li><strong>double</strong>: double-precision signed
  306. floating-point number</li>
  307. <li><strong>datetime.iso8601</strong>: a date value, in ISO
  308. 8601 format</li>
  309. <li><strong>base64</strong>: binary data, base64-encoded for
  310. transmission</li>
  311. </ul>
  312. </section2>
  313. <section2 topic='Instance Addresses'>
  314. <p>Instance addresses are a special type of string used for
  315. referring to instance objects. They can be passed as
  316. parameters to methods, or set as attribute values.</p>
  317. <p>If a value can contain an object instance, its type is the
  318. address of a class. The address of any object instance that is
  319. an instance of that class, or any of its subclasses, can be
  320. used in that value.</p>
  321. <p>For example, if <tt>Boxcar@trainset.example.com</tt> is a
  322. subclass of <tt>Car@trainset.example.com</tt>, then
  323. <tt>Boxcar@trainset.example.com/569</tt> can be used as a
  324. method parameter, or set as an attribute, where
  325. <tt>Car@trainset.example.com</tt> is the defined type.</p>
  326. <p>Because addresses are used for instance values, all methods
  327. involving instances are implicitly pass-by-reference. If a
  328. pass-by-value functionality is needed, a struct (see below)
  329. should be used instead.</p>
  330. <p>Note that attribute and method param types can use classes
  331. and instances from other object servers (that is, with
  332. different domain identifiers). For instance, an
  333. <tt>Employee@payroll.example.com</tt> class could have an
  334. attribute of type <tt>Job@hr.example.com</tt>.</p>
  335. </section2>
  336. <section2 topic='Compound Types'>
  337. <p>There are two compound types defined in XML-RPC.</p>
  338. <section3 topic='Arrays'>
  339. <p>An <em>array</em> is an ordered list of values. An array
  340. can contain values of any type, including other compound
  341. types.</p>
  342. <p>In JOAP, as with XML-RPC, it is not possible to address,
  343. set, or delete elements of an array. To set values in an
  344. array, the entire new array must be specified.</p>
  345. </section3>
  346. <section3 topic='Structs'>
  347. <p>A <em>struct</em> is a set of name-value pairs organized into
  348. a logical grouping. A struct can contain values of any type,
  349. including other compound types.</p>
  350. <p>In JOAP, as with XML-RPC, it is not possible to address,
  351. set, or delete elements of a struct. To set values in an
  352. struct, the entire new struct must be specified.</p>
  353. <p>Structs are useful mainly for groupings of data that do not
  354. have independent identity or behavior. Where an object
  355. needs identity or behavior, an instance should be used
  356. instead of a struct.</p>
  357. </section3>
  358. </section2>
  359. <section2 topic='Specifying Types'>
  360. <p>Types are specified by a string name of the type. This can be
  361. one of the XML-RPC types described above, or a class
  362. address.<note>Implementers can determine if a specified type
  363. is valid by checking it against a list of the XML-RPC
  364. types. If it does not match, it should be checked to see if
  365. matches the syntax for a class address (node identifier
  366. plus domain identifier). Otherwise, it is not a valid
  367. type.</note></p>
  368. </section2>
  369. </section1>
  370. <section1 topic='JOAP Stanzas'>
  371. <p>This section defines the Jabber stanzas that make up the JOAP
  372. protocol.</p>
  373. <p>Each stanza is an information query (IQ). Except for method
  374. calls, the stanzas are all in the 'jabber:iq:joap' namespace. Each
  375. of the following sections describes a stanza in that namespace,
  376. herein called a "verb". The verbs allow basic access
  377. to object servers, classes, and instances.</p>
  378. <p>Not all verbs can be sent to all JOAP entities. The appropriate JOAP
  379. entity a verb should be addressed to is noted under the description of
  380. the verb.</p>
  381. <section2 topic='&lt;describe&gt;'>
  382. <p>The &lt;describe&gt; verb requests the interface -- that is, methods,
  383. attributes, and classes -- of a given object server or class. The IQ
  384. type is "get".</p>
  385. <p>The &lt;describe&gt; verb is useful for creating wrapper
  386. classes in JOAP clients, either at runtime or at compile
  387. time. It can also be used for object browsers, or for client
  388. programs to ascertain that the interface they assume for an
  389. object is still valid.</p>
  390. <section3 topic='Targets'>
  391. <p>&lt;describe&gt; verbs can be sent to object servers, classes, and
  392. instances. Each will return different data.</p>
  393. <ul>
  394. <li>Object servers return zero or more descriptive texts,
  395. zero or more attribute definitions, zero or more method
  396. definitions, zero or more class names, and a
  397. timestamp.</li>
  398. <li>Classes return zero or more descriptive texts, zero or
  399. more attribute definitions, zero or more method
  400. definitions, and a timestamp.</li>
  401. <li>Instances return the exact results of sending the
  402. &lt;describe&gt; method to their class. This is for convenience
  403. only; it is preferable to send &lt;describe&gt; to the class
  404. directly.</li>
  405. </ul>
  406. </section3>
  407. <section3 topic='Descriptive Texts'>
  408. <p>Each object description can contain one or more strings of
  409. descriptive text. This is to indicate the
  410. purpose and usage of the object in human-readable form.</p>
  411. <p>Multiple descriptions are allowed in the hope that they
  412. will be used to describe the attribute in multiple
  413. languages (differentiated using the xml:lang
  414. attribute).</p>
  415. </section3>
  416. <section3 topic='Attribute Definitions'>
  417. <p>Attribute definitions have the following parts:</p>
  418. <ul>
  419. <li>A name, which is a legal attribute name as described
  420. above.</li>
  421. <li>A type, which is a legal JOAP type as described
  422. above.</li>
  423. <li>A flag indicating if the attribute is an attribute of the
  424. class itself, or of individual instances.</li>
  425. <li>A flag indicating if the attribute is writable.</li>
  426. <li>A flag indicating if the attribute is required.</li>
  427. <li>One or more strings of descriptive text, to indicate the
  428. purpose and usage of this attribute. Multiple
  429. descriptions are allowed in the hope that they will be
  430. used to describe the attribute in multiple languages
  431. (differentiated using the 'xml:lang' attribute).</li>
  432. </ul>
  433. <p>The attribute definitions returned to a client should
  434. include only attributes the user is authorized to access.</p>
  435. </section3>
  436. <section3 topic='Method Definitions'>
  437. <p>Method definitions have the following parts:</p>
  438. <ul>
  439. <li>A name, which is a legal method name as described
  440. above.</li>
  441. <li>A return type, which is a legal JOAP type as described
  442. above.</li>
  443. <li>A flag indicating if the method is a method of the class
  444. itself, or of individual instances.</li>
  445. <li>Zero or more parameters, each of which has a name, a
  446. type, and one or more strings of descriptive text.</li>
  447. <li>One or more strings of descriptive text, indicating the
  448. use and behavior of this method.</li>
  449. </ul>
  450. <p>The method definitions returned to a client should
  451. include only methods the user is authorized to access.</p>
  452. </section3>
  453. <section3 topic='Class References'>
  454. <p>Classes, in superclass definitions and object server
  455. interfaces, are always referred to by their full
  456. address.</p>
  457. </section3>
  458. <section3 topic='Timestamps'>
  459. <p>The timestamp is a date-time value in ISO 8601 format,
  460. UTC. The timestamp indicates the last time an interface was
  461. changed, if that information is available.</p>
  462. </section3>
  463. <section3 topic='Superclasses'>
  464. <p>The main point of describing the superclasses a class has
  465. is to allow clients to make typing distinctions: that is, to
  466. determine if a class presents a given interface, or may be
  467. provided as a parameter or attribute in another JOAP
  468. call.</p>
  469. <p>The list of superclasses given in a class description is
  470. flat, not hierarchical. No provision is made to
  471. indicate which of a class's superclasses are superclasses of
  472. each other, nor is there any implied precedence order in the
  473. order of the classes in the returned description.</p>
  474. <p>In addition, no provision is made to define which
  475. superclass actually implements any methods or attributes
  476. defined.</p>
  477. </section3>
  478. <section3 topic='Flattening'>
  479. <p>When a class receives a &lt;describe&gt; verb, it must
  480. return all its superclasses, including multiple
  481. ancestors. It must as well return all the attributes and
  482. methods that it responds to, including those defined in
  483. its superclasses. This is called a "flattened"
  484. description of the class. <note>Flattening the class
  485. interface reduces the need for making multiple
  486. "describe" verb calls just to find the interface
  487. for one class.</note></p>
  488. </section3>
  489. <section3 topic='Examples'>
  490. <p>The following examples illustrate the use of the &lt;describe&gt;
  491. verb. <note>All extended examples in this document refer
  492. to a particular object domain, based on a fictional model
  493. train set. A UML description of the object domain is
  494. available in Appendix D.</note></p>
  495. <p>To describe a server, the JOAP client sends this
  496. stanza.</p>
  497. <example caption='Describing An Object Server'><![CDATA[
  498. <iq type='get'
  499. id='joap_describe_1'
  500. from='Client@example.com'
  501. to='trainset.example.com'>
  502. <describe xmlns='jabber:iq:joap' />
  503. </iq>]]></example>
  504. <p>The object server returns this response:</p>
  505. <example caption='Description of an Object Server'><![CDATA[
  506. <iq type='result'
  507. id='joap_describe_1'
  508. from='trainset.example.com'
  509. to='Client@example.com'>
  510. <describe xmlns='jabber:iq:joap'>
  511. <desc xml:lang='en-US'>
  512. This server provides classes for managing a virtual
  513. remote train set.
  514. </desc>
  515. <attributeDescription writable='true'>
  516. <name>logLevel</name>
  517. <type>i4</type>
  518. <desc xml:lang='en-US'>Verbosity level for access logging.</desc>
  519. </attributeDescription>
  520. <methodDescription>
  521. <name>startLogging</name>
  522. <returnType>boolean</returnType>
  523. <desc xml:lang='en-US'>Start logging activity on this
  524. server. Returns true for success and false for an
  525. error.</desc>
  526. </methodDescription>
  527. <methodDescription>
  528. <name>stopLogging</name>
  529. <returnType>boolean</returnType>
  530. <desc xml:lang='en-US'>Stop logging activity on this
  531. server. Returns true for success and false for an
  532. error.</desc>
  533. </methodDescription>
  534. <class>Train@trainset.example.com</class>
  535. <class>Car@trainset.example.com</class>
  536. <class>Caboose@trainset.example.com</class>
  537. <class>Engine@trainset.example.com</class>
  538. <class>Boxcar@trainset.example.com</class>
  539. <class>PassengerCar@trainset.example.com</class>
  540. <class>Building@trainset.example.com</class>
  541. <class>TrackSegment@trainset.example.com</class>
  542. <class>Switch@trainset.example.com</class>
  543. <class>Station@trainset.example.com</class>
  544. <timestamp>2003-01-07T20:08:13Z</timestamp>
  545. </describe>
  546. </iq>]]></example>
  547. <p>To describe the <tt>Car@trainset.example.com</tt> class,
  548. the JOAP client sends this stanza to the class for
  549. boxcars.</p>
  550. <example caption='Describing a Class'><![CDATA[
  551. <iq type='get'
  552. id='joap_describe_2'
  553. from='Client@example.com'
  554. to='Boxcar@trainset.example.com' >
  555. <describe xmlns='jabber:iq:joap' />
  556. </iq>]]></example>
  557. <p>The class returns this stanza to the JOAP client.</p>
  558. <example caption='Description of a Class'><![CDATA[
  559. <iq type='result'
  560. id='joap_describe_2'
  561. from='Boxcar@trainset.example.com'
  562. to='Client@example.com'>
  563. <describe xmlns='jabber:iq:joap'>
  564. <desc xml:lang='en-US'>
  565. A Car in the trainset that can be used to ship cargo.
  566. </desc>
  567. <attributeDescription writable='false' required='true'>
  568. <name>trackingNumber</name>
  569. <type>i4</type>
  570. <desc xml:lang='en-US'>Tracking number for this car.</desc>
  571. </attributeDescription>
  572. <attributeDescription writable='true' required='true'>
  573. <name>contents</name>
  574. <type>string</type>
  575. <desc xml:lang='en-US'>Contents of the boxcar.</desc>
  576. </attributeDescription>
  577. <methodDescription allocation='class'>
  578. <name>nextTrackingNumber</name>
  579. <returnType>i4</returnType>
  580. <desc xml:lang='en-US'>The next available tracking number.</desc>
  581. </methodDescription>
  582. <superclass>Car@trainset.example.com</superclass>
  583. <timestamp>2003-01-07T20:08:13Z</timestamp>
  584. </describe>
  585. </iq>]]></example>
  586. <p>To describe an instance, the JOAP client sends this stanza
  587. to a particular track segment.</p>
  588. <example caption='Describing an Instance'><![CDATA[
  589. <iq type='get'
  590. id='joap_describe_3'
  591. from='Client@example.com'
  592. to='TrackSegment@trainset.example.com/134' >
  593. <describe xmlns='jabber:iq:joap' />
  594. </iq>
  595. ]]>
  596. </example>
  597. <p>The instance returns this stanza to the JOAP client.</p>
  598. <example caption='Description of an Instance'><![CDATA[
  599. <iq type='result'
  600. from='TrackSegment@trainset.example.com/134'
  601. to='Client@example.com'
  602. id='joap_describe_3'>
  603. <describe xmlns='jabber:iq:joap'>
  604. <desc xml:lang='en-US'>
  605. A length of track in the trainset which can be
  606. connected to a previous and next length of track.
  607. </desc>
  608. <attributeDescription>
  609. <name>previous</name>
  610. <type>TrackSegment@trainset.example.com</type>
  611. <desc>Previous segment of track.</desc>
  612. </attributeDescription>
  613. <attributeDescription>
  614. <name>next</name>
  615. <type>TrackSegment@trainset.example.com</type>
  616. <desc>Next segment of track.</desc>
  617. </attributeDescription>
  618. <timestamp>2003-01-07T20:08:13Z</timestamp>
  619. </describe>
  620. </iq>]]>
  621. </example>
  622. </section3>
  623. </section2>
  624. <section2 topic='&lt;read&gt;'>
  625. <p>The &lt;read&gt; verb allows clients to retrieve the values
  626. of attributes of an object server, class, or instance. The
  627. client can specify which attributes to return; if no
  628. attributes are specified, then all attributes are
  629. returned. <note>This allows clients to cheaply retrieve
  630. meta-information about an instance that may have exceptionally
  631. large data, such as bin64-encoded file data.</note></p>
  632. <p>The &lt;read&gt; verb uses the "get" IQ type.</p>
  633. <section3 topic='Timestamps'>
  634. <p>A timestamp, in ISO 8601 format, UTC, can be added to the
  635. results of a &lt;read&gt;. The timestamp indicates the last
  636. time any of an object's attribute values have changed (not
  637. just the requested ones). The timestamp can be used, for
  638. example, to implement object caching on the client side.</p>
  639. </section3>
  640. <section3 topic='Error Codes'>
  641. <p>The following are some common error codes may be generated
  642. in response to a &lt;read&gt; verb.</p>
  643. <ul>
  644. <li><strong>404 (Not Found)</strong>: The object addressed
  645. does not exists.</li>
  646. <li><strong>403 (Forbidden)</strong>: The user is not
  647. authorized to read attributes of this object, or not
  648. authorized to read the specified attributes of this
  649. object.</li>
  650. <li><strong>406 (Not Acceptable)</strong>: The client sent
  651. an &lt;read&gt; verb specifying attributes that are not
  652. defined for the class.</li>
  653. </ul>
  654. </section3>
  655. <section3 topic='Examples'>
  656. <p>This section gives some examples of using the &lt;read&gt;
  657. verb.</p>
  658. <p>A client would send the following stanza to an instance to
  659. read its attributes:</p>
  660. <example caption='Reading the Attributes of an
  661. Instance'><![CDATA[
  662. <iq type='get'
  663. id='joap_read_1'
  664. from='Client@example.com'
  665. to='Station@trainset.example.com/Paddington'>
  666. <read xmlns='jabber:iq:joap' />
  667. </iq>
  668. ]]>
  669. </example>
  670. <p>In return, the instance would send this stanza to the
  671. client:</p>
  672. <example caption='Attributes of an Instance'><![CDATA[
  673. <iq type='result'
  674. id='joap_read_1'
  675. from='Station@trainset.example.com/Paddington'
  676. to='Client@example.com'>
  677. <read xmlns='jabber:iq:joap'>
  678. <attribute>
  679. <name>name</name>
  680. <value>Paddington Station</value>
  681. </attribute>
  682. <attribute>
  683. <name>size</name>
  684. <value>
  685. <struct>
  686. <member>
  687. <name>length</name>
  688. <value><i4>4</i4></value>
  689. </member>
  690. <member>
  691. <name>width</name>
  692. <value><i4>3</i4></value>
  693. </member>
  694. </struct>
  695. </value>
  696. </attribute>
  697. <attribute>
  698. <name>previous</name>
  699. <value>TrackSegment@trainset.example.com/334</value>
  700. </attribute>
  701. <attribute>
  702. <name>next</name>
  703. <value>TrackSegment@trainset.example.com/271</value>
  704. </attribute>
  705. </read>
  706. </iq>]]>
  707. </example>
  708. <p>To read only specified attributes of an instance, the
  709. client would send this stanza:</p>
  710. <example caption='Reading Limited Attributes'><![CDATA[
  711. <iq type='get'
  712. id='joap_read_2'
  713. from='Client@example.com'
  714. to='Train@trainset.example.com/38'>
  715. <read xmlns='jabber:iq:joap'>
  716. <name>location</name>
  717. <name>cars</name>
  718. </read>
  719. </iq>
  720. ]]>
  721. </example>
  722. <p>In return, the instance would send this stanza to the
  723. client:</p>
  724. <example caption='Limited Attributes'><![CDATA[
  725. <iq type='result'
  726. id='joap_read_2'
  727. from='Train@trainset.example.com/38'
  728. to='Client@example.com'>
  729. <read xmlns='jabber:iq:joap'>
  730. <attribute>
  731. <name>location</name>
  732. <value>Station@trainset.example.com/Paddington</value>
  733. </attribute>
  734. <attribute>
  735. <name>cars</name>
  736. <value>
  737. <array>
  738. <data>
  739. <value>Engine@trainset.example.com/14</value>
  740. <value>PassengerCar@trainset.example.com/112</value>
  741. <value>PassengerCar@trainset.example.com/309</value>
  742. <value>BoxCar@trainset.example.com/212</value>
  743. <value>Caboose@trainset.example.com/9</value>
  744. </data>
  745. </array>
  746. </value>
  747. </attribute>
  748. </read>
  749. </iq>]]></example>
  750. </section3>
  751. </section2>
  752. <section2 topic='&lt;add&gt;'>
  753. <p>The &lt;add&gt; verb is used to create a new instance of a
  754. JOAP class. The verb is sent to the JOAP class, which returns
  755. the address of the newly-created instance.</p>
  756. <p>Within each &lt;add&gt; verb the client must include
  757. attribute values for each required, writable attribute of the
  758. class.</p>
  759. <p>The IQ is of type "set".</p>
  760. <section3 topic='Error Codes'>
  761. <p>The following are some common error codes may be generated
  762. in response to an &lt;add&gt; verb.</p>
  763. <ul>
  764. <li><strong>404 (Not Found)</strong>: The class for which an
  765. instance is to be instantiated does not exists.</li>
  766. <li><strong>403 (Forbidden)</strong>: The user is not
  767. authorized to instantiate an instance of this class.</li>
  768. <li><strong>405 (Not Allowed)</strong>: The client sent an
  769. &lt;add&gt; verb to something that isn't a class.</li>
  770. <li><strong>406 (Not Acceptable)</strong>: The client sent an
  771. &lt;add&gt; verb containing attributes that are not
  772. writable, or without all required, writable attributes,
  773. or with attributes that are not defined for the class, or
  774. with attribute values that are of the wrong type.</li>
  775. </ul>
  776. </section3>
  777. <section3 topic='Examples'>
  778. <p>To create a new PassengerCar, the client would send the
  779. following stanza to the PassengerCar class:</p>
  780. <example caption='Adding a New Instance'><![CDATA[
  781. <iq type='set'
  782. id='joap_add_1'
  783. to='PassengerCar@trainset.example.com'
  784. from='Client@example.com'>
  785. <add xmlns='jabber:iq:joap'>
  786. <attribute>
  787. <name>passengers</name>
  788. <value><i4>38</i4></value>
  789. </attribute>
  790. </add>
  791. </iq>]]></example>
  792. <p>The class would return the following response:</p>
  793. <example caption='A New Instance'><![CDATA[
  794. <iq type='result'
  795. id='joap_add_1'
  796. from='PassengerCar@trainset.example.com'
  797. to='Client@example.com'>
  798. <add xmlns='jabber:iq:joap'>
  799. <newAddress>PassengerCar@trainset.example.com/866</newAddress>
  800. </add>
  801. </iq>
  802. ]]></example>
  803. <p>Note that the class created a new instance identifier, 866,
  804. for the new instance. Further communications from the client
  805. would use the full instance address returned.</p>
  806. </section3>
  807. </section2>
  808. <section2 topic='&lt;edit&gt;'>
  809. <p>The &lt;edit&gt; verb is used to update the attributes of an
  810. object. The name and new value of each attribute that is to be
  811. updated is listed in the &lt;edit&gt; verb.</p>
  812. <p>The IQ is of type "set".</p>
  813. <p>Leaving a given attribute out of an &lt;edit&gt; verb does
  814. not indicate that the attribute should be set to an undefined
  815. or default value. The new values of attributes that are left
  816. out is implementation-dependent; in general, though, they
  817. should remain unchanged, if possible.</p>
  818. <section3 topic='Content in &lt;edit&gt; Results'>
  819. <p>If the results of an &lt;edit&gt; verb have content, it
  820. will contain the new address of the instance that was
  821. updated. The new address should be used henceforth by the
  822. client. <note>This is to allow updates that alter the unique
  823. key or attribute of an instance that determine its instance
  824. identifier.</note></p>
  825. </section3>
  826. <section3 topic='Error Codes'>
  827. <p>The following error codes may be generated in response to a
  828. &lt;edit&gt; verb.</p>
  829. <ul>
  830. <li><strong>404 (Not Found)</strong>: The object to be
  831. edited does not exists.</li>
  832. <li><strong>403 (Forbidden)</strong>: The user is not
  833. authorized to edit this object, or to change one of the
  834. attributes specified in the &lt;edit&gt; request.</li>
  835. <li><strong>406 (Not Acceptable)</strong>: The client sent
  836. an &lt;edit&gt; verb containing attributes that are not
  837. defined for the class, or with attribute values that are
  838. of the wrong type, or with attribute values that are
  839. outside the range for the attribute.</li>
  840. </ul>
  841. </section3>
  842. <section3 topic='Examples'>
  843. <p>To change the number of passengers in a PassengerCar, the
  844. client would send the following stanza to the instance:</p>
  845. <example caption='Editing an Instance'><![CDATA[
  846. <iq type='set'
  847. id='joap_edit_1'
  848. from='Client@example.com'
  849. to='PassengerCar@trainset.example.com/199'>
  850. <edit xmlns='jabber:iq:joap'>
  851. <attribute>
  852. <name>passengers</name>
  853. <value><i4>31</i4></value>
  854. </attribute>
  855. </edit>
  856. </iq>
  857. ]]></example>
  858. <p>The client would return the following stanza:</p>
  859. <example caption='Results of Editing an Instance'><![CDATA[
  860. <iq type='result'
  861. id='joap_edit_1'
  862. to='Client@example.com'
  863. from='PassengerCar@trainset.example.com/199'>
  864. <edit xmlns='jabber:iq:joap' />
  865. </iq>
  866. ]]></example>
  867. <p>If a client wanted to change the name of a Building, it
  868. would send the following stanza to the instance:</p>
  869. <example caption='Editing an Instance'><![CDATA[
  870. <iq type='set'
  871. id='joap_edit_2'
  872. from='Client@example.com'
  873. to='Building@trainset.example.com/JonesFamilyHome'>
  874. <edit xmlns='jabber:iq:joap'>
  875. <attribute>
  876. <name>name</name>
  877. <value>Smith Family Home</value>
  878. </attribute>
  879. </edit>
  880. </iq>
  881. ]]></example>
  882. <p>The results would be as follows:</p>
  883. <example caption='Results of Editing an Instance'><![CDATA[
  884. <iq type='result'
  885. id='joap_edit_2'
  886. to='Client@example.com'
  887. from='Building@trainset.example.com/JonesFamilyHome'>
  888. <edit xmlns='jabber:iq:joap'>
  889. <newAddress>Building@trainset.example.com/SmithFamilyHome</newAddress>
  890. </edit>
  891. </iq>
  892. ]]></example>
  893. <p>Note that the instance indentifier, and thus the instance
  894. address, of the instance has changed. The <tt>from</tt> part
  895. of the IQ, however, contains the old address.</p>
  896. </section3>
  897. </section2>
  898. <section2 topic='&lt;delete&gt;'>
  899. <p>The &lt;delete&gt; verb is used to delete an instance. The IQ
  900. is of type "set". The &lt;delete&gt; stanza has no
  901. sub-elements.</p>
  902. <p>Only instances can be deleted. Classes and object servers
  903. cannot be deleted. After an instance is deleted, it is no
  904. longer addressable.</p>
  905. <p>A given user may not be able to delete a particular
  906. instance.</p>
  907. <section3 topic='Error Codes'>
  908. <p>The following error codes may be generated in response to a
  909. &lt;delete&gt; verb.</p>
  910. <ul>
  911. <li><strong>404 (Not Found)</strong>: The instance to be
  912. deleted does not exists.</li>
  913. <li><strong>403 (Forbidden)</strong>: The user is not
  914. authorized to delete this instance.</li>
  915. <li><strong>405 (Not Allowed)</strong>: The client sent a
  916. &lt;delete&gt; verb to an object server or class.</li>
  917. </ul>
  918. </section3>
  919. <section3 topic='Examples'>
  920. <p>To delete an instance, a client would send the following
  921. stanza:</p>
  922. <example caption='Deleting an Instance'><![CDATA[
  923. <iq type='set'
  924. id='joap_delete_1'
  925. from='Client@example.com'
  926. to='Building@trainset.example.com/Courthouse'>
  927. <delete xmlns='jabber:iq:joap' />
  928. </iq>]]></example>
  929. <p>The instance would return this stanza:</p>
  930. <example caption='A Deleted Instance'><![CDATA[
  931. <iq type='result'
  932. id='joap_delete_1'
  933. to='Client@example.com'
  934. from='Building@trainset.example.com/Courthouse'>
  935. <delete xmlns='jabber:iq:joap' />
  936. </iq>]]></example>
  937. <p>If the user is not authorized to delete the instance, it
  938. would return this error:</p>
  939. <example caption='Error on Unauthorized Deletion'><![CDATA[
  940. <iq type='error'
  941. id='joap_delete_1'
  942. to='Client@example.com'
  943. from='Building@trainset.example.com/Courthouse'>
  944. <delete xmlns='jabber:iq:joap' />
  945. <error code='403'>
  946. You are not authorized to delete this instance.
  947. </error>
  948. </iq>]]></example>
  949. </section3>
  950. </section2>
  951. <section2 topic='&lt;search&gt;'>
  952. <p>The &lt;search&gt; verb allows rudimentary searching and
  953. listing of instances in a class. The IQ is of type
  954. "get".</p>
  955. <p>The client sends a &lt;search&gt; verb to the class,
  956. specifying the attributes that are search criteria and values
  957. to search for. The class returns a list of the addresses of
  958. matching instances.</p>
  959. <p>Multiple attributes are logically AND'd; that
  960. is, resulting instances must match <em>all</em> of the
  961. attribute values.</p>
  962. <section3 topic='Value Matching'>
  963. <p>How attribute values are specified for matching depends on
  964. the type of the attribute.</p>
  965. <ul>
  966. <li>For numeric types (&lt;int&gt;, &lt;double&gt;),
  967. &lt;boolean&gt;, and &lt;dateTime.iso8601&gt;, values match
  968. if they are exactly equal.</li>
  969. <li>For &lt;string&gt; types, a search value matches an
  970. attribute value if it is a case-dependent substring of
  971. that value. For example, "hat" will match
  972. "hat", "that", and "real-time
  973. chat server".</li>
  974. <li>For the &lt;base64&gt; type, a search value matches
  975. an attribute value if the base64-decoded value of the
  976. search value is an 8-bit clean substring of the
  977. base64-decoded attribute value. For example,
  978. "aGF0Cg==" ("hat") will match
  979. "cmVhbC10aW1lIGNoYXQK" ("real-time
  980. chat").</li>
  981. <li>For instance addresses, a search value matches an
  982. attribute value if they are exactly equal.</li>
  983. <li>For &lt;struct&gt; types, a search value matches an
  984. attribute value if each of its named members matches the
  985. corresponding named members in the attribute value, and
  986. has the same type.</li>
  987. <li>For &lt;array&gt; types, a search value matches an
  988. attribute value if each of its members matches the
  989. corresponding members in the attribute value, in order,
  990. and has the same type.</li>
  991. </ul>
  992. </section3>
  993. <section3 topic='Instances of Subclasses'>
  994. <p>Classes should return all instances of the class that are
  995. on the same object server (that is, which have the same
  996. domain identifier in their address) and that match the search
  997. criteria. This includes instances of subclasses of the
  998. class.</p>
  999. <p>Whether a class returns instances of subclasses that reside
  1000. on other object servers is implementation-dependent.
  1001. <note>This caveat is to allow different types of subclassing
  1002. policies. Classes that define a well-known, standard
  1003. interface -- for example, a class defined by a standards
  1004. organization -- would probably not be "aware" of
  1005. all instances of that class. However, it is conceivable to
  1006. have a multi-tier business application where the object
  1007. servers did know about other servers, their classes, and
  1008. their instances.</note></p>
  1009. <p>Classes cannot be searched on attributes that are defined
  1010. only in subclasses; for example, a search for the attribute
  1011. "contents" sent to the
  1012. <tt>Car@trainset.example.com</tt> class should result in a
  1013. <tt>406 (Not Acceptable)</tt> error.</p>
  1014. </section3>
  1015. <section3 topic='Empty &lt;search&gt;'>
  1016. <p>The semantics of an empty &lt;search&gt; verb is to request
  1017. <em>all</em> instances of a class. This provides a listing
  1018. or browsing functionality.</p>
  1019. </section3>
  1020. <section3 topic='Error Codes'>
  1021. <p>The following error codes may be generated in response to a
  1022. &lt;search&gt; verb.</p>
  1023. <ul>
  1024. <li><strong>404 (Not Found)</strong>: The class to be
  1025. searched does not exists.</li>
  1026. <li><strong>403 (Forbidden)</strong>: The user is not
  1027. authorized to search this class.</li>
  1028. <li><strong>405 (Not Allowed)</strong>: The client sent a
  1029. &lt;search&gt; verb to an object server or instance.</li>
  1030. <li><strong>406 (Not Acceptable)</strong>: The client sent
  1031. an &lt;search&gt; verb containing attributes that are not
  1032. defined for the class, or with attribute values that are
  1033. of the wrong type.</li>
  1034. </ul>
  1035. </section3>
  1036. <section3 topic='Examples'>
  1037. <p>To search for Boxcar instances carrying coal, the client
  1038. would send the following stanza to the Boxcar class:</p>
  1039. <example caption='Searching for Instances'><![CDATA[
  1040. <iq type='get'
  1041. id='joap_search_1'
  1042. from='Client@example.com'
  1043. to='Boxcar@trainset.example.com'>
  1044. <search xmlns='jabber:iq:joap'>
  1045. <attribute>
  1046. <name>contents</name>
  1047. <value><string>coal</string></value>
  1048. </attribute>
  1049. </search>
  1050. </iq>]]></example>
  1051. <p>The Boxcar class would return a list of all matching
  1052. instances:</p>
  1053. <example caption='Search Results'><![CDATA[
  1054. <iq type='result'
  1055. id='joap_search_1'
  1056. from='Boxcar@trainset.example.com'
  1057. to='Client@example.com'>
  1058. <search xmlns='jabber:iq:joap'>
  1059. <item>Boxcar@trainset.example.com/195</item>
  1060. <item>Boxcar@trainset.example.com/35</item>
  1061. <item>Boxcar@trainset.example.com/681</item>
  1062. </search>
  1063. </iq>]]></example>
  1064. <p>To get a list of all Building instances, the client would
  1065. send an empty &lt;search&gt; verb, as follows:</p>
  1066. <example caption='Listing All Instances of a Class'><![CDATA[
  1067. <iq type='get'
  1068. id='joap_search_2'
  1069. from='Client@example.com'
  1070. to='Building@trainset.example.com'>
  1071. <search xmlns='jabber:iq:joap' />
  1072. </iq>]]></example>
  1073. <p>The Building class would return the following stanza:</p>
  1074. <example caption='List Results'><![CDATA[
  1075. <iq type='result'
  1076. id='joap_search_2'
  1077. from='Building@trainset.example.com'
  1078. to='Client@example.com'>
  1079. <search xmlns='jabber:iq:joap'>
  1080. <item>Building@trainset.example.com/Courthouse</item>
  1081. <item>Station@trainset.example.com/Paddington</item>
  1082. <item>Station@trainset.example.com/GareDeLyon</item>
  1083. <item>Building@trainset.example.com/SmithFamilyHome</item>
  1084. </search>
  1085. </iq>]]></example>
  1086. <p>Note that the class returns instances of subclasses, as
  1087. well as direct instances of the class.</p>
  1088. </section3>
  1089. </section2>
  1090. <section2 topic='Method Calls'>
  1091. <p>Method calls in JOAP are simply XML-RPC calls, as defined in
  1092. XEP-0009.<note>XEP-0009 leaves some open questions as to use
  1093. of widely-defined extensions to the XML-RPC standard, such as
  1094. the &lt;nil&gt; type.</note> To call a method
  1095. on an object, the client simply sends an XML-RPC message to that
  1096. object. Method calls must match the parameters as defined in
  1097. the method definition returned by the &lt;describe&gt;
  1098. verb.</p>
  1099. <p>Method names must be the exact method name as returned by
  1100. &lt;describe&gt;. No class or instance identifier prefix (with
  1101. "." or ":") is used.</p>
  1102. <p>Note, also, that the addressee of the method call, that is,
  1103. the object that defines the method, is not specified as a
  1104. parameter of the method, as it is in some programming
  1105. languages. The addressee of the method is implicit in the
  1106. address to which the method was sent.</p>
  1107. <section3 topic='Examples'>
  1108. <p>To start the event log on the train set server, the client
  1109. would send the following stanza:</p>
  1110. <example caption='Method Call on an Object Server'><![CDATA[
  1111. <iq type='set'
  1112. id='joap_xmlrpc_1'
  1113. from='Client@example.com'
  1114. to='trainset.example.com'>
  1115. <query xmlns='jabber:iq:rpc'>
  1116. <methodCall>
  1117. <methodName>startLogging</methodName>
  1118. </methodCall>
  1119. </query>
  1120. </iq>]]></example>
  1121. <p>The object server would respond with the following results:</p>
  1122. <example caption='Method Call on an Object Server'><![CDATA[
  1123. <iq type='result'
  1124. id='joap_xmlrpc_1'
  1125. to='Client@example.com'
  1126. from='trainset.example.com'>
  1127. <query xmlns='jabber:iq:rpc'>
  1128. <methodResponse>
  1129. <params>
  1130. <param>
  1131. <value><boolean>1</boolean></value>
  1132. </param>
  1133. </params>
  1134. </methodResponse>
  1135. </query>
  1136. </iq>]]></example>
  1137. <p>To retrieve the next available Car tracking number, the
  1138. client would send the following stanza to the Car class:</p>
  1139. <example caption='Method Call on a Class'><![CDATA[
  1140. <iq type='set'
  1141. id='joap_xmlrpc_2'
  1142. from='Client@example.com'
  1143. to='Car@trainset.example.com'>
  1144. <query xmlns='jabber:iq:rpc'>
  1145. <methodCall>
  1146. <methodName>nextTrackingNumber</methodName>
  1147. </methodCall>
  1148. </query>
  1149. </iq>]]></example>
  1150. <p>The class would respond with the following results:</p>
  1151. <example caption='Results of a Class Method Call'><![CDATA[
  1152. <iq type='result'
  1153. id='joap_xmlrpc_2'
  1154. to='Client@example.com'
  1155. from='Car@trainset.example.com'>
  1156. <query xmlns='jabber:iq:rpc'>
  1157. <methodResponse>
  1158. <params>
  1159. <param>
  1160. <value><i4>909</i4></value>
  1161. </param>
  1162. </params>
  1163. </methodResponse>
  1164. </query>
  1165. </iq>]]></example>
  1166. <p>To make a Switch change to a different track segment, the
  1167. client would send the following stanza to the instance:</p>
  1168. <example caption='Method Call on an Instance'><![CDATA[
  1169. <iq type='set'
  1170. id='joap_xmlrpc_3'
  1171. from='Client@example.com'
  1172. to='Switch@trainset.example.com/981'>
  1173. <query xmlns='jabber:iq:rpc'>
  1174. <methodCall>
  1175. <methodName>switchTo</methodName>
  1176. <params>
  1177. <param>
  1178. <value>TrackSegment@trainset.example.com/119</value>
  1179. </param>
  1180. </params>
  1181. </methodCall>
  1182. </query>
  1183. </iq>]]></example>
  1184. <p>The instance would respond with the following results:</p>
  1185. <example caption='Results of an Instance Method Call'><![CDATA[
  1186. <iq type='result'
  1187. id='joap_xmlrpc_3'
  1188. from='Switch@trainset.example.com/981'
  1189. to='Client@example.com'>
  1190. <query xmlns='jabber:iq:rpc'>
  1191. <methodResponse>
  1192. <params>
  1193. <param>
  1194. <value><boolean>1</boolean></value>
  1195. </param>
  1196. </params>
  1197. </methodResponse>
  1198. </query>
  1199. </iq>]]></example>
  1200. </section3>
  1201. </section2>
  1202. </section1>
  1203. <section1 topic='Potential Applications'>
  1204. <section2 topic='Application Server'>
  1205. <p>A simple application server can be provided using JOAP. This is merely
  1206. the degenerate case of an object server that provides only methods and
  1207. attributes, with no classes.</p>
  1208. </section2>
  1209. <section2 topic='Relational Database Interface'>
  1210. <p>A more complex example would be an interface to a relational database
  1211. server, such as Oracle, PostgreSQL, or mySQL. The object server would
  1212. represent a single database within the database server. Each table in
  1213. the database would be represented by a class with no class attributes
  1214. or methods. Each row in the database would be an instance of its
  1215. table's class, with attributes but no methods.</p>
  1216. </section2>
  1217. <section2 topic='N-Tier Application'>
  1218. <p>A distributed n-tier application can be built fairly directly
  1219. with JOAP. N-tier applications are usually defined as having
  1220. three main segments:</p>
  1221. <ul>
  1222. <li>A user-interface segment</li>
  1223. <li>A business-object segment, defining objects with business
  1224. rules encoded into their behavior</li>
  1225. <li>A data-storage segment, handling basic storage of
  1226. relatively unintelligent objects</li>
  1227. </ul>
  1228. <p>With JOAP, application developers can create the last two
  1229. segments with a JOAP interface. User-interface clients can use
  1230. JOAP to access and manipulate the business objects in a
  1231. business object server. In turn, the business objects can use
  1232. JOAP to manipulate underlying database objects in the data
  1233. storage layer (perhaps implemented using a relational database
  1234. interface, as defined above).</p>
  1235. </section2>
  1236. <section2 topic='Jabber Component Controller'>
  1237. <p>Jabber protocols typically define a base set of functionality
  1238. for a component to provide. Implementers often want to provide
  1239. specialized, fine-grained control of the component that is not
  1240. part of the core functionality of a component. For example,
  1241. the implementer may wish to allow administrators to get
  1242. metrics on a component, enable or review logs, note error
  1243. situations, or configure the component remotely.<note>Most
  1244. Jabber components currently define Web interfaces, or
  1245. command-line scripts, to perform this kind of
  1246. control.</note></p>
  1247. <p>A component can provide an additional JOAP interface, along
  1248. with its regular protocol-specific interface, to enable this
  1249. kind of control functionality. Implementers can in this way
  1250. provide implementation-specific functionality in an open
  1251. way.</p>
  1252. <p>For example, if <tt>conference.example.com</tt> is
  1253. a MUC component, <tt>control.conference.example.com</tt> might
  1254. be a JOAP component with access to the internal data
  1255. structures of the MUC component. A conference room addressed
  1256. in the MUC component as
  1257. <tt>ModelTrains@conference.example.com</tt> might be addressed
  1258. in the JOAP component as
  1259. <tt>Room@control.conference.example.com/ModelTrains</tt>.</p>
  1260. </section2>
  1261. <section2 topic='Distributed Object System Gateway'>
  1262. <p>There are a number of existing distributed object systems,
  1263. such as SOAP, CORBA, distributed OLE, Enterprise Java Beans,
  1264. etc.</p>
  1265. <p>It would be reasonable to create gateways for these object
  1266. systems or object servers implementing their protocols using
  1267. JOAP. JOAP could also be used to allow disparate object
  1268. systems to communicate through a common protocol.</p>
  1269. </section2>
  1270. </section1>
  1271. <section1 topic='Implementation Notes'>
  1272. <p>To follow.</p>
  1273. </section1>
  1274. <section1 topic='Security Considerations'>
  1275. <p>This section describes some security considerations for
  1276. implementers of JOAP.</p>
  1277. <section2 topic='Authentication'>
  1278. <p>No provision is made for authentication of users to the
  1279. object server. Jabber users authenticate to a login server
  1280. before they are able to send any Jabber stanzas.</p>
  1281. </section2>
  1282. <section2 topic='Authorization'>
  1283. <p>Authorization for users to access and manipulate objects and
  1284. attributes in JOAP is fine-grained; object servers can return
  1285. error codes to indicate a lack of authorization for any given
  1286. attribute, object, or method.</p>
  1287. <p>No provision is made to define a user's authorization for an
  1288. object, attribute, or method. Implicit authorization is
  1289. outlined with the results of the &lt;describe&gt; verb.</p>
  1290. <ul>
  1291. <li>For attributes, if a user is unauthorized to &lt;read&gt; the
  1292. attribute, the object server should not return a definition of
  1293. the attribute in the &lt;describe&gt; results.</li>
  1294. <li>If a user is unauthorized to &lt;edit&gt; an attribute, the
  1295. object server should note that the the attribute is not
  1296. writable in the &lt;describe&gt; results.</li>
  1297. <li>If a user is unauthorized to execute a method, the object
  1298. server should not return a definition of the attribute in
  1299. the &lt;describe&gt; results.</li>
  1300. <li>For classes that the user is not allowed to access at all,
  1301. the object server should not return a reference to that
  1302. class in the &lt;describe&gt; results for the object
  1303. server.</li>
  1304. <li>For instances that the user is not allowed to access at
  1305. all, the object server should not return references to that
  1306. instance in &lt;search&gt; results.</li>
  1307. </ul>
  1308. </section2>
  1309. <section2 topic='Privacy and Confidentiality'>
  1310. <p>No provision is made in the JOAP protocol for providing
  1311. privacy and confidentiality in JOAP conversations. This is
  1312. left up to existing, more general Jabber protocols and
  1313. extensions.</p>
  1314. <p>Confidentiality from external, non-Jabber observers can be
  1315. obtained using transport-layer security (TLS) in all legs of
  1316. the Jabber path -- from client to server to (potentially)
  1317. another server to the object server component.</p>
  1318. <p>Maintaining confidentiality against observers in the Jabber
  1319. pathway -- for example, servers relaying JOAP stanzas --
  1320. requires using end-to-end encryption.</p>
  1321. <p>Due to the nature of the JOAP addressing scheme, however,
  1322. perfect confidentiality cannot be preserved. Even if the
  1323. contents of an IQ packet are encrypted, the address of the
  1324. object the packet is sent to -- e.g.,
  1325. <tt>Tips@whistleblower.example.org/NuclearRegulatoryInfractions</tt>
  1326. -- will reveal some information about the JOAP
  1327. conversation which could be harmful to the user.</p>
  1328. </section2>
  1329. </section1>
  1330. <section1 topic='IANA Considerations'>
  1331. <p>This document requires no interaction with the IANA.</p>
  1332. </section1>
  1333. <section1 topic='XMPP Registrar Considerations'>
  1334. <p>This protocol defines one new namespace, 'jabber:iq:joap'.</p>
  1335. <p>Experimental implementations of this protocol should use the
  1336. namespace '<tt>http://www.xmpp.org/extensions/xep-0075.html#0.3</tt>' to
  1337. avoid conflicts with future versions.</p>
  1338. </section1>
  1339. <section1 topic='Future Considerations'>
  1340. <ul>
  1341. <li>The presence mechanism provided by Jabber is currently not
  1342. integrated into the JOAP protocol. It would be relatively
  1343. easy to incorporate an observation mechanism, based on
  1344. presence, that would enable JOAP clients to request state
  1345. updates on JOAP instances. It is currently an open question
  1346. as to whether this would be genuinely useful, or merely a
  1347. "gee-whiz" add-on that needlessly complicates
  1348. implementation of the JOAP protocol.</li>
  1349. <li>More sophisticated distributed object protocol mechanisms,
  1350. such as transactions, are not addressed in this
  1351. specification.</li>
  1352. <li>The JOAP addressing mechanism restricts the type of Jabber
  1353. entity that can act as an object server. A Jabber instant
  1354. messaging client, for example, is normally addressed with
  1355. username and resource, such as
  1356. 'AJabberUser@example.com/Home'. This address has no place
  1357. to hang the class and instance identifiers to allow
  1358. JOAP interactions.</li>
  1359. <li>Additionally, the JOAP addressing mechanism inhibits
  1360. letting components that already use the node and resource
  1361. identifier parts of their addresses, such as multi-user
  1362. chat (MUC) services. This restriction can be worked around by
  1363. providing corresponding JOAP components for existing Jabber
  1364. components.</li>
  1365. <li>An additional type for object references may be called
  1366. for.</li>
  1367. <li>The addition of the widely used &lt;nil&gt; XML-RPC data
  1368. type may be called for.</li>
  1369. <li>Searching is fairly rudimentary; a full boolean logic (and,
  1370. or, not) may be necessary to provide rich searching.</li>
  1371. <li>There is no indication in class descriptions of the
  1372. inheritance hierarchy of the class, or which superclass's
  1373. implementation of a method the class may use. This is an
  1374. implementation decision, and it seems counterproductive to
  1375. force any given inheritance method on the implementer.</li>
  1376. <li>Some functionality will be expensive using JOAP. An example
  1377. might be finding all Cars in a Train and adding them to
  1378. another Train. In our example, this would require one IQ to
  1379. get the train's cars, and N many other IQs to update each
  1380. Car. A batching mechanism -- being able to send multiple
  1381. updates in one IQ message -- would make this somewhat less
  1382. chatty. However, this functionality may be better addressed by
  1383. a global Jabber batching mechanism, rather than
  1384. special-purpose batching just for JOAP.</li>
  1385. <li>A more appropriate term than &lt;verb&gt; may be necessary
  1386. to describe the different types of IQs that make up the JOAP
  1387. namespace.</li>
  1388. <li>The names of the verbs come from the so-called basic READ
  1389. data-manipulation functions: read, edit, add, delete. A more
  1390. SQL-oriented set of names might be SELECT, UPDATE, INSERT,
  1391. DELETE. A set of names from C-related object languages would
  1392. be get, set, new, destroy or delete.</li>
  1393. <li>No mechanism is provided to describe the range of an
  1394. attribute. For example, if an attribute can only be an integer
  1395. less than 10, or a string in the set {'open', 'closed'}, there
  1396. is no allowance for describing this in JOAP.</li>
  1397. <li>Currently, <tt>struct</tt> and <tt>array</tt> attributes and
  1398. parameters are described just with the "struct" and
  1399. "array" types, and no definition is given of their
  1400. parts' types, names, or semantics. It may be valuable to
  1401. expand JOAP type descriptions to also describe the members of
  1402. a <tt>struct</tt> or <tt>array</tt>.</li>
  1403. </ul>
  1404. </section1>
  1405. <section1 topic='Appendix A: Glossary'>
  1406. <p>The following glossary collects some definitions of terms used
  1407. in this document.</p>
  1408. <dl>
  1409. <di><dt>Object services</dt><dd>Modelling an object or
  1410. collection of objects, and providing an interface to
  1411. manipulate those objects to other entities.</dd></di>
  1412. <di><dt>Object server</dt><dd>A Jabber component that
  1413. provides object services.</dd></di>
  1414. <di><dt>Class</dt><dd>A category of object
  1415. instances that defines their structure and interface.</dd></di>
  1416. <di><dt>Instance</dt><dd>A collection of
  1417. data with identity (address), state (attributes), and
  1418. behavior (methods).</dd></di>
  1419. <di><dt>Attribute</dt><dd>A unit of state that makes up
  1420. part of an object server, instance, or class.</dd></di>
  1421. <di><dt>Method</dt><dd>A unit of behavior.</dd></di>
  1422. <di><dt>Object</dt><dd>An object server, class, or
  1423. instance.</dd></di>
  1424. <di><dt>User</dt><dd>A person or process that accesses
  1425. object services through JOAP.</dd></di>
  1426. <di><dt>Client</dt><dd>The software or agent a user
  1427. employs to access object services through JOAP.</dd></di>
  1428. <di><dt>Instance address</dt><dd>The full JID of an
  1429. instance, e.g.,
  1430. <tt>Train@trainset.example.com/OrangeBlossomSpecial</tt>.</dd></di>
  1431. <di><dt>Instance identifier</dt><dd>The resource
  1432. identifier part of an instance address. For example, in
  1433. <tt>Train@trainset.example.com/OrangeBlossomSpecial</tt>, the
  1434. instance identifier is <tt>OrangeBlossomSpecial</tt>.</dd></di>
  1435. <di><dt>Class address</dt><dd>The full JID of a class,
  1436. e.g., <tt>Switch@trainset.example.com</tt>.</dd></di>
  1437. <di><dt>Class identifier</dt><dd>The node identifier part
  1438. of a class address. For example, in
  1439. <tt>Switch@trainset.example.com</tt>, the class identifier is
  1440. <tt>Switch</tt></dd></di>
  1441. <di><dt>Authentication</dt><dd>The act of determining
  1442. that a user is who they say they are. In the Jabber world, this
  1443. is done at login time.</dd></di>
  1444. <di><dt>Authorization</dt><dd>The act of determining
  1445. whether a given user has the right to execute a particular
  1446. action.</dd></di>
  1447. </dl>
  1448. </section1>
  1449. <section1 topic='Appendix B: JOAP XML Schema'>
  1450. <p>The following is an XML Schema for JOAP.</p>
  1451. <code><![CDATA[
  1452. <?xml version='1.0' encoding='UTF-8'?>
  1453. <schema xmlns='http://www.w3.org/2001/XMLSchema'
  1454. xmlns:joap='jabber:iq:joap'
  1455. targetNamespace='jabber:iq:joap'
  1456. elementFormDefault='qualified'
  1457. attributeFormDefault='unqualified'>
  1458. <element name='describe'>
  1459. <complexType>
  1460. <choice>
  1461. <group ref='joap:DescribeRequest' />
  1462. <group ref='joap:DescribeResponse' />
  1463. </choice>
  1464. </complexType>
  1465. </element>
  1466. <element name='read'>
  1467. <complexType>
  1468. <choice>
  1469. <group ref='joap:ReadRequest' />
  1470. <group ref='joap:ReadResponse' />
  1471. </choice>
  1472. </complexType>
  1473. </element>
  1474. <element name='edit'>
  1475. <complexType>
  1476. <choice>
  1477. <group ref='joap:EditRequest' />
  1478. <group ref='joap:EditResponse' />
  1479. </choice>
  1480. </complexType>
  1481. </element>
  1482. <element name='add'>
  1483. <complexType>
  1484. <choice>
  1485. <group ref='joap:AddRequest' />
  1486. <group ref='joap:AddResponse' />
  1487. </choice>
  1488. </complexType>
  1489. </element>
  1490. <element name='delete'>
  1491. <complexType>
  1492. <choice>
  1493. <group ref='joap:DeleteRequest' />
  1494. <group ref='joap:DeleteResponse' />
  1495. </choice>
  1496. </complexType>
  1497. </element>
  1498. <element name='search'>
  1499. <complexType>
  1500. <choice>
  1501. <group ref='joap:SearchRequest' />
  1502. <group ref='joap:SearchResponse' />
  1503. </choice>
  1504. </complexType>
  1505. </element>
  1506. <group name='DescribeRequest'>
  1507. <sequence /> <!-- empty -->
  1508. </group>
  1509. <group name='DescribeResponse'>
  1510. <sequence>
  1511. <element name='desc' type='joap:Description'
  1512. minOccurs='0' maxOccurs='unbounded' />
  1513. <element name='attributeDescription' type='joap:AttributeDescription'
  1514. minOccurs='0' maxOccurs='unbounded' />
  1515. <element name='methodDescription' type='joap:MethodDescription'
  1516. minOccurs='0' maxOccurs='unbounded' />
  1517. <choice>
  1518. <element name='superclass' type='joap:ClassAddress'
  1519. minOccurs='0' maxOccurs='unbounded' />
  1520. <element name='class' type='joap:ClassAddress'
  1521. minOccurs='0' maxOccurs='unbounded' />
  1522. </choice>
  1523. <element name='timestamp' type='joap:Timestamp'
  1524. minOccurs='0' maxOccurs='1' />
  1525. </sequence>
  1526. </group>
  1527. <group name='ReadRequest'>
  1528. <sequence>
  1529. <element name='name' type='joap:JOAPName'
  1530. minOccurs='0' maxOccurs='unbounded' />
  1531. </sequence>
  1532. </group>
  1533. <group name='ReadResponse'>
  1534. <sequence>
  1535. <element name='attribute' type='joap:Attribute'
  1536. minOccurs='0' maxOccurs='unbounded' />
  1537. <element name='timestamp' type='joap:Timestamp'
  1538. minOccurs='0' maxOccurs='1' />
  1539. </sequence>
  1540. </group>
  1541. <group name='EditRequest'>
  1542. <sequence>
  1543. <element name='attribute' type='joap:Attribute'
  1544. minOccurs='0' maxOccurs='unbounded' />
  1545. </sequence>
  1546. </group>
  1547. <group name='EditResponse'>
  1548. <sequence>
  1549. <element name='newAddress' type='joap:InstanceAddress'
  1550. minOccurs='0' maxOccurs='1' />
  1551. </sequence>
  1552. </group>
  1553. <group name='AddRequest'>
  1554. <sequence>
  1555. <element name='attribute' type='joap:Attribute'
  1556. minOccurs='0' maxOccurs='unbounded' />
  1557. </sequence>
  1558. </group>
  1559. <group name='AddResponse'>
  1560. <sequence>
  1561. <element name='newAddress' type='joap:InstanceAddress'
  1562. minOccurs='1' maxOccurs='1' />
  1563. </sequence>
  1564. </group>
  1565. <group name='DeleteRequest'>
  1566. <sequence /> <!-- empty -->
  1567. </group>
  1568. <group name='DeleteResponse'>
  1569. <sequence /> <!-- empty -->
  1570. </group>
  1571. <group name='SearchRequest'>
  1572. <sequence>
  1573. <element name='attribute' type='joap:Attribute'
  1574. minOccurs='0' maxOccurs='unbounded' />
  1575. </sequence>
  1576. </group>
  1577. <group name='SearchResponse'>
  1578. <sequence>
  1579. <element name='item' type='joap:InstanceAddress'
  1580. minOccurs='0' maxOccurs='unbounded' />
  1581. </sequence>
  1582. </group>
  1583. <complexType name='Attribute'>
  1584. <sequence>
  1585. <element name='name' type='joap:JOAPName'
  1586. minOccurs='1' maxOccurs='1' />
  1587. <element name='value' type='joap:JOAPValue'
  1588. minOccurs='1' maxOccurs='1' />
  1589. </sequence>
  1590. </complexType>
  1591. <complexType name='AttributeDescription'>
  1592. <!-- XXX: enforce name rules -->
  1593. <sequence>
  1594. <element name='name' type='joap:JOAPName'
  1595. minOccurs='1' maxOccurs='1' />
  1596. <element name='type' type='joap:JOAPType'
  1597. minOccurs='1' maxOccurs='1' />
  1598. <element name='desc' type='joap:Description'
  1599. minOccurs='0' maxOccurs='unbounded' />
  1600. </sequence>
  1601. <attribute name='required' type='boolean' default='false' />
  1602. <attribute name='writable' type='boolean' default='false' />
  1603. <attribute name='allocation' type='joap:Allocation' />
  1604. </complexType>
  1605. <complexType name='MethodDescription'>
  1606. <sequence>
  1607. <element name='name' type='joap:JOAPName'
  1608. minOccurs='1' maxOccurs='1' />
  1609. <element name='returnType' type='joap:JOAPType'
  1610. minOccurs='1' maxOccurs='1'/>
  1611. <element name='params' minOccurs='0' maxOccurs='1'>
  1612. <complexType>
  1613. <sequence>
  1614. <element name='param' minOccurs='0' maxOccurs='unbounded' >
  1615. <complexType>
  1616. <sequence>
  1617. <element name='name' type='joap:JOAPName'
  1618. minOccurs='1' maxOccurs='1' />
  1619. <element name='type' type='joap:JOAPType'
  1620. minOccurs='1' maxOccurs='1' />
  1621. <element name='desc' type='joap:Description'
  1622. minOccurs='0' maxOccurs='unbounded' />
  1623. </sequence>
  1624. </complexType>
  1625. </element>
  1626. </sequence>
  1627. </complexType>
  1628. </element>
  1629. <element name='desc' type='joap:Description'
  1630. minOccurs='0' maxOccurs='unbounded' />
  1631. </sequence>
  1632. <attribute name='allocation' type='joap:Allocation' />
  1633. </complexType>
  1634. <simpleType name='ClassAddress'>
  1635. <restriction base='string'>
  1636. <pattern value='[^@]+@[a-zA-Z0-9\.]+' />
  1637. </restriction>
  1638. </simpleType>
  1639. <simpleType name='InstanceAddress'>
  1640. <restriction base='string'>
  1641. <pattern value='[^@]+@[a-zA-Z0-9\.]+/.+' />
  1642. </restriction>
  1643. </simpleType>
  1644. <simpleType name='XMLRPCType'>
  1645. <restriction base='string'>
  1646. <enumeration value='int' />
  1647. <enumeration value='i4' />
  1648. <enumeration value='double' />
  1649. <enumeration value='boolean' />
  1650. <enumeration value='string' />
  1651. <enumeration value='array' />
  1652. <enumeration value='struct' />
  1653. </restriction>
  1654. </simpleType>
  1655. <simpleType name='JOAPType'>
  1656. <union memberTypes='ClassAddress XMLRPCType' />
  1657. </simpleType>
  1658. <simpleType name='JOAPName'>
  1659. <restriction base='string'>
  1660. <pattern value='[a-zA-Z_][0-9a-zA-Z_]*'/>
  1661. </restriction>
  1662. </simpleType>
  1663. <simpleType name='Boolean'>
  1664. <restriction base='unsignedByte'>
  1665. <enumeration value='0' />
  1666. <enumeration value='1' />
  1667. </restriction>
  1668. </simpleType>
  1669. <!-- FIXME: figure out how to do this without using mixed
  1670. content, which allows stuff we don't want. -->
  1671. <complexType name='JOAPValue' mixed='true'>
  1672. <choice minOccurs='0'>
  1673. <element name='i4' type='integer' />
  1674. <element name='int' type='integer' />
  1675. <element name='boolean' type='joap:Boolean' />
  1676. <element name='string' type='string' />
  1677. <element name='double' type='decimal' />
  1678. <element name='datetime.iso8601' type='dateTime' />
  1679. <element name='base64' type='base64Binary' />
  1680. <element name='struct' type='joap:XMLRPCStruct' />
  1681. <element name='array' type='joap:XMLRPCArray' />
  1682. </choice>
  1683. </complexType>
  1684. <complexType name='XMLRPCStruct'>
  1685. <sequence>
  1686. <element name='member' minOccurs='1' maxOccurs='unbounded'>
  1687. <complexType>
  1688. <sequence>
  1689. <element name='name' minOccurs='1' maxOccurs='1'
  1690. type='string' />
  1691. <element name='value' minOccurs='1' maxOccurs='1'
  1692. type='joap:JOAPValue' />
  1693. </sequence>
  1694. </complexType>
  1695. </element>
  1696. </sequence>
  1697. </complexType>
  1698. <complexType name='XMLRPCArray'>
  1699. <sequence>
  1700. <element name='data' minOccurs='1' maxOccurs='1'>
  1701. <complexType>
  1702. <sequence>
  1703. <element name='value' type='joap:JOAPValue'
  1704. minOccurs='0' maxOccurs='unbounded' />
  1705. </sequence>
  1706. </complexType>
  1707. </element>
  1708. </sequence>
  1709. </complexType>
  1710. <simpleType name='Allocation'>
  1711. <restriction base='string'>
  1712. <enumeration value='instance' />
  1713. <enumeration value='class' />
  1714. </restriction>
  1715. </simpleType>
  1716. <simpleType name='Description'>
  1717. <restriction base='string' />
  1718. </simpleType>
  1719. <simpleType name='Timestamp'>
  1720. <restriction base='dateTime' />
  1721. </simpleType>
  1722. </schema>
  1723. ]]>
  1724. </code>
  1725. </section1>
  1726. <section1 topic='Appendix C: JOAP DTD'>
  1727. <p>The following is a document-type description (DTD) for JOAP.</p>
  1728. <code><![CDATA[
  1729. <!ELEMENT name (#PCDATA)>
  1730. <!ELEMENT type (#PCDATA)>
  1731. <!ELEMENT desc (#PCDATA)>
  1732. <!ATTLIST desc
  1733. xml:lang NMTOKEN #IMPLIED>
  1734. <!ELEMENT i4 (#PCDATA)>
  1735. <!ELEMENT int (#PCDATA)>
  1736. <!ELEMENT string (#PCDATA)>
  1737. <!ELEMENT double (#PCDATA)>
  1738. <!ELEMENT datetime.iso8601 (#PCDATA)>
  1739. <!ELEMENT base64 (#PCDATA)>
  1740. <!ELEMENT class (#PCDATA)>
  1741. <!ELEMENT superclass (#PCDATA)>
  1742. <!ELEMENT item (#PCDATA)>
  1743. <!ELEMENT returnType (#PCDATA)>
  1744. <!ELEMENT member (name, value)>
  1745. <!ELEMENT struct (member+)>
  1746. <!ELEMENT data (value+)>
  1747. <!ELEMENT array (data)>
  1748. <!ELEMENT value (#PCDATA|i4|int|string|double|datetime.iso8601|base64|struct|array)*>
  1749. <!ELEMENT attribute (name, value)>
  1750. <!ELEMENT timestamp (#PCDATA)>
  1751. <!ELEMENT newAddress (#PCDATA)>
  1752. <!ELEMENT attributeDescription (name, type, desc*)>
  1753. <!ATTLIST attributeDescription
  1754. required (true|false|0|1) "false"
  1755. writable (true|false|0|1) "false"
  1756. allocation (class|instance) "instance">
  1757. <!ELEMENT params (param+)>
  1758. <!ELEMENT param (name, type, desc*)>
  1759. <!ELEMENT methodDescription (name, returnType, params?, desc*)>
  1760. <!ATTLIST methodDescription
  1761. allocation (class|instance) "instance">
  1762. <!ELEMENT describe (desc*, attributeDescription*, methodDescription*,
  1763. (class*|superclass*), timestamp?)>
  1764. <!ELEMENT read (name*|(attribute*, timestamp?))>
  1765. <!ELEMENT edit (attribute*|newAddress?)>
  1766. <!ELEMENT add (attribute*|newAddress)>
  1767. <!ELEMENT search (attribute*|item*)>
  1768. <!ELEMENT delete EMPTY>
  1769. ]]>
  1770. </code>
  1771. </section1>
  1772. <section1 topic='Appendix D: Objects in Extended Example'>
  1773. <p>Because JOAP requires some significant examples to define the
  1774. protocol, an example domain was developed to provide
  1775. consistency. Readers familiar with UML may find the following diagram
  1776. useful to illustrate some of the fine points of JOAP listed
  1777. above.</p>
  1778. <example caption='Object Diagram'><![CDATA[
  1779. Train:
  1780. number: i4
  1781. name: string
  1782. location: TrackSegment
  1783. cars: Car[]
  1784. void forward()
  1785. void back()
  1786. void insertCar(Car car, Car before)
  1787. Car:
  1788. trackingNumber: i4
  1789. i4 nextTrackingNumber() {class}
  1790. Caboose: Car
  1791. Engine: Car
  1792. canPull: i4
  1793. Boxcar: Car
  1794. contents: string
  1795. PassengerCar: Car
  1796. passengers: i4
  1797. Building:
  1798. name: string
  1799. size: struct (length: i4, width: i4)
  1800. TrackSegment:
  1801. previous: TrackSegment
  1802. next: TrackSegment
  1803. Switch:
  1804. in: TrackSegment
  1805. out: TrackSegment[]
  1806. boolean switchTo(TrackSegment)
  1807. Station: TrackSegment, Building
  1808. ]]></example>
  1809. </section1>
  1810. </xep>