Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
|-
| WATCH
| <code>\10 {name}</code>
| <code>{info} \0</code>
| Registers the client for the specified event.
|-
| UNWATCH
| <code>\11 {name}</code>
| <code>{info} \0</code>
| Unregisters the client.
{{Mark|Since Version 8.0}}, also Also sequences can be bound to variables and the context:
* Watch the specified event:<br/><code>void watch(String name, Event notifier)</code>
* Unwatch the specified event:<br/><code>void unwatch(String name)</code>
[[Category:Developer]]
[[Category:Server]]
[[Category:API]]
no edit summary
===Conventions===
* <code>\xxx</code>: single byte.* <code>{...}</code>: utf8 strings or raw data, suffixed with a <code>\000</code> byte. To avoid confusion with this end-of-string byte, all transfered <code>\000</code> and <code>\FF</code> bytes that occur in raw data will be are prefixed with by an additional <code>\FF</code>byte.
===Authentication===
====Digest (==== Digest authentication is used since Version 8.0)====:
# Client connects to server socket
## the md5 hash of the '''user name''', '''realm''', and '''password''' (all separated by a colon), and
## the '''nonce''': <code>{username} {md5(md5(username:realm:password) + nonce)}</code>
# Server replies with <code>\000</code> (success) or <code>\101</code> (error)
====CRAM-MD5 (before Version 8.0)====
CRAM-MD5 was discarded, because unsalted md5 hashes could easily be uncovered
using rainbow tables. However, most client bindings still provide support for
the outdated handshaking, as it only slightly differs from the new protocol:
# Client connects to server socket
## the md5 of the '''password''' and
## the '''nonce''': <code>{username} {md5(md5(password) + nonce)}</code>
# Server replies with <code>\000</code> (success) or <code>\101</code> (error)
Clients can easily be implemented to both support {{Code|digest}} and {{Code|cram-md5}} authentication: If the first server response contains no colon, {{Code|cram-md5}} should be chosen.
| COMMAND
| <code>{command}</code>
| <code>{result} {info} \000</code>
| Executes a database command.
|-
| QUERY
| <code>\0 00 {query}</code>| <code>{id} \000</code>
| Creates a new query instance and returns its id.
|-
| CREATE
| <code>\8 08 {name} {input}</code>| <code>{info} \000</code>
| Creates a new database with the specified input (may be empty).
|-
| ADD
| <code>\9 09 {name} {path} {input}</code>| <code>{info} \000</code>
| Adds a new resource to the opened database.
|-
| REPLACE
| <code>\12 0C {path} {input}</code>| <code>{info} \000</code>
| Replaces a resource with the specified input.
|-
| STORE
| <code>\13 0D {path} {input}</code>| <code>{info} \000</code>
| Stores a binary resource in the opened database.
|-
| ↯ error
| <code></code>
| <code>{</code>''partial result''<code>} {error} \101</code>
| Error feedback.
|}
|-
| CLOSE
| <code>\2 02 {id}</code>| <code>\0 00 \000</code>
| Closes and unregisters the query with the specified id.
|-
| BIND
| <code>\3 03 {id} {name} {value} {type}</code>| <code>\0 00 \000</code>
| Binds a value to a variable. The type will be ignored if the string is empty.
|-
| RESULTS
| <code>\4 04 {id}</code>| <code>\x xx {item} ... \x xx {item} \000</code>| Returns all resulting items as strings, prefixed by a single byte ({{Code|\xxx}}) that represents the [[Server Protocol: Types|Type ID]]. This command is called by the {{Code|more()}} function of a client implementation.
|-
| EXECUTE
| <code>\5 05 {id}</code>| <code>{result} \000</code>| Executes the query and returns all results the result as a single string.
|-
| INFO
| <code>\6 06 {id}</code>| <code>{result} \000</code>
| Returns a string with query compilation and profiling info.
|-
| OPTIONS
| <code>\7 07 {id}</code>| <code>{result} \000</code>| Returns a string with all query serialization parameters, which can e.g. be assigned to the [[Options#SERIALIZER|SERIALIZER]] option.
|-
| CONTEXT
| <code>\14 0E {id} {value} {type}</code>| <code>\0 00 \000</code>
| Binds a value to the context. The type will be ignored if the string is empty.
|-
| UPDATING
| <code>\30 1E {id}</code>| <code>{result} \000</code>| Returns {{Code|true}} if the query may perform updatescontains updating expressions; {{Code|false}} otherwise.
|-
| FULL
| <code>\31 1F {id}</code>| <code>''XDM'' {item} ... ''XDM'' {item} \000</code>
| Returns all resulting items as strings, prefixed by the [[Server Protocol: Types#XDM Meta Data|XDM Meta Data]]. This command is e. g. used by the [[Developing|XQJ API]].
|}
As can be seen in the table, all results end with a single {{Code|\000}} byte, which indicates that the process was successful. If an error occurs, an additional byte {{Code|\101}} is sent, which is then followed by the {{Code|error}} message string.
====Binding Sequences====
* {{Code|empty-sequence()}} must be supplied as type if an empty sequence is to be bound.
* Multiple items are supplied via the <code>{value}</code> argument and separated with {{Code|\101}} bytes.* Item types are specified by appending {{Code|\202}} and the type in its string representation to an item. If no item type is specified, the general type is used.
Some examples for the <code>{value}</code> argument:
* the two integers {{Code|123}} and {{Code|789}} are encoded as {{Code|123}}, {{Code|\101}}, {{Code|789}} and {{Code|\000}} ({{Code|xs:integer}} may be specified via the <code>{type}</code> argument).* the two items {{Code|xs:integer(123)}} and {{Code|xs:string('ABC')}} are encoded as {{Code|123}}, {{Code|\202}}, {{Code|xs:integer}}, {{Code|\101}}, {{Code|ABC}}, {{Code|\202}}, {{Code|xs:string}} and {{Code|\000}}.
==Example==
* '''Client''' requests the query results via the RESULTS protocol command and its query id: {{Code|04 31 00 ►}}
* '''Server''' returns the first result ("1", type xs:integer): {{Code|◄ 52 31 00}}
* '''Server''' sends a single "{{Code|\0" 00}} byte instead of a new result, which indicates that no more results can be expected: {{Code|◄ 00}}* '''Server''' sends the error code "{{Code|\1" 01}} and the error message ("Stopped at..."): {{Code|◄ 01 53 74 6f ... 00}}
* '''Client''' closes the query instance: {{Code|02 31 00 ►}}
* '''Server''' sends a response (which is equal to an empty info string) and success code: {{Code|◄ 00 00}}
* Store raw data at the specified path:<br/><code>void store(String path, InputStream input)</code>
* Return process information:<br/><code>String info()</code>
=Changelog=
;Version 8.2
* Removed: {{Code|WATCH}} and {{Code|UNWATCH}} command
;Version 8.0
</div>
