Server Protocol
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.
Class 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:
Query(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 parameters:
String options()
- Returns if the query may perform updates:
boolean updating()
- Closes the iterator and query:
void 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}
|
\x {item} ... \x {item} \0
|
Returns all resulting items as strings, prefixed by a Type byte (\x ).
|
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}
|
XDM {item} ... XDM {item} \0
|
Version 7.1.2: Returns all resulting items as strings, prefixed by XDM Meta Data (see below). |
↯ error |
|
{ beginning of result} \1 {error}
|
Error feedback. |
XDM Meta Data
In most cases, the XDM meta data boils down to a single byte, which represents the node kind or item type. There are three exceptions: document-node()
, attribute()
and xs:QName
items are followed by an additional {URI}
string.