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.

==Code StructureTransfer Protocol==

* Executes <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 returns the result:<brcode>\FF</code>bytes are prefixed by an additional <code>String execute(String command)\FF</code>byte.

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

* Replaces # 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 insuccess)or <code>\01</code>(error)

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

* Unwatches the specified event# Client connects to server socket# Server sends a '''nonce''' (timestamp):<br/><code>void unwatch(String name){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* Returns process information## the '''nonce''':<br/><code>String info{username} {md5(md5(password) + nonce)}</code> * Closes the session:# Server replies with <br/code>\00</code>void close(success)or <code>\01</code>(error)

===Query=== * Creates query object with session and query:<br/><code>constructor(Session s, String query)</code> * Binds an external variable:<br/><code>void bind(String name, String value)</code> * Executes the query:<br/><code>String execute()</code> * Iterator: checks if a query returns more items:<br/><code>boolean more()</code> * Returns next item:<br/><code>String next()</code> * Returns query information:<br/><code>String info()</code> * Returns serialization options:<br/><code>String options()</code> * Closes the iterator and query:<br/><code>close()</code> ==Transfer Protocol== The protocol below has been introduced with Version 6.3.1 of BaseX. Please note that the protocol for iterative query execution has changed a little, though: From Version 6.3.1 to 6.7.1 of BaseX, iterative queries could lead It is possible to deadlocks if query iterators were not properly closed. Since support both {{VersionCode|7.0digest}}, the ITER command returns all results of a query in one go, and the iterative execution of clients is left to the client code. ===Syntax=== * <code>\x</code>: single byte.* <code>{...{Code|cram-md5}}</code>authentication in clients: utf8 strings and raw data, suffixed with a <code>\0</code> byte. To avoid confusion with If the suffix bytefirst server response contains no colon, all <code>\0</code> and <code>\FF</code> bytes that occur in the data itself need to 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:<br/><code>{timestamp}</code># Client sends username and hashed password/timestamp:<br/><code>{username} {md5(md5(password) + timestamp)}</code># Server replies with <code>\0</code> (success) or <code>\1</code> (error)should be chosen.

The following byte sequences are sent and received from the client (please note that a specific client may, and need, not support all of the presented commands):

| <code>{result} {info} \000</code>| Executes a BaseX database command.

| <code>\0 00 {query}</code>| <code>{id} \000</code>| Creates a new query object instance and returns its id.

| <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 in document to the opened database.|-| WATCH| <code>\10 {name}</code>| <code></code>| Registers the client for the specified event.|-| UNWATCH| <code>\11 {name}</code>| <code></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>''beginning of partial result''<code>} {error} \101</code>

Queries are referenced via an {{MonoCode|id}}, which is supplied has been returned by the server {{Code|QUERY}} command (see QUERY command above):.

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

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

| ITERRESULTS| <code>\4 04 {id}</code>| <code>\t xx {item 1} ... \t xx {item n} \000</code>| Returns all results of the queryresulting items as strings, prefixed by their a single byte ({{Code|\xx}}) that represents the [[Server Protocol/Data : Types|Data TypeID]] encoded in . This command is called by the {{MonoCode|\tmore()}}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 UTF8 single string.

| <code>\6 06 {id}</code>| <code>{result} \000</code>| Returns a string with query compilation and profiling info string.

| <code>\7 07 {id}</code>| <code>{result} \000</code>| Returns the 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.

| <code>\31 1F {id}</code>| <code>{meta 1} ''XDM'' {item 1} ... {meta n} ''XDM'' {item n} \000</code>| {{Version|7.1.2}}: Returns all results of the queryresulting items as strings, prefixed by their the [[Server Protocol/: Types#XDM Meta DataMetadata|XDM meta dataMetadata]].This command is e. g. used by the [[Developing|-| ↯ error| <code></code>| <code>{</code>''beginning of result''<code>} \1 {error}</code>| Error feedbackXQJ 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. ===Examples=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}}. ==Example== In the following example, a client registers a new session and executes the {{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''' 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): {{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 {{Code|\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}}* '''Client''' closes the socket connection ==Constructors 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> * Add a document to the current database from an input stream:<br/><code>void add(String path, InputStream input)</code> * Put a document with the specified input stream:<br/><code>void put(String path, InputStream input)</code> * Put a binary resource at the specified path:<br/><code>void putBinary(String path, InputStream input)</code> * Return process information:<br/><code>String info()</code> * Close 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 and query:<br/><code>Query(Session session, String query)</code> * Bind an external variable:<br/><code>void bind(String name, String value, String type)</code><br/>The type can be an empty string. * Bind the context item:<br/><code>void context(String value, String type)</code><br/>The type can be an empty string. * Execute the query and return the result:<br/><code>String execute()</code> * Iterator: check if a query returns more items:<br/><code>boolean more()</code> * Iterator: return the next item:<br/><code>String next()</code> * Return query information:<br/><code>String info()</code> * Return serialization parameters:<br/><code>String options()</code> * Return if the query may perform updates:<br/><code>boolean updating()</code> * Close the query:<br/><code>void close()</code></div><div style="float:left; width:100%;"> =Changelog= ;Version 8.2 * Removed: {{Code|WATCH}} and {{Code|UNWATCH}} command ;Version 8.0 * Updated: cram-md5 replaced with digest authentication* Updated: {{Code|BIND}} command: support more than one item ;Version 7.2 * Added: Query Commands CONTEXT, UPDATING and FULL* Added: Client function {{Code|context(String value, String type)}}

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