Server Protocol

From BaseX Documentation
Revision as of 13:14, 10 October 2011 by Michael (talk | contribs) (Text replace - "<font color='orangered'>Version 7.0</font>" to "{{Version|7.0}}")
Jump to navigation Jump to search

This page presents the code structure of the BaseX clients, and the client/server protocol needed to write Clients in other programming languages.

Description

  • First of all, the BaseX database server must be running in order to use the clients.
  • 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.
  • For the execution of commands you need to call the execute() method with the database command as argument. The method 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 by execute(), or in an iterative manner with the more() and next() functions. If an error occurs, an exception will be thrown.
  • The create(), add(), replace() and store() method can be used to 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 name, String target, 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

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 to deadlocks if query iterators were not properly closed. Since Version 7.0, 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

  • \x: single byte.
  • {...}: 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)

  1. Client connects to server socket
  2. Server sends timestamp:
    {timestamp}
  3. Client sends username and hashed password/timestamp:
    {username} {md5(md5(password) + timestamp)}
  4. 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 may, and need, not support all of the presented commands):

Command Client Request Server Response
COMMAND {command} {result} {info} \0
QUERY \0 {query} {id} \0
CREATE \8 {name} {input} {info} \0
ADD \9 {name} {path} {input} {info} \0
WATCH \10 {name}
UNWATCH \11 {name}
REPLACE \12 {path} {input} {info} \0
STORE \13 {path} {input} {info} \0
↯ error {start of response} {error} \1

Queries are referenced with an id, which is supplied by the server (see QUERY command above):

Command Client Request Server Response
CLOSE \2 {id} \0 \0
BIND \3 {id} {name} {value} {type} \0 \0
ITER \4 {id} \1 {item 1} ... \1 {item n} \0
EXECUTE \5 {id} {result} \0
INFO \6 {id} {result} \0
OPTIONS \7 {id} {result} \0
↯ error {start of response} \1 {error}

Examples