Changes

* Each client provides a session class or script with methods to connect to and communicate with the database server. A socket connection will be established by the constructor, which expects a host, port, user name username and password as arguments.

* The {{Code|create()}}, {{Code|add()}}, {{Code|replaceput()}} and {{Code|storeputbinary()}} method methods pass on input streams to the corresponding database commands. The input can be a UTF-8 encoded XML document, a binary resource, or any other data (such as JSON or CSV) that can be successfully converted to a resource by the server.

* <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 transferred <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.

# Client sends the '''user nameusername''' and a hash value. The hash is composed of the md5 hash of## the md5 hash of the '''user nameusername''', '''realm''', and '''password''' (all separated by a colon), and

# Server replies with <code>\000</code> (success) or <code>\101</code> (error)

CRAM-MD5 was discarded, because unsalted md5 hashes could can easily be uncoveredusing rainbow tables. However, most client bindings still provide support forthe outdated handshaking, as it only slightly differs from the new protocol:

# Client sends the '''user nameusername''' and a hash value. The hash is composed of the md5 hash of

# Server replies with <code>\000</code> (success) or <code>\101</code> (error)

Clients can easily be implemented It is possible to support both support {{Code|digest}} and {{Code|cram-md5}} authenticationin clients: If the first server response contains no colon, {{Code|cram-md5}} should be chosen.

| <code>{result} {info} \000</code>

| <code>\0 00 {query}</code>| <code>{id} \000</code>

| <code>\8 08 {name} {input}</code>| <code>{info} \000</code>

| <code>\9 {name} 09 {path} {input}</code>| <code>{info} \000</code>| Adds a new resource document to the opened database.

| WATCHPUT| <code>\10 0C {namepath} {input}</code>| <code>{info} \000</code>| Registers the client for Puts (adds or replaces) an XML document resource in the specified eventopened database.

| UNWATCHPUTBINARY| <code>\11 {name}</code>| <code>{info} \0</code>| Unregisters the client.|-| REPLACE| <code>\12 {path} {input}</code>| <code>{info} \0</code>| Replaces a resource with the specified input.|-| STORE| <code>\13 0D {path} {input}</code>| <code>{info} \000</code>| Stores Puts (adds or replaces) a binary resource in the opened database.

| <code>{</code>''partial result''<code>} {error} \101</code>

| <code>\2 02 {id}</code>| <code>\0 00 \000</code>

| <code>\3 03 {id} {name} {value} {type}</code>| <code>\0 00 \000</code>

| <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.

| <code>\5 05 {id}</code>| <code>{result} \000</code>

| <code>\6 06 {id}</code>| <code>{result} \000</code>

| <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{{Option|SERIALIZER]] }} option.

| <code>\14 0E {id} {value} {type}</code>| <code>\0 00 \000</code>

| <code>\30 1E {id}</code>| <code>{result} \000</code>

| <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 DataMetadata|XDM Meta DataMetadata]]. 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.

Also , sequences can be bound to variables and the context:

* 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.

* 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}}.

In the following example, a client registers a new session and executes the [[Commands#INFO{{Command|INFO]] }} database command. Next, it creates a new query instance for the XQuery expression {{Code|1, 2+'3'}}. The query is then evaluated, and the server returns the result of the first subexpression {{Code|1}} and an error for the second sub expression. Finally, the query instance and client session are closed.

* '''Client''' sends user name username "jack": {{Code|6A 61 63 6B 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}}

* Create and return session with host, port, user name username and password:<br/><code>Session(String host, int port, String name, String password)</code>

* Replace Put a document with the specified input stream:<br/><code>void replaceput(String path, InputStream input)</code> * Store raw data at the specified path:<br/><code>void store(String path, InputStream input)</code> * Watch the specified event:<br/><code>void watch(String name, Event notifier)</code>

* Unwatch Put a binary resource at the specified eventpath:<br/><code>void unwatchputBinary(String namepath, InputStream input)</code>