Changes

<div style="float:left; width:100%;">This page presents the code structure classes and functions of the [[Clients|BaseX clientsClients]],and the client/underlying protocol, which is utilized for communicating with the database server protocol needed to write [[Clients]].in other programming languagesA detailed example demonstrates how a concrete byte exchange can look like.

==DescriptionWorkflow==

* First of allAll clients are based on the client/server architecture. Hence, the a BaseX database server must be running in order to use the clientsstarted first.

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

* For the execution of commands you need to call the <code>The {{Code|execute()</code> }} method with the is called to launch a database command as argument. The method It returns the result or throws an exception with the received error message.

* The <code>{{Code|query()</code> }} method creates a query instance. Variables and the context item can be bound to that objectinstance, and the result can either be requested by <code>via {{Code|execute()</code>}}, or in an iterative manner with the <code>{{Code|more()</code> }} and <code>{{Code|next()</code> }} functions. If an error occurs, an exception will be thrown.

* The <code>{{Code|create()</code>}}, <code>{{Code|add()</code>}}, <code>replace{{Code|put()</code> }} and <code>store{{Code|putbinary()</code> method can be used to }} 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.

==Transfer Protocol== All [[Clients]] use the following client/server protocol to communicate with the server.The description of the protocol is helpful if you want to implement your own client. ===Conventions=== * <code>\xx</code>: single byte.* <code>{...}</code>: utf8 strings or raw data, suffixed with a <code>\00</code> byte. To avoid confusion with this end-of-string byte, all transferred <code>\00</code> and <code>\FF</code> bytes are prefixed by an additional <code>\FF</code> byte. ===Authentication=== ====Digest==== Digest authentication is used since Version 8.0: # Client connects to server socket# Server sends a '''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 '''nonce''': <code>{username} {md5(md5(username:realm:password) + nonce)}</code># Server replies with <code>\00</code> (success) or <code>\01</code> (error) ====CRAM-MD5==== 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 new protocol: # Client connects to server socket# Server sends a '''nonce''' (timestamp): <code>{nonce}</code># Client sends the '''username''' and a hash value. The hash is composed of the md5 hash of## the md5 of the '''password''' and## the '''nonce''': <code>{username} {md5(md5(password) + nonce)}</code># Server replies with <code>\00</code> (success) or <code>\01</code> (error) It is possible to support both {{Code|digest}} and {{Code|cram-md5}} authentication in clients: If the first server response contains no colon, {{Code Structure|cram-md5}} should be chosen. ===Command Protocol=== The following byte sequences are sent and received from the client (please note that a specific client may not support all of the presented commands): {| class="wikitable"|-! Command! Client Request! Server Response! Description|-| COMMAND| <code>{command}</code>| <code>{result} {info} \00</code>| Executes a database command.|-| QUERY| <code>\00 {query}</code>| <code>{id} \00</code>| Creates a new query instance and returns its id.|-| CREATE| <code>\08 {name} {input}</code>| <code>{info} \00</code>| Creates a new database with the specified input (may be empty).|-| ADD| <code>\09 {path} {input}</code>| <code>{info} \00</code>| Adds a new document to the opened database.|-| PUT| <code>\0C {path} {input}</code>| <code>{info} \00</code>| Puts (adds or replaces) an XML document resource in the opened database.|-| PUTBINARY| <code>\0D {path} {input}</code>| <code>{info} \00</code>| Puts (adds or replaces) a binary resource in the opened database.|-| ↯ error| <code></code>| <code>{</code>''partial result''<code>} {error} \01</code>| Error feedback.|} ===Query Command Protocol=== Queries are referenced via an {{Code|id}}, which has been returned by the {{Code|QUERY}} command (see above). {| class="wikitable"|-! Query Command! Client Request! Server Response! Description|-| CLOSE| <code>\02 {id}</code>| <code>\00 \00</code>| Closes and unregisters the query with the specified id.|-| BIND| <code>\03 {id} {name} {value} {type}</code>| <code>\00 \00</code>| Binds a value to a variable. The type will be ignored if the string is empty.|-| RESULTS| <code>\04 {id}</code>| <code>\xx {item} ... \xx {item} \00</code>| Returns all resulting items as strings, prefixed by a single byte ({{Code|\xx}}) that represents the [[Server Protocol: Types|Type ID]]. This command is called by the {{Code|more()}} function of a client implementation.|-| EXECUTE| <code>\05 {id}</code>| <code>{result} \00</code>| Executes the query and returns the result as a single string.|-| INFO| <code>\06 {id}</code>| <code>{result} \00</code>| Returns a string with query compilation and profiling info.|-| OPTIONS| <code>\07 {id}</code>| <code>{result} \00</code>| Returns a string with all query serialization parameters, which can e.g. be assigned to the {{Option|SERIALIZER}} option.|-| CONTEXT| <code>\0E {id} {value} {type}</code>| <code>\00 \00</code>| Binds a value to the context. The type will be ignored if the string is empty.|-| UPDATING| <code>\1E {id}</code>| <code>{result} \00</code>| Returns {{Code|true}} if the query contains updating expressions; {{Code|false}} otherwise.|-| FULL| <code>\1F {id}</code>| <code>''XDM'' {item} ... ''XDM'' {item} \00</code>| Returns all resulting items as strings, prefixed by the [[Server Protocol: Types#XDM Metadata|XDM Metadata]]. 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|\00}} byte, which indicates that the process was successful. If an error occurs, an additional byte {{Code|\01}} is sent, which is then followed by the {{Code|error}} message string. ====Binding Sequences==== Also, sequences can be bound to variables and the context: * {{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|\01}} bytes.* Item types are specified by appending {{Code|\02}} 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|\01}}, {{Code|789}} and {{Code|\00}} ({{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|\02}}, {{Code|xs:integer}}, {{Code|\01}}, {{Code|ABC}}, {{Code|\02}}, {{Code|xs:string}} and {{Code|\00}}.

