Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
Created page with "This page presents the client/server protocol of BaseX, which is needed to write clients in other programming languages. ==Description== Each client provides a session class or..."
This page presents the client/server protocol of BaseX, which is needed to
write clients in other programming languages.
==Description==
Each client provides a session class or script with methods
to connect to and communicate with the BaseX 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 <code>execute()</code>
method with the database command as argument. The method returns the
result or throws an exception with the received error message.
To speedup execution, an output stream can be specified by some clients;
this way, all results will be directed to that output stream.
The <code>query()</code> method creates a query instance. Variables can be
bound to that object, and the result can either be requested by
<code>execute()</code>, or in an iterative manner with the
<code>more()</code> and <code>next()</code> functions.
If an error occurs, an exception will be thrown.
The <code>create()</code>, <code>add()</code>, <code>replace()</code>
and <code>store()</code> method can be used to pass on input streams
to the corresponding database commands.
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:<br/><code>Session(String host, int port, String name, String password)</code>
* Executes a command and returns the result:<br/><code>String execute(String command)</code>
* Returns a query object for the specified query:<br/><code>Query query(String query)</code>
* Creates a database from an input stream:<br/><code>void create(String name, InputStream in)</code>
* Adds a document to the current database from an input stream:<br/><code>void add(String name, String target, InputStream in)</code>
* Replaces a document with the specified input stream:<br/><code>void replace(String path, InputStream in)</code>
* Stores raw data at the specified path:<br/><code>void store(String path, InputStream in)</code>
* Watches the specified event:<br/><code>void watch(String name, Event notifier)</code>
* Unwatches the specified event:<br/><code>void unwatch(String name)</code>
* Returns process information:<br/><code>String info()</code>
* Closes the session:<br/><code>void close()</code>
===Query===
* Creates query object with session and query:<br/><code>constructor(Session s, String query)</code>
* Binds an external variable:<br/><code>void bind(String name, String value)</code>
* Executes the query:<br/><code>String execute()</code>
* Iterator: checks if a query returns more items:<br/><code>boolean more()</code>
* Returns next item:<br/><code>String next()</code>
* Returns query information:<br/><code>String info()</code>
* Returns serialization options:<br/><code>String options()</code>
* Closes the iterator and query:<br/><code>close()</code>
==Transfer Protocol==
===Syntax===
* String (UTF8): <code>{...}</code>
* Single Byte: <code>\X</code>
===Authentication===
# Client connects to server socket
# Server sends timestamp: <code>{timestamp} \0</code>
# Client sends username and hash: <code>{username} \0 {md5(md5(password) + timestamp)} \0</code>
# Server sends <code>\0</code> (success) or <code>\1</code> (error)
===Client request===
- command: -> {command} \0
- create: -> \8 {name} \0 {input} \0
- add: -> \9 {name} \0 {path} \0 {input} \0
- watch: -> \10 {name} \0
- unwatch: -> \11 {name} \0
- replace: -> \12 {path} \0 {input} \0
- store: -> \13 {path} \0 {input} \0
- query: start -> \0 {query} \0
bind -> \3 {id} \0 {variable} \0 {value} \0 {type} \0
next -> \1 {id} \0
execute -> \5 {id} \0
info -> \6 {id} \0
options -> \7 {id} \0
close -> \2 {id} \0
===Server response===
- command: -> {result} \0 {info} \0 \0
- create: -> {info} \0 \0
- add: -> {info} \0 \0
error -> \0 {error} \0 \1
- query: start -> {id} \0 \0
bind -> \0 \0
next -> {result} \0 \0
execute -> {result} \0 \0
info -> {result} \0 \0
options -> {result} \0 \0
close -> \0 \0
error -> \0 \1 {error} \0
write clients in other programming languages.
==Description==
Each client provides a session class or script with methods
to connect to and communicate with the BaseX 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 <code>execute()</code>
method with the database command as argument. The method returns the
result or throws an exception with the received error message.
To speedup execution, an output stream can be specified by some clients;
this way, all results will be directed to that output stream.
The <code>query()</code> method creates a query instance. Variables can be
bound to that object, and the result can either be requested by
<code>execute()</code>, or in an iterative manner with the
<code>more()</code> and <code>next()</code> functions.
If an error occurs, an exception will be thrown.
The <code>create()</code>, <code>add()</code>, <code>replace()</code>
and <code>store()</code> method can be used to pass on input streams
to the corresponding database commands.
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:<br/><code>Session(String host, int port, String name, String password)</code>
* Executes a command and returns the result:<br/><code>String execute(String command)</code>
* Returns a query object for the specified query:<br/><code>Query query(String query)</code>
* Creates a database from an input stream:<br/><code>void create(String name, InputStream in)</code>
* Adds a document to the current database from an input stream:<br/><code>void add(String name, String target, InputStream in)</code>
* Replaces a document with the specified input stream:<br/><code>void replace(String path, InputStream in)</code>
* Stores raw data at the specified path:<br/><code>void store(String path, InputStream in)</code>
* Watches the specified event:<br/><code>void watch(String name, Event notifier)</code>
* Unwatches the specified event:<br/><code>void unwatch(String name)</code>
* Returns process information:<br/><code>String info()</code>
* Closes the session:<br/><code>void close()</code>
===Query===
* Creates query object with session and query:<br/><code>constructor(Session s, String query)</code>
* Binds an external variable:<br/><code>void bind(String name, String value)</code>
* Executes the query:<br/><code>String execute()</code>
* Iterator: checks if a query returns more items:<br/><code>boolean more()</code>
* Returns next item:<br/><code>String next()</code>
* Returns query information:<br/><code>String info()</code>
* Returns serialization options:<br/><code>String options()</code>
* Closes the iterator and query:<br/><code>close()</code>
==Transfer Protocol==
===Syntax===
* String (UTF8): <code>{...}</code>
* Single Byte: <code>\X</code>
===Authentication===
# Client connects to server socket
# Server sends timestamp: <code>{timestamp} \0</code>
# Client sends username and hash: <code>{username} \0 {md5(md5(password) + timestamp)} \0</code>
# Server sends <code>\0</code> (success) or <code>\1</code> (error)
===Client request===
- command: -> {command} \0
- create: -> \8 {name} \0 {input} \0
- add: -> \9 {name} \0 {path} \0 {input} \0
- watch: -> \10 {name} \0
- unwatch: -> \11 {name} \0
- replace: -> \12 {path} \0 {input} \0
- store: -> \13 {path} \0 {input} \0
- query: start -> \0 {query} \0
bind -> \3 {id} \0 {variable} \0 {value} \0 {type} \0
next -> \1 {id} \0
execute -> \5 {id} \0
info -> \6 {id} \0
options -> \7 {id} \0
close -> \2 {id} \0
===Server response===
- command: -> {result} \0 {info} \0 \0
- create: -> {info} \0 \0
- add: -> {info} \0 \0
error -> \0 {error} \0 \1
- query: start -> {id} \0 \0
bind -> \0 \0
next -> {result} \0 \0
execute -> {result} \0 \0
info -> {result} \0 \0
options -> {result} \0 \0
close -> \0 \0
error -> \0 \1 {error} \0
