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.

==Constructors and FunctionsTransfer Protocol==

<All [[Clients]] use the following client/div>server protocol to communicate with the server.<div style="float:left; width:48%;">===Session===The description of the protocol is helpful if you want to implement your own client.

* Execute <code>\xx</code>: single byte.* <code>{...}</code>: utf8 strings or raw data, suffixed with a command <code>\00</code> byte. To avoid confusion with this end-of-string byte, all transferred <code>\00</code> and return the result:<brcode>\FF</code>bytes are prefixed by an additional <code>String execute(String command)\FF</code>byte.

* Add a document to the current database from an input streamDigest authentication is used since Version 8.0:<br/><code>void add(String path, InputStream input)</code>

* Replace # Client connects to server socket# Server sends a document with '''realm''' and '''nonce''', separated by a colon: <code>{realm:nonce}</code># Client sends the '''username''' and a hash value. The hash is composed of the md5 hash of## the md5 hash of the '''username''', '''realm''', and '''password''' (all separated by a colon), and## the specified input stream'''nonce''':<brcode>{username} {md5(md5(username:realm:password) + nonce)}</code># Server replies with <code>\00</code>void replace(String path, InputStream inputsuccess)or <code>\01</code>(error)

* Watch CRAM-MD5 was discarded because unsalted md5 hashes can easily be uncovered using rainbow tables. However, most client bindings still provide support for the outdated handshaking, as it only slightly differs from the specified eventnew protocol:<br/><code>void watch(String name, Event notifier)</code>

* Unwatch the specified event:<br/><code>void unwatch# Client connects to server socket# Server sends a '''nonce''' (String nametimestamp)</code> * Return process information:<br/><code>String info(){nonce}</code> * Close # Client sends the session:<br/><code>void close()</code> </div><div style="float:left; width:4%;">&nbsp;</div><div style="float:left; width:48%;">===Query=== * Create query instance with session '''username''' and query:<br/><code>Query(Session session, String query)</code> * Bind an external variable:<br/><code>void bind(String name, String a hash value, String type)</code><br/>. The type can be an empty string.hash is composed of the md5 hash of * Bind ## the context item:<br/><code>void context(String value, String type)</code><br/>The type can be an empty string. * Execute md5 of the query '''password''' and return ## the result'''nonce''':<br/><code>String execute{username} {md5()</code> * Iterator: check if a query returns more items:<br/><code>boolean more()</code> * Iterator: return the next item:<br/><code>String nextmd5(password)</code> * Return query information:<br/><code>String info(+ nonce)}</code> * Return serialization parameters:<br/># Server replies with <code>String options()\00</code> * Return if the query may perform updates:<br/><code>boolean updating(success)or </code> * Close the query:\01<br/><code>void close(error)</code></div>

<div style="float:left; width:100%;"> ==Transfer Protocol== All [[Clients]] use the following client/server protocol to communicate with the server.The description of the protocol It is helpful if you want possible to implement your own client. ===General Syntax=== * <code>\x</code>: single byte.* <code>support both {{...Code|digest}}</code>: utf8 strings or raw data, suffixed with a <code>\0</code> byte. To avoid confusion with this end-of-string byte, all <code>\0</code> and <code>\FF</code> bytes that occur in raw data will be prefixed with <code>\FF</code>. ===Authentication (via [http://tools.ietf.org/html/rfc2195 {{Code|cram-md5])=== # Client connects to server socket# Server sends timestamp (string representation of the current time }} authentication in milliseconds)clients:<br/><code>If the first server response contains no colon, {timestamp}</code># Client sends username and hashed password/timestamp:<br/><code>{usernameCode|cram-md5} {md5(md5(password) + timestamp)}</code># Server replies with <code>\0</code> (success) or <code>\1</code> (error)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.|-| 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.

| REPLACEPUT| <code>\12 0C {path} {input}</code>| <code>{info} \000</code>| Replaces a Puts (adds or replaces) an XML document resource with in the specified inputopened database.

| STOREPUTBINARY| <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>| Executes the query and returns all results the result as a single string.

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

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

| <code>\30 1E {id}</code>| <code>{result} \000</code>| Returns {{Code|true}} if the query may perform updatescontains updating expressions; {{Code|false}} otherwise.

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

{{Mark|Since Version 8.0}}Also, also sequences can be bound to variables and the context:

* {{Code|empty-sequence()}} must be specified supplied as type if an empty sequence is to be bound.* Multiple items are separated in {supplied via the <code>{Code|value}} </code> argument and separated with {{Code|\101}} bytes.* Item types can be are specified by appending {{Code|\202}} and the type in its string representation to the an item. If no item type is specified, the general type is used.

Some examplesfor 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}}.

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.

* '''Server''' sends realm and timestamp "BaseX:1369578179679": {{Code|◄ 42 61 73 65 58 3A 31 33 36 39 35 37 38 31 37 39 36 37 39 00}}* '''Client''' sends user name username "jack": {{Code|6A 61 63 6B 00 ►}}* '''Client''' additionally sends hashed password/timestamp combinationhash: md5(md5("jack:BaseX:topsecret") + "1369578179679") = "66442c0e3b5af8b9324f7e31b7f5cca8ca664a31f8deda9b71ea3e79347f6666": {{Code|63 61 36 36 34 ... 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}}

==Existing ClientsConstructors and Functions== Most language bindings provide the following constructors and functions: </div><div style="float:left; width:48%;">===Session=== * Create and return session with host, port, username and password:<br/><code>Session(String host, int port, String name, String password)</code> * Execute a command and return the result:<br/><code>String execute(String command)</code> * Return a query instance for the specified query:<br/><code>Query query(String query)</code> * Create a database from an input stream:<br/><code>void create(String name, InputStream input)</code>

* [httpsAdd a document to the current database from an input stream:<br/><code>void add(String path, InputStream input)</github.comcode> * Put a document with the specified input stream:<br/BaseXdb><code>void put(String path, InputStream input)</basex-examplescode> * Put a binary resource at the specified path:<br/blob><code>void putBinary(String path, InputStream input)</mastercode> * Return process information:<br/src><code>String info()</maincode> * Close the session:<br/java><code>void close()</orgcode> </basexdiv><div style="float:left; width:4%;">&nbsp;</examplesdiv><div style="float:left; width:48%;">===Query=== * Create query instance with session and query:<br/api><code>Query(Session session, String query)</BaseXClient.java Java client]code> * [httpsBind an external variable:<br/><code>void bind(String name, String value, String type)</code><br/github>The type can be an empty string.com/BaseXdb/basex-api/blob/master * Bind the context item:<br/src><code>void context(String value, String type)</maincode><br/c%23/BaseXClient>The type can be an empty string.cs C# client] * [httpsExecute the query and return the result:<br/><code>String execute()</github.comcode> * Iterator: check if a query returns more items:<br/BaseXdb><code>boolean more()</basex-apicode> * Iterator: return the next item:<br/blob><code>String next()</mastercode> * Return query information:<br/src><code>String info()</maincode> * Return serialization parameters:<br/python><code>String options()</BaseXClient.py Python client]code> * [httpsReturn if the query may perform updates:<br/><code>boolean updating()</github.comcode> * Close the query:<br/BaseXdb><code>void close()</basex-api/blob/master/src/main/perlcode></BaseXClient.pm Perl client]div>* more client implementations are listed on the [[Clients]] page.<div style="float:left; width:100%;">