Difference between revisions of "Server Protocol"
Jump to navigation
Jump to search
Line 1: | Line 1: | ||
− | This page presents the | + | This page presents the classes and functions of the BaseX clients, |
− | and the | + | and the underlying protocol, which is utilized for communicating with |
− | + | the database server. | |
− | == | + | ==Workflow== |
− | * First of all, | + | * First of all, a BaseX database server must be running, which will process the client requests. |
* 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 and password as arguments. | * 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 and password as arguments. | ||
− | * | + | * The {{Mono|execute()}} method is called to launch a database command. It returns the result or throws an exception with the received error message. |
− | * The | + | * The {{Mono|query()}} method creates a query instance. Variables can be bound to that object, and the result can either be requested via {{Mono|execute()}}, or in an iterative manner with the {{Mono|more()}} and {{Mono|next()}} functions. If an error occurs, an exception will be thrown. |
− | * The | + | * The {{Mono|create()}}, {{Mono|add()}}, {{Mono|replace()}} and {{Mono|store()}} method pass on input streams to the corresponding database commands. |
* To speed up execution, an output stream can be specified by some clients; this way, all results will be directed to that output stream. | * To speed up execution, an output stream can be specified by some clients; this way, all results will be directed to that output stream. | ||
Line 65: | Line 65: | ||
==Transfer Protocol== | ==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 a new client. | ||
− | + | ===General Syntax=== | |
− | |||
− | ===Syntax=== | ||
* <code>\x</code>: single byte. | * <code>\x</code>: single byte. | ||
Line 83: | Line 82: | ||
===Command Protocol=== | ===Command Protocol=== | ||
− | The following byte sequences are sent and received from the client (please note that a specific client | + | The following byte sequences are sent and received from the client (please note that a specific client need not support all of the presented commands): |
{| class="wikitable" | {| class="wikitable" | ||
Line 140: | Line 139: | ||
===Query Command Protocol=== | ===Query Command Protocol=== | ||
− | Queries are referenced via an {{Mono|id}}, which | + | Queries are referenced via an {{Mono|id}}, which has been returned by the {{Mono|QUERY}} command (see above): |
{| class="wikitable" | {| class="wikitable" | ||
Line 159: | Line 158: | ||
| Binds a value to a variable. | | Binds a value to a variable. | ||
|- | |- | ||
− | | | + | | RESULTS |
| <code>\4 {id}</code> | | <code>\4 {id}</code> | ||
| <code>\t {item 1} ... \t {item n} \0</code> | | <code>\t {item 1} ... \t {item n} \0</code> | ||
− | | Returns all results of the query, prefixed by their [[Server Protocol/Data Types|Data Type]] | + | | Returns all results of the query, prefixed by their [[Server Protocol/Data Types|Data Type]] {{Mono|\t}}. |
|- | |- | ||
| EXECUTE | | EXECUTE | ||
Line 187: | Line 186: | ||
| <code>\31 {id}</code> | | <code>\31 {id}</code> | ||
| <code>{meta 1} {item 1} ... {meta n} {item n} \0</code> | | <code>{meta 1} {item 1} ... {meta n} {item n} \0</code> | ||
− | | {{Version|7.1.2}}: Returns all results of the query, prefixed by their [[Server Protocol | + | | {{Version|7.1.2}}: Returns all results of the query, prefixed by their [[Server Protocol#XDM Meta Data|XDM meta data]]. |
|- | |- | ||
| ↯ error | | ↯ error | ||
Line 195: | Line 194: | ||
|} | |} | ||
− | ===Examples | + | ===XDM Meta Data=== |
+ | |||
+ | ==Examples== | ||
* [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/java/BaseXClient.java Java client] |
Revision as of 18:00, 2 March 2012
This page presents the classes and functions of the BaseX clients, and the underlying protocol, which is utilized for communicating with the database server.
Contents
Workflow
- First of all, a BaseX database server must be running, which will process the client requests.
- 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 and password as arguments.
- The
execute()
method is called to launch a database command. It returns the result or throws an exception with the received error message.
- The
query()
method creates a query instance. Variables can be bound to that object, and the result can either be requested viaexecute()
, or in an iterative manner with themore()
andnext()
functions. If an error occurs, an exception will be thrown.
- The
create()
,add()
,replace()
andstore()
method pass on input streams to the corresponding database commands.
- To speed up execution, an output stream can be specified by some clients; this way, all results will be directed to that output stream.
- Most clients are accompanied by some example files, which demonstrate how database commands can be executed or how queries can be evaluated.
Code Structure
Session
- Creates and returns session with host, port, user name and password:
Session(String host, int port, String name, String password)
- Executes a command and returns the result:
String execute(String command)
- Returns a query object for the specified query:
Query query(String query)
- Creates a database from an input stream:
void create(String name, InputStream in)
- Adds a document to the current database from an input stream:
void add(String path, InputStream in)
- Replaces a document with the specified input stream:
void replace(String path, InputStream in)
- Stores raw data at the specified path:
void store(String path, InputStream in)
- Watches the specified event:
void watch(String name, Event notifier)
- Unwatches the specified event:
void unwatch(String name)
- Returns process information:
String info()
- Closes the session:
void close()
Query
- Creates query object with session and query:
constructor(Session s, String query)
- Binds an external variable:
void bind(String name, String value)
- Executes the query:
String execute()
- Iterator: checks if a query returns more items:
boolean more()
- Returns next item:
String next()
- Returns query information:
String info()
- Returns serialization options:
String options()
- Closes the iterator and query:
close()
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 a new client.
General Syntax
\x
: single byte.{...}
: utf8 strings and raw data, suffixed with a\0
byte. To avoid confusion with the suffix byte, all\0
and\FF
bytes that occur in the data itself need to be prefixed with\FF
.
Authentication (via cram-md5)
- Client connects to server socket
- Server sends timestamp:
{timestamp}
- Client sends username and hashed password/timestamp:
{username} {md5(md5(password) + timestamp)}
- Server replies with
\0
(success) or\1
(error)
Command Protocol
The following byte sequences are sent and received from the client (please note that a specific client need not support all of the presented commands):
Command | Client Request | Server Response | Description |
---|---|---|---|
COMMAND | {command}
|
{result} {info} \0
|
Executes a database command. |
QUERY | \0 {query}
|
{id} \0
|
Creates a new query instance and returns its id. |
CREATE | \8 {name} {input}
|
{info} \0
|
Creates a new database with the specified input (may be empty). |
ADD | \9 {name} {path} {input}
|
{info} \0
|
Adds a new resource to the opened database. |
WATCH | \10 {name}
|
|
Registers the client for the specified event. |
UNWATCH | \11 {name}
|
|
Unregisters the client. |
REPLACE | \12 {path} {input}
|
{info} \0
|
Replaces a resource with the specified input. |
STORE | \13 {path} {input}
|
{info} \0
|
Stores a binary resource in the opened database. |
↯ error |
|
{ beginning of result} {error} \1
|
Error feedback. |
Query Command Protocol
Queries are referenced via an id
, which has been returned by the QUERY
command (see above):
Query Command | Client Request | Server Response | Description |
---|---|---|---|
CLOSE | \2 {id}
|
\0 \0
|
Closes and unregisters the query with the specified id. |
BIND | \3 {id} {name} {value} {type}
|
\0 \0
|
Binds a value to a variable. |
RESULTS | \4 {id}
|
\t {item 1} ... \t {item n} \0
|
Returns all results of the query, prefixed by their Data Type \t .
|
EXECUTE | \5 {id}
|
{result} \0
|
Executes the query and returns all results as a UTF8 string. |
INFO | \6 {id}
|
{result} \0
|
Returns a query info string. |
OPTIONS | \7 {id}
|
{result} \0
|
Returns a string with all query serialization parameters. |
UPDATING | \30 {id}
|
{result} \0
|
Version 7.1.2: Returns true if the query may perform updates; false otherwise.
|
FULL | \31 {id}
|
{meta 1} {item 1} ... {meta n} {item n} \0
|
Version 7.1.2: Returns all results of the query, prefixed by their XDM meta data. |
↯ error |
|
{ beginning of result} \1 {error}
|
Error feedback. |