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-0043.xml 28KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796
  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY % ents SYSTEM "xep.ent">
  4. %ents;
  5. ]>
  6. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  7. <xep>
  8. <header>
  9. <title>Jabber Database Access</title>
  10. <abstract>Expose RDBM systems directly to the jabber network</abstract>
  11. &LEGALNOTICE;
  12. <number>0043</number>
  13. <status>Retracted</status>
  14. <type>Standards Track</type>
  15. <sig>Standards</sig>
  16. <dependencies/>
  17. <supersedes/>
  18. <supersededby/>
  19. <shortname>N/A</shortname>
  20. <author>
  21. <firstname>Justin</firstname>
  22. <surname>Kirby</surname>
  23. <email>justin@openaether.org</email>
  24. <jid>zion@openaether.org</jid>
  25. </author>
  26. <revision>
  27. <version>0.2</version>
  28. <date>2003-10-20</date>
  29. <initials>psa</initials>
  30. <remark>At the request of the author, changed status to Retracted.</remark>
  31. </revision>
  32. <revision>
  33. <version>0.1</version>
  34. <date>2002-08-21</date>
  35. <initials>jk</initials>
  36. <remark>Initial public release</remark>
  37. </revision>
  38. </header>
  39. <section1 topic='Introduction'>
  40. <p>Accessing a RDBMS in a generic fashion is a complex and difficult
  41. task. Consequently, this will not be an attempt to XMLize a generic
  42. Database API or query language. Instead, it will providing a
  43. simple mechanism for a JID to read/write data that it has access to
  44. and specifying a model for those schemas to use in xml.</p>
  45. <p>This document has two aims.</p>
  46. <ol>
  47. <li>Be able to request the available schemas</li>
  48. <li>Perform near SQL-like data manipulation</li>
  49. </ol>
  50. <p>Although designed for use with an RDBMS this document is not
  51. restricted to such uses. It may be used with any data storage
  52. system that can be broken down to a simple table, column/row
  53. format. for example comma delimited files.</p>
  54. </section1>
  55. <section1 topic='Prerequisites'>
  56. <p>To understand the following sections of this document the reader
  57. must be aware of the following.</p>
  58. <section2 topic='Namespace'>
  59. <p>The current namespace of <link>http://openaether.org/projects/jabber_database.html</link>
  60. will be used until this becomes a jep. Once officially accepted as
  61. a jep and approved as final by the council, it will become
  62. <link>http://www.xmpp.org/extensions/xep-0043.html</link>.</p>
  63. </section2>
  64. <section2 topic='Elements'>
  65. <ul>
  66. <li>version - specify the version of the protocol that the client/server supports</li>
  67. <li>database - specify the database/catalog has the following attributes:
  68. <ul>
  69. <li>name - name of the database/catalog</li>
  70. <li>sql - embed native SQL queries directly</li>
  71. <li>table - the element scopes the children into the table. has the following attributes:
  72. <ul>
  73. <li>name - name of the table</li>
  74. <li>permission - what the user can do with the data</li>
  75. <li>col - describes the column. has the following attributes
  76. <ul>
  77. <li>name - name of the column</li>
  78. <li>type - SQL99 datatype of the column</li>
  79. <li>size - size of the datatype if required</li>
  80. <li>op - comparison operator, used only if child of where element</li>
  81. </ul>
  82. </li>
  83. <li>where - scopes col elements into a 'sql-like' where clause
  84. <ul>
  85. <li>col - see above</li>
  86. </ul>
  87. </li>
  88. </ul>
  89. </li>
  90. <li>proc - element scopes the children into a procedure has the following attributes:
  91. <ul>
  92. <li>name - name of the sproc</li>
  93. <li>permission - what the user can do with the data</li>
  94. <li>col - see above</li>
  95. <li>result - indicated return value by running the procedure (restricted to integer)</li>
  96. </ul>
  97. </li>
  98. </ul>
  99. </li>
  100. </ul>
  101. </section2>
  102. <section2 topic='Data Types'>
  103. <p>There are a limited subset of data types available:</p>
  104. <ul>
  105. <li>bit - a single 'bit', usually used to represent boolean values</li>
  106. <li>tinyint - signed 8bit integer, has a range from -128 to +127</li>
  107. <li>integer - signed 32bit integer, has a range from -2147483648 to +2147483647</li>
  108. <li>utinyint - unsigned 8bit integer, has a range from 0 to +255</li>
  109. <li>uinteger - usigned 32bit integer, has a range from 0 to +4294967296</li>
  110. <li>float - allowed values are -3.402823466E+38 to
  111. -1.175494351E-38, 0, and 1.175494351E-38 to 3.402823466E+38 (can NOT be unsigned)</li>
  112. <li>numeric - unlimited size (some databases constrain this though)</li>
  113. <li>date - resolution is one day. acceptable ranges vary (TODO: constrain minimal range to something)</li>
  114. <li>datetime - a date and time combination (often has range dependencies)</li>
  115. <li>timestamp - a datetime used most often to record events</li>
  116. <li>time - a time in the format HH:MM:SS (TODO: specify valid range)</li>
  117. <li>char - an unsigned byte representing a single character (ASCII)</li>
  118. <li>vchar - a variable width char</li>
  119. <li>text - an extremely large chunk of text</li>
  120. <li>blob - an extremely large chunk of binary data (encode in MIME)</li>
  121. </ul>
  122. </section2>
  123. <section2 topic='Assumed Database Setup'>
  124. <p>All SQL/RDBMS units will be scoped in the xml hierarchy:</p>
  125. <code>
  126. &lt;database&gt;
  127. &lt;table&gt;
  128. &lt;col/&gt;
  129. &lt;/table&gt;
  130. &lt;/database&gt;
  131. </code>
  132. <p>All examples will assume the existence of the following rdbms setup. A
  133. database named 'testdb' with tables created with following SQL
  134. script:</p>
  135. <code>
  136. create table tbl_one
  137. (
  138. a_int int,
  139. a_float float,
  140. a_char char(10)
  141. )
  142. create table tbl_two
  143. (
  144. a_date datetime,
  145. a_numeric numeric(9,3)
  146. )
  147. </code>
  148. </section2>
  149. </section1>
  150. <section1 topic='Usage'>
  151. <section2 topic='Requesting Schemas'>
  152. <example caption='A simple schema request'>
  153. &lt;iq id="001" to="db.host" type="get"&gt;
  154. &lt;database
  155. name="testdb"
  156. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  157. &lt;/iq&gt;
  158. </example>
  159. <p>This is a simple request to discover what tables/procedures
  160. exist on the database testdb. And what permissions are available
  161. to the user. All schema requests will respond within the scope that
  162. was asked for. This is to prevent unnecessary data from flooding
  163. the network. So the response for the above request would look
  164. something like:</p>
  165. <example caption='Response to a schema request'>
  166. &lt;iq id="001" type="result" from="db.host"&gt;
  167. &lt;database
  168. name="testdb"
  169. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  170. &lt;table name="tbl_one" permission="both"/&gt;
  171. &lt;table name="tbl_two" permission="read"/&gt;
  172. &lt;/database&gt;
  173. &lt;/iq&gt;
  174. </example>
  175. <p>The response is scoped to only the 'children' of the request.
  176. Since the request was for the testdb database, only the tables
  177. within that database were returned in the result. The reason for
  178. the limitation is to prevent excessively large packets from filling
  179. the network from large schemas.</p>
  180. <p>The response indicates that the user has both read and write
  181. permissions on the table 'tbl_one' and only read permissions on
  182. the table 'tbl_two'. Consequently, the user may only perform get
  183. requests on 'tbl_two'.</p>
  184. <example caption='Request detailed table schema'>
  185. &lt;iq id="002" type="get" to="db.host"&gt;
  186. &lt;database
  187. name="testdb"
  188. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  189. &lt;table name="tbl_one"/&gt;
  190. &lt;/database&gt;
  191. &lt;/iq&gt;
  192. </example>
  193. <p>The response would look like:</p>
  194. <example caption='Response to detailed request'>
  195. &lt;iq id="002" type="result" from="db.host"&gt;
  196. &lt;database
  197. name="testdb"
  198. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  199. &lt;table name="tbl_one" permission="both"&gt;
  200. &lt;col name="a_int" type="int"/&gt;
  201. &lt;col name="a_float" type="float"/&gt;
  202. &lt;col name="a_char" type="char" size="10"/&gt;
  203. &lt;/table&gt;
  204. &lt;/database&gt;
  205. &lt;/iq&gt;
  206. </example>
  207. <p>The schema response for tbl_one is quite intuitive. Three
  208. columns exist, one called a_int of type int (integer), another
  209. a_float of type float and a third called a_char of type char
  210. with a size of ten characters.</p>
  211. </section2>
  212. <section2 topic='Manipulating Data'>
  213. <p>Manipulation of data (select, insert, update, delete) will
  214. definitely not be elegant or easy. SQL allows for some fairly
  215. complex queries on any fully functional RDBMS. Consequently,
  216. the data manipulation will be relatively limited since it is
  217. not a goal to translate SQL into xml.</p>
  218. <section3 topic='Selects'>
  219. <p>To indicate a select like query, specify an &lt;iq&gt; of
  220. type get. The table that the query is to be performed against
  221. must be specified. The columns that are to be returned in
  222. the result set must be scoped within the relative table.
  223. Any attribute on the &lt;col&gt; element besides name will be
  224. ignored. e.g. it is not required nor recommended to specify
  225. the data types or the sizes while performing a get.</p>
  226. <example caption='Basic select'>
  227. &lt;iq id="003" type="get" to="db.host"&gt;
  228. &lt;database
  229. name="testdb"
  230. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  231. &lt;table name="tbl_one"&gt;
  232. &lt;col name="a_int"/&gt;
  233. &lt;col name="a_float"/&gt;
  234. &lt;col name="a_char"/&gt;
  235. &lt;/table&gt;
  236. &lt;/database&gt;
  237. &lt;/iq&gt;
  238. SQL Syntax:
  239. select a_int, a_float, a_char
  240. from tbl_one
  241. </example>
  242. <p>It is also possible to specify a limit on the number of rows
  243. returned in the result set by specifying a value for the limit
  244. attribute.</p>
  245. <example caption='Basic select with limit'>
  246. &lt;iq id="003" type="get" to="db.host"&gt;
  247. &lt;database
  248. name="testdb"
  249. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  250. &lt;table name="tbl_one" limit="2"&gt;
  251. &lt;col name="a_int"/&gt;
  252. &lt;col name="a_float"/&gt;
  253. &lt;col name="a_char"/&gt;
  254. &lt;/table&gt;
  255. &lt;/database&gt;
  256. &lt;/iq&gt;
  257. </example>
  258. <p>In this case a limit of two rows will be returned in the result set.</p>
  259. <p> The result set which is returned will contain all the rows
  260. that met the criteria of the select. There is no schema
  261. information beyond the column names included in the result set.
  262. Each 'row' in the result set is scoped within the corresponding
  263. &lt;table&gt; element. This allows for queries on multiple
  264. tables to be used in one &lt;iq&gt; packet.</p>
  265. <example caption='Response to basic select'>
  266. &lt;iq id="003" type="result" from="db.host"&gt;
  267. &lt;database
  268. name="testdb"
  269. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  270. &lt;table name="tbl_one"&gt;
  271. &lt;col name="a_int"&gt;1234&lt;/col&gt;
  272. &lt;col name="a_float"&gt;123.45&lt;/col&gt;
  273. &lt;col name="a_char"&gt;onetwothre&lt;/col&gt;
  274. &lt;/table&gt;
  275. &lt;table name="tbl_one"&gt;
  276. &lt;col name="a_int"&gt;2345&lt;/col&gt;
  277. &lt;col name="a_float"&gt;234.56&lt;/col&gt;
  278. &lt;col name="a_char"&gt;twothreefo&lt;/col&gt;
  279. &lt;/table&gt;
  280. &lt;/database&gt;
  281. &lt;/iq&gt;
  282. </example>
  283. </section3>
  284. <section3 topic='Constraining Result Sets'>
  285. <p>It would be impractical to request the entire contents of the
  286. table every time you needed one row or a subset of the data. You
  287. can constrain the result set by specifying a where clause.</p>
  288. <example caption='Select with constraints'>
  289. &lt;iq id="004" type="get" to="db.host"&gt;
  290. &lt;database
  291. name="testdb"
  292. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  293. &lt;table name="tbl_one"&gt;
  294. &lt;col name="a_int"/&gt;
  295. &lt;col name="a_float"/&gt;
  296. &lt;col name="a_char"/&gt;
  297. &lt;where&gt;
  298. &lt;col name="a_int" op="eq"&gt;1234&lt;/col&gt;
  299. &lt;col name="a_float" op="lt" conj="and"&gt;200.00&lt;/col&gt;
  300. &lt;/where&gt;
  301. &lt;/table&gt;
  302. &lt;/database&gt;
  303. &lt;/iq&gt;
  304. SQL Syntax:
  305. select a_int, a_float, a_char from tbl_one
  306. where a_int = 1234 and a_float &lt; 200.00
  307. </example>
  308. <p>Attributes only used in the &lt;col&gt; element within a
  309. &lt;where&gt; element are the op (for operator) and conj for
  310. (conjunction). The op is used for comparison operators such
  311. as &lt;, &gt;, =, &lt;&gt;, &lt;=, &gt;=</p>
  312. <ul>
  313. <li>eq - equivalent =</li>
  314. <li>neq - not-equivalent &lt;&gt;</li>
  315. <li>lt - less than &lt;</li>
  316. <li>gt - greater than &gt;</li>
  317. <li>let - less than or equivalent &lt;=</li>
  318. <li>get - greater than or equivalent &gt;=</li>
  319. <li>null - IS NULL (the column is null in the database sense of the word)</li>
  320. </ul>
  321. <p>The conjuction attribute is used to combined constraints in the where clause</p>
  322. <ul>
  323. <li>not - to negate a result</li>
  324. <li>or - logical OR ||</li>
  325. <li>and - logical AND &amp;&amp;</li>
  326. </ul>
  327. <p><strong>Result</strong></p>
  328. <example caption='Response to select with constraints'>
  329. &lt;iq id="003" type="result" to="db.host"&gt;
  330. &lt;database
  331. name="testdb"
  332. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  333. &lt;table name="tbl_one"&gt;
  334. &lt;col name="a_int"&gt;1234&lt;/col&gt;
  335. &lt;col name="a_float"&gt;123.45&lt;/col&gt;
  336. &lt;col name="a_char"&gt;onetwothre&lt;/col&gt;
  337. &lt;/table&gt;
  338. &lt;/database&gt;
  339. &lt;/iq&gt;
  340. </example>
  341. </section3>
  342. <section3 topic='Inserts'>
  343. <p>Inserting or altering the stored data in anyway requires
  344. setting the type attribute to a value of set. This indicates
  345. that the user wants to perform a 'insert/update'. The
  346. differentiating factor between an insert and an update operation
  347. is whether a &lt;where&gt; element is used. If there is no
  348. &lt;where&gt; element then it must be interpreted as an insert.
  349. If a &lt;where&gt; element does exist, then it must be
  350. interpreted as an update.</p>
  351. <example caption='Inserting data'>
  352. &lt;iq id="004" type="set" to="db.host"&gt;
  353. &lt;database
  354. name="testdb"
  355. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  356. &lt;table name="tbl_one"&gt;
  357. &lt;col name="a_int"&gt;3456&lt;/col&gt;
  358. &lt;col name="a_float"&gt;345.67&lt;/col&gt;
  359. &lt;col name="a_char"&gt;threefour&lt;/col&gt;
  360. &lt;/table&gt;
  361. &lt;table name="tbl_two"&gt;
  362. &lt;col name="a_date"&gt;02/16/2002&lt;/col&gt;
  363. &lt;col name="a_numeric"&gt;123456789123.123&lt;/col&gt;
  364. &lt;/table&gt;
  365. &lt;/database&gt;
  366. &lt;/iq&gt;
  367. SQL syntax:
  368. insert tbl_one (a_int, a_float,a_char)VALUES(3456, 345.67, 'threefour')
  369. insert tbl_two (a_date, a_numeric) VALUES('02/16/2002', 123456789123.123)
  370. </example>
  371. <p><strong>Result</strong></p>
  372. <p> If there is no result set for the query, as in an update,
  373. insert, delete, then the response must indicate success or
  374. failure within the &lt;table&gt; element scope. An empty
  375. &lt;table&gt; element indicates success, and a &lt;table&gt;
  376. element containing an &lt;error&gt; element indicates a failure.</p>
  377. <example caption='Response to data insert'>
  378. &lt;iq id="004" type="result" from="db.host"&gt;
  379. &lt;database
  380. name="testdb"
  381. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  382. &lt;table name="tbl_one"/&gt;
  383. &lt;table name="tbl_two"&gt;
  384. &lt;error code="380"&gt;permission denied on table&lt;/error&gt;
  385. &lt;/table&gt;
  386. &lt;/database&gt;
  387. &lt;/iq&gt;
  388. </example>
  389. <p> The insert into tbl_one succeeded since the response has an
  390. empty &lt;table&gt; element. However, the insert into tbl_two
  391. failed with a permission denied error. Which is indicated with a
  392. non-empty &lt;table&gt; element.</p>
  393. </section3>
  394. <section3 topic='Updates'>
  395. <p> As stated previously, if the type attribute has a value of
  396. set and a &lt;where&gt; element exists, then it must be interpreted as an update.</p>
  397. <example caption='Updating'>
  398. &lt;iq id="005" type="set" to="db.host"&gt;
  399. &lt;database
  400. name="testdb"
  401. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  402. &lt;table name="tbl_one"&gt;
  403. &lt;col name="a_char"&gt;aaaaaaaaaa&lt;/col&gt;
  404. &lt;where&gt;
  405. &lt;col name=c"a_int"&gt;1234&lt;/col&gt;
  406. &lt;/where&gt;
  407. &lt;/table&gt;
  408. &lt;/database&gt;
  409. &lt;/iq&gt;
  410. SQL Syntax:
  411. update tbl_one
  412. set a_char = 'aaaaaaaaaa'
  413. where a_int = 1234
  414. </example>
  415. <p><strong>Result</strong></p>
  416. <p> Again, if there is no result set returned by the query, then
  417. success or failure must be indicated.</p>
  418. <example caption='Response to update'>
  419. &lt;iq id="005" type="result" to="db.host"&gt;
  420. &lt;database
  421. name="testdb"
  422. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  423. &lt;table name="tbl_one"/&gt;
  424. &lt;/database&gt;
  425. &lt;/iq&gt;
  426. </example>
  427. </section3>
  428. <section3 topic='Deletes'>
  429. <p> If the type attribute has a value of set and there are no
  430. &lt;col&gt; elements scoped within the &lt;table&gt; element,
  431. then the query must be interpreted as a delete.</p>
  432. <example caption='Simple delete'>
  433. &lt;iq id="006" type="set" to="db.host"&gt;
  434. &lt;database
  435. name="testdb"
  436. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  437. &lt;table name="tbl_one"&gt;
  438. &lt;where&gt;
  439. &lt;col name="a_int" op="eq"&gt;1234&lt;/col&gt;
  440. &lt;/where&gt;
  441. &lt;/table&gt;
  442. &lt;/database&gt;
  443. &lt;/iq&gt;
  444. SQL Syntax:
  445. delete from tbl_one where a_int = 1234
  446. </example>
  447. <p><strong>Result</strong></p>
  448. <p>Again, if a result set is not generated by a query, then
  449. success or failure must be indicated by the &lt;table&gt; element</p>
  450. <example caption='Response to delete'>
  451. &lt;iq id="006" type="result" to="db.host"&gt;
  452. &lt;database
  453. name="testdb"
  454. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  455. &lt;table name="tbl_one"/&gt;
  456. &lt;/database&gt;
  457. &lt;/iq&gt;
  458. </example>
  459. </section3>
  460. </section2>
  461. <section2 topic='Procedures'>
  462. <p> Procedures, or stored procedures <note>Apparently procedures
  463. are not as common in RDBMS as I thought. Postgres and MySQL have
  464. functions, but not procedures. So until I, or someone else,
  465. researches this issue this feature is on hold.</note>
  466. , are often handy to make frequently used sql queries execute faster.
  467. These are simply queries stored in a precompiled form and given a
  468. name with a list of parameters. Each RDBMS handles procedures
  469. differently, but the common characteristics are that they are
  470. stored server side and have in/out parameters.</p>
  471. <p> The &lt;proc&gt; element will be used to indicate a procedure.
  472. It has similar characteristics to the &lt;table&gt; element. The
  473. core differences are that the &lt;col&gt; elements have permissions
  474. and a &lt;result&gt; element can be used to indicate the value
  475. returned by the procedure.</p>
  476. <p> The permission attribute on a &lt;col&gt; element is used to
  477. indicate whether the parameter is in (read), out (write) or in/out (both). </p>
  478. <p> The only result set acceptable from a procedure is that of the
  479. parameters or &lt;col&gt; element. If the procedure produces a
  480. result set outside of the parameters this should be ignored.</p>
  481. </section2>
  482. <section2 topic='Errors'>
  483. <p> The server must be able to let the client know when an error
  484. occurs, instead of just being silent.</p>
  485. <table caption='Error Codes'>
  486. <tr>
  487. <th>Code</th>
  488. <th>Message</th>
  489. <th>Description</th>
  490. </tr>
  491. <tr>
  492. <td>399</td>
  493. <td>Invalid Database Name</td>
  494. <td>Returned when the client has requested information from a
  495. database which does not exist according to the component.</td>
  496. </tr>
  497. <tr>
  498. <td>398</td>
  499. <td>Invalid Table Name</td>
  500. <td>Returned when the client has requested information from a
  501. table/procedure which does not exist according to the component.</td>
  502. </tr>
  503. <tr>
  504. <td>397</td>
  505. <td>Invalid Column Name</td>
  506. <td>Returned when the client has requested information from a
  507. column which does not exist according to the component.</td>
  508. </tr>
  509. <tr>
  510. <td>380</td>
  511. <td>Permission Denied on Table</td>
  512. <td>Returned when the requested action is not allowed for the
  513. user on the table</td>
  514. </tr>
  515. <tr>
  516. <td>401</td>
  517. <td>Access Denied</td>
  518. <td>Returned when the user does not have permission to use the
  519. component.</td>
  520. </tr>
  521. </table>
  522. <p>If the user requests an action on a table which they do not have
  523. permission to do the following should be returned</p>
  524. <example caption='Permission denied error'>
  525. &lt;iq id="004" type="error" from="db.host"&gt;
  526. &lt;database
  527. name="testdb"
  528. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  529. &lt;table name="tbl_two"&gt;
  530. &lt;error code="380"&gt;permission denied on table&lt;/error&gt;
  531. &lt;/table&gt;
  532. &lt;/database&gt;
  533. &lt;/iq&gt;
  534. </example>
  535. <p>If the user is not allowed to access the component the following should be returned</p>
  536. <example caption='General access denied'>
  537. &lt;iq id="004" type="error" from="db.host"&gt;
  538. &lt;database
  539. name="testdb"
  540. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  541. &lt;error code="401"&gt;Access Denied&lt;/error&gt;
  542. &lt;/database&gt;
  543. &lt;/iq&gt;
  544. </example>
  545. </section2>
  546. <section2 topic='Optional Features'>
  547. <p> There are requirements which can be provided by other jabber
  548. components/namespaces, namely the jabber:iq:browse namespace
  549. in-place of Version Negotiation. Due to the inherent limitations
  550. of the above data retrieval mechanisms more sophisticated querying
  551. techniques might be desired. The &lt;query&gt; element will extend
  552. the functionality </p>
  553. <section3 topic='Embedded SQL'>
  554. <p> The abilities described in the Basics section are just that,
  555. basic. To provide more flexibility and allow for the full power
  556. of SQL without xmlifying everything, a &lt;sql&gt; element may
  557. be implemented to provide this feature.</p>
  558. <p> The &lt;sql&gt; element must be scoped within the &lt;database&gt; element.</p>
  559. <example caption='Embedded sql query'>
  560. &lt;iq id="007" type="get" to="db.host"&gt;
  561. &lt;database
  562. name="testdb"
  563. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  564. &lt;sql&gt; select a_int, a_float from tbl_one &lt;/sql&gt;
  565. &lt;/database&gt;
  566. &lt;/iq&gt;
  567. </example>
  568. <p><strong>Result</strong></p>
  569. <example caption='Response to embedded query'>
  570. &lt;iq id="007" type="result" to="db.host"&gt;
  571. &lt;database
  572. name="testdb"
  573. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  574. &lt;table name="tbl_one" permission="both"&gt;
  575. &lt;col name="a_int" type="integer"/&gt;
  576. &lt;col name="a_float" type="float"/&gt;
  577. &lt;/table&gt;
  578. &lt;table name="tbl_one"&gt;
  579. &lt;col name="a_int"&gt;1234&lt;/col&gt;
  580. &lt;col name="a_float"&gt;123.45&lt;/col&gt;
  581. &lt;/table&gt;
  582. &lt;table name="tbl_one"&gt;
  583. &lt;col name="a_int"&gt;2345&lt;/col&gt;
  584. &lt;col name="a_float"&gt;234.56&lt;/col&gt;
  585. &lt;/table&gt;
  586. &lt;/database&gt;
  587. &lt;/iq&gt;
  588. </example>
  589. <p> Since SQL is so flexible, the result set schema is not known
  590. until it is returned as a result of the query. Consequently, it
  591. must be sent as the first 'row' of the returned result. Each
  592. following row will be the actual data queried for.</p>
  593. <p> If multiple tables are used within one SQL statement, then
  594. then name attribute within the &lt;table&gt; element can not be
  595. accurately denoted with a single table name. The best way to deal
  596. with this situation is to simply use a unique identifier within
  597. the scope of the &lt;database&gt; element. This will allow for
  598. multiple &lt;sql&gt; results to be scoped within the same result.</p>
  599. </section3>
  600. <section3 topic='Version Negotiation'>
  601. <p>It is expected that this protocol will grow and be extended
  602. to meet various demands. Therefore, version
  603. negotiation<note>Version Negotiation is being killed since browsing, feature
  604. negotiation, or disco will be able to perform this function,
  605. however it might be useful as an optional feature for clients
  606. that don't implement these yet, especially considering none
  607. of these have been standardized.</note> will be
  608. incorporated up front.</p>
  609. <p>When the connection initiator, client end-user or
  610. server/transport, starts a session, it must first send
  611. the version number it expects to use, otherwise, behavior
  612. is undefined.</p>
  613. <code>
  614. &lt;iq id="000" type="get" to="db.host"&gt;
  615. &lt;database
  616. xmlns="http://openaether.org/projects/jabber_database.html"&gt;
  617. &lt;version&gt;0.1&lt;/version&gt;
  618. &lt;/database&gt;
  619. &lt;/iq&gt;
  620. </code>
  621. <p>Three responses are possible from the server.</p>
  622. <ol>
  623. <li>
  624. <p>It supports that version number and responds with:</p>
  625. <code>
  626. &lt;iq id="000" type="result" from="db.host"&gt;
  627. &lt;database
  628. xmlns="http://openaether.org/projects/jabber_database.html"&gt;
  629. &lt;version&gt;0.1&lt;/version&gt;
  630. &lt;/database&gt;
  631. &lt;/iq&gt;
  632. </code>
  633. <p>The type of 'result' indicates that the version request was
  634. successful and if the client is satisfied with the version number,
  635. may continue with schema requests or whatever.</p></li>
  636. <li><p>It does not support that version number and responds with:</p>
  637. <code>
  638. &lt;iq id="000" type="error" from="db.host"&gt;
  639. &lt;database
  640. xmlns="http://openaether.org/projects/jabber_database.html"/&gt;
  641. &lt;/iq&gt;
  642. </code>
  643. <p>The type of 'error' indicates a failure in conforming to the
  644. desired version number. The server may optionally send an
  645. alternative option.</p>
  646. <code>
  647. &lt;iq id="000" type="error" from="db.host"&gt;
  648. &lt;database
  649. xmlns="http://openaether.org/projects/jabber_database.html"&gt;
  650. &lt;version&gt;0.2&lt;/version&gt;
  651. &lt;/database&gt;
  652. &lt;/iq&gt;
  653. </code></li>
  654. <li>If the server has no idea what the client is talking
  655. about it should send the appropriate Jabber error code.</li>
  656. </ol>
  657. </section3>
  658. </section2>
  659. </section1>
  660. <section1 topic='Limitations'>
  661. <ol>
  662. <li>No joins, roll ups, cubes</li>
  663. <li>Views are not differentiated from tables</li>
  664. <li>provides basic sql-like functionality only</li>
  665. <li>Utilizes <em>lowest common denominator</em> approach</li>
  666. </ol>
  667. </section1>
  668. <section1 topic='Todos'>
  669. <ul>
  670. <li>define procedures; what they are and how they work</li>
  671. <li>determine value of adding administration features</li>
  672. </ul>
  673. </section1>
  674. <section1 topic='Thanks'>
  675. <p>Thanks to Russell Davis (ukscone) for fine tuning the layout and wording of this jep. It would probably have been unreadable if it wasn't for him.</p>
  676. </section1>
  677. <section1 topic='DTD and Schema'>
  678. <section2 topic='DTD'>
  679. <code>
  680. &lt;!ELEMENT version (#PCDATA)&gt;
  681. &lt;!ELEMENT error (#PCDATA)&gt;
  682. &lt;!ELEMENT sql(#PCDATA)&gt;
  683. &lt;!ELEMENT database (table | sproc | sql | error)*&gt;
  684. &lt;!ELEMENT table (col | where | error)*&gt;
  685. &lt;!ELEMENT where (col+)&gt;
  686. &lt;!ELEMENT col (#PCDATA)&gt;
  687. &lt;!ELEMENT proc(col | result | error)*&gt;
  688. &lt;!ELEMENT result (#PCDATA)&gt;
  689. &lt;!ATTLIST error code CDATA #IMPLIED&gt;
  690. &lt;!ATTLIST database name CDATA #IMPLIED&gt;
  691. &lt;!ATTLIST table
  692. name CDATA #IMPLIED
  693. permission (read | write | both) #IMPLIED
  694. limit CDATA #IMPLIED
  695. &gt;
  696. &lt;!ATTLIST proc name CDATA #IMPLIED&gt;
  697. &lt;!ATTLIST col
  698. name CDATA #IMPLIED
  699. size CDATA #IMPLIED
  700. op (eq | neq | lt | gt | let | get | null) #IMPLIED
  701. conj (not | or | and ) #IMPLIED
  702. permission (read | write | both) #IMPLIED
  703. type (bit | tinyint | integer | utinyint | uinteger |
  704. float | numeric | date | datetime | timestamp |
  705. time | char | vchar | text | blob) #IMPLIED
  706. &gt;
  707. </code>
  708. </section2>
  709. <section2 topic='Schema'>
  710. <p><strong>Anyone care to do this?</strong></p>
  711. </section2>
  712. </section1>
  713. </xep>