Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
* # Clientconnects to the database server socket# Server sends timestamp "1369578179679": {{Code|31 33 36 39 35 37 38 31 37 39 36 37 39 00}}# Client send user name and hashed password/timestamp "user", md5(md5("topsecret") + "1369578179679") = "66442c0e3b5af8b9324f7e31b7f5cca8": {{Code|75 73 65 72 00 36 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 string "1" and a success code: {{Code|31 00 00}}# Client requests the query results via the RESULTS protocol command "\4 " and the query id "1": {{Code|04 31 00}}# Server returns the first result ("1", type xs:integer): {{Code|52 31 00}}# Instead of a second result, a single "\0" byte is returned, which indicates that no more results can be expected: {{Code|00}}# Next, server returns the error code "\1" and the error message ("Stopped at..."): {{Code|01 53 74 6f ... 00}}# Client closes the query instance: {{Code|02 31 00}}# Server sends the response and success code: {{Code|00 00}}# Client closes the socket connection
no edit summary
* The {{Code|execute()}} method is called to launch a database command. It returns the result or throws an exception with the received error message.
* The {{Code|query()}} method creates a query instance. Variables and the context item can be bound to that objectinstance, and the result can either be requested via {{Code|execute()}}, or in an iterative manner with the {{Code|more()}} and {{Code|next()}} functions. If an error occurs, an exception will be thrown.
* The {{Code|create()}}, {{Code|add()}}, {{Code|replace()}} and {{Code|store()}} method pass on input streams to the corresponding database commands.
* Execute a command and return the result:<br/><code>String execute(String command)</code>
* Return a query object 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 in)</code>
===Query===
* Create query object instance with session and query:<br/><code>Query(Session s, String query)</code>
* Bind an external variable:<br/><code>void bind(String name, String value, String type). The type can be an empty string.</code>
| <code>\4 {id}</code>
| <code>\x {item} ... \x {item} \0</code>
| Returns all resulting the single items as strings, prefixed by a single byte ({{Code|\x}}) that represents the [[Server Protocol: Types|Type ID]]. This command will usually be is called by the {{Code|more()}} function of a client implementation.
|-
| EXECUTE
| <code>\5 {id}</code>
| <code>{result} \0</code>
| Executes the query and returns all results as a UTF8 single string.
|-
| INFO
|}
All results end with a single {{Code|\0}} byte, which indicates that the process was successful. If an error occurs, a byte {{Code|\1}} is additionally sent instead, followed by the {{Code|error message}}.
===Example===
In the following example, a client registers a new session and calls executes the {{Code[[Commands#INFO|INFO}} ]] database command. Next, it creates a new query instance for the XQuery expression {{Code|1, 2+'3'}}, which receives the id {{Code|\1}}. The query is then evaluated via the {{Code|RESULTS}} command, 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.
==Existing Clients==
* [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]
* more client implementations are listed on the [[Clients]] page.
=Changelog=
