Difference between revisions of "Server Protocol"

From BaseX Documentation
Jump to navigation Jump to search
Line 125: Line 125:
 
| WATCH
 
| WATCH
 
| <code>\10 {name}</code>
 
| <code>\10 {name}</code>
| <code></code>
+
| <code>{info} \0</code>
 
| Registers the client for the specified event.
 
| Registers the client for the specified event.
 
|-
 
|-
 
| UNWATCH
 
| UNWATCH
 
| <code>\11 {name}</code>
 
| <code>\11 {name}</code>
| <code></code>
+
| <code>{info} \0</code>
 
| Unregisters the client.
 
| Unregisters the client.
 
|-
 
|-

Revision as of 12:07, 17 May 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.

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

  • Create and return session with host, port, user name and password:
    Session(String host, int port, String name, String password)
  • Execute a command and return the result:
    String execute(String command)
  • Return a query object for the specified query:
    Query query(String query)
  • Create a database from an input stream:
    void create(String name, InputStream in)
  • Add a document to the current database from an input stream:
    void add(String path, InputStream in)
  • Replace a document with the specified input stream:
    void replace(String path, InputStream in)
  • Store raw data at the specified path:
    void store(String path, InputStream in)
  • Watch the specified event:
    void watch(String name, Event notifier)
  • Unwatch the specified event:
    void unwatch(String name)
  • Return process information:
    String info()
  • Close the session:
    void close()
 

Query

  • Create query object with session and query:
    Query(Session s, String query)
  • Bind an external variable:
    void bind(String name, String value, String type). The type can be an empty string.
  • Version 7.2: Bind the context item:
    void context(String value, String type). The type can be an empty string.
  • Execute the query and return the result:
    String execute()
  • Iterator: check if a query returns more items:
    boolean more()
  • Iterator: return the next item:
    String next()
  • Return query information:
    String info()
  • Return serialization parameters:
    String options()
  • Return if the query may perform updates:
    boolean updating()
  • Close the 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 or raw data, suffixed with a \0 byte. To avoid confusion with the suffix byte, all \0 and \FF bytes that occur in raw data will 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 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} {info} \0 Registers the client for the specified event.
UNWATCH \11 {name} {info} \0 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. An empty string can be specified as data type.
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.
CONTEXT \14 {id} {value} {type} \0 \0 Version 7.2: Binds a value to the context item. An empty string can be specified as data type.
UPDATING \30 {id} {result} \0 Version 7.2: Returns true if the query may perform updates; false otherwise.
FULL \31 {id} XDM {item} ... XDM {item} \0 Version 7.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.

Examples

Changelog

Version 7.2

  • Added: Query Commands CONTEXT, UPDATING and FULL