===Session=Example==

* Creates In the following example, a client registers a new session and returns session with hostexecutes the {{Command|INFO}} database command. Next, it creates a new query instance for the XQuery expression {{Code|1, port2+'3'}}. The query is then evaluated, user name and password:<br/><code>Session(String hostthe server returns the result of the first subexpression {{Code|1}} and an error for the second sub expression. Finally, int port, String name, String password)</code>the query instance and client session are closed.

* Executes '''Client''' connects to the database server socket* '''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 username "jack": {{Code|6A 61 63 6B 00 ►}}* '''Client''' sends hash: md5(md5("jack:BaseX:topsecret") + "1369578179679") = "ca664a31f8deda9b71ea3e79347f6666": {{Code|63 61 36 ... 00 ►}}* '''Server''' replies with success code: {{Code|◄ 00}}* '''Client''' sends the "INFO" command: {{Code|49 4E 46 4F 00 ►}}* '''Server''' responds with the result "General Information...": {{Code|◄ 47 65 6e 65 ... 00}}* '''Server''' additionally sends an (empty) info string: {{Code|◄ 00}}* '''Client''' creates a new query instance for the XQuery "1, 2+'3'": {{Code|00 31 2C 20 32 2B 27 33 27 00 ►}}* '''Server''' returns query id "1" and a success code: {{Code|◄ 31 00 00}}* '''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):<br/><{{Code|◄ 52 31 00}}* '''Server''' sends a single {{Code|\00}} byte instead of a new result, which indicates that no more results can be expected: {{Code|◄ 00}}* '''Server''' sends the error code>String execute{{Code|\01}} and the error message (String command"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}}* '''Client''' closes the socket connection

* Creates a database from an input streamMost language bindings provide the following constructors and functions:<br/><code>void create(String name, InputStream in)</code>

* Adds a document to the current database from an input stream:<br/div><code>void add(String name, String target, InputStream in)</codediv style="float:left; width:48%;">===Session===

* Replaces a document Create and return session with the specified input streamhost, port, username and password:<br/><code>void replaceSession(String pathhost, int port, String name, InputStream inString password)</code>

* Stores raw data at Execute a command and return the specified pathresult:<br/><code>void storeString execute(String path, InputStream incommand)</code>

* Watches Return a query instance for the specified eventquery:<br/><code>void watchQuery query(String name, Event notifierquery)</code>

* Unwatches the specified eventCreate a database from an input stream:<br/><code>void unwatchcreate(String name, InputStream input)</code>

* Returns process informationAdd a document to the current database from an input stream:<br/><code>void add(String info(path, InputStream input)</code>

* Closes Put a document with the sessionspecified input stream:<br/><code>void closeput(String path, InputStream input)</code>

* Creates query object with session and queryReturn process information:<br/><code>constructorString info(Session s, String query)</code>

* Binds an external variableClose the session:<br/><code>void bindclose(String name, String value)</code>

* Executes the query:<br/div><codediv style="float:left; width:4%;">String execute()&nbsp;</codediv><div style="float:left; width:48%;">===Query===

* Iterator: checks if a Create query instance with session and query returns more items:<br/><code>boolean moreQuery(Session session, String query)</code>

* Returns next itemBind an external variable:<br/><code>void bind(String name, String value, String next(type)</code><br/>The type can be an empty string.

* Returns query informationBind the context item:<br/><code>void context(String value, String info(type)</code><br/>The type can be an empty string.

* Returns serialization optionsExecute the query and return the result:<br/><code>String optionsexecute()</code>

* Closes the iterator and Iterator: check if a queryreturns more items:<br/><code>closeboolean more()</code>

* <code>\x</code>Return serialization parameters: single byte.* <code>{...}<br/code>: strings, which are transfered in the UTF8 encoding.* <code>[...]String options()</code>: binary data. All 00 and FF bytes are prefixed with FF.

===Authentication (via [http* Return if the query may perform updates:<br/><code>boolean updating()</tools.ietf.org/html/rfc2195 cram-md5])===code>

# Client connects to server socket# Server sends timestamp* Close the query:<br/><code>{timestamp} \0</code># Client sends username and hashed password/timestamp:<br/><code>{username} \0 {md5(md5void close(password) + timestamp)} \0</code># Server sends <code>\0</codediv> (success) or <code>\1</codediv style="float:left; width:100%;"> (error)

===Client Request==Changelog=

COMMAND -> * Removed: {command} \0 CREATE -> \8 {nameCode|WATCH} \0 [input] \0 ADD -> \9 {name} \0 and {path} \0 [input] \0 WATCH -> \10 {name} \0 Code|UNWATCH -> \11 {name} \0 REPLACE -> \12 {path} \0 [input] \0 STORE -> \13 {path} \0 [input] \0 QUERY: INIT -> \0 {query} \0 CLOSE -> \2 {id} \0 BIND -> \3 {id} \0 {variable} \0 {value} \0 {type} \0 ITER -> \4 {id} \0 EXECUTE -> \5 {id} \0 INFO -> \6 {id} \0 OPTIONS -> \7 {id} \0command

The server replies * Updated: cram-md5 replaced with the following byte sequencesdigest authentication* Updated: {{Code|BIND}} command:support more than one item

* [https:<//github.com/BaseXdb/basex-api/blob/master/src/main/java/BaseXClient.java Java client]* [https://github.com/BaseXdb/basex-api/blob/master/src/main/c%23/BaseXClient.cs C# client]* [https://github.com/BaseXdb/basex-api/blob/master/src/main/python/BaseXClient.py Python client]* [https://github.com/BaseXdb/basex-api/blob/master/src/main/perl/BaseXClient.pm Perl client]div>