Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
Clients can easily be implemented It is possible to support both support {{Code|digest}} and {{Code|cram-md5}} authenticationin clients: If the first server response contains no colon, {{Code|cram-md5}} should be chosen.
[[Category:Developer]]
[[Category:Server]]
[[Category:API]]
→Command Protocol
* All clients are based on the client/server architecture. Hence, a BaseX database server must be started first.
* 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 username and password as arguments.
* The {{Code|execute()}} method is called to launch a database command. It returns the result or throws an exception with the received error message.
* The {{Code|query()}} method creates a query instance. Variables and the context item can be bound to that instance, and the result can either be requested via {{Code|execute()}}, or in an iterative manner with the {{Code|more()}} and {{Code|next()}} functions. If an error occurs, an exception will be thrown.
* The {{Code|create()}}, {{Code|add()}}, {{Code|replaceput()}} and {{Code|storeputbinary()}} method methods pass on input streams to the corresponding database commands. The input can be a UTF-8 encoded XML document, a binary resource, or any other data (such as JSON or CSV) that can be successfully converted to a resource by the server.
* To speed up execution, an output stream can be specified by some clients; this way, all results will be directed to that output stream.
* <code>\xx</code>: single byte.
* <code>{...}</code>: utf8 strings or raw data, suffixed with a <code>\00</code> byte. To avoid confusion with this end-of-string byte, all transfered transferred <code>\00</code> and <code>\FF</code> bytes are prefixed by an additional <code>\FF</code> byte.
===Authentication===
# Client connects to server socket
# Server sends a '''realm''' and '''nonce''', separated by a colon: <code>{realm:nonce}</code>
# Client sends the '''user nameusername''' and a hash value. The hash is composed of the md5 hash of## the md5 hash of the '''user nameusername''', '''realm''', and '''password''' (all separated by a colon), and
## the '''nonce''': <code>{username} {md5(md5(username:realm:password) + nonce)}</code>
# Server replies with <code>\00</code> (success) or <code>\01</code> (error)
====CRAM-MD5====
CRAM-MD5 was discarded, because unsalted md5 hashes could can easily be uncoveredusing rainbow tables. However, most client bindings still provide support forthe outdated handshaking, as it only slightly differs from the new protocol:
# Client connects to server socket
# Server sends a '''nonce''' (timestamp): <code>{nonce}</code>
# Client sends the '''user nameusername''' and a hash value. The hash is composed of the md5 hash of
## the md5 of the '''password''' and
## the '''nonce''': <code>{username} {md5(md5(password) + nonce)}</code>
# Server replies with <code>\00</code> (success) or <code>\01</code> (error)
===Command Protocol===
|-
| ADD
| <code>\09 {name} {path} {input}</code>
| <code>{info} \00</code>
| Adds a new resource document to the opened database.
|-
| REPLACEPUT
| <code>\0C {path} {input}</code>
| <code>{info} \00</code>
| Replaces a Puts (adds or replaces) an XML document resource with in the specified inputopened database.
|-
| STOREPUTBINARY
| <code>\0D {path} {input}</code>
| <code>{info} \00</code>
| Stores Puts (adds or replaces) a binary resource in the opened database.
|-
| ↯ error
| <code>\07 {id}</code>
| <code>{result} \00</code>
| Returns a string with all query serialization parameters, which can e.g. be assigned to the [[Options#SERIALIZER{{Option|SERIALIZER]] }} option.
|-
| CONTEXT
| <code>\1F {id}</code>
| <code>''XDM'' {item} ... ''XDM'' {item} \00</code>
| Returns all resulting items as strings, prefixed by the [[Server Protocol: Types#XDM Meta DataMetadata|XDM Meta DataMetadata]]. This command is e. g. used by the [[Developing|XQJ API]].
|}
====Binding Sequences====
Also , sequences can be bound to variables and the context:
* {{Code|empty-sequence()}} must be supplied as type if an empty sequence is to be bound.
==Example==
In the following example, a client registers a new session and executes the [[Commands#INFO{{Command|INFO]] }} database command. Next, it creates a new query instance for the XQuery expression {{Code|1, 2+'3'}}. The query is then evaluated, and the server returns the result of the first subexpression {{Code|1}} and an error for the second sub expression. Finally, the query instance and client session are closed.
* '''Client''' connects to the database server socket
* '''Server''' sends realm and timestamp "BaseX:1369578179679": {{Code|◄ 42 61 73 65 58 3A 31 33 36 39 35 37 38 31 37 39 36 37 39 00}}
* '''Client''' sends user name username "jack": {{Code|6A 61 63 6B 00 ►}}
* '''Client''' sends hash: md5(md5("jack:BaseX:topsecret") + "1369578179679") = "ca664a31f8deda9b71ea3e79347f6666": {{Code|63 61 36 ... 00 ►}}
* '''Server''' replies with success code: {{Code|◄ 00}}
===Session===
* Create and return session with host, port, user name username and password:<br/><code>Session(String host, int port, String name, String password)</code>
* Execute a command and return the result:<br/><code>String execute(String command)</code>
* Add a document to the current database from an input stream:<br/><code>void add(String path, InputStream input)</code>
* Replace Put a document with the specified input stream:<br/><code>void replaceput(String path, InputStream input)</code>
* Store raw data Put a binary resource at the specified path:<br/><code>void storeputBinary(String path, InputStream input)</code>
* Return process information:<br/><code>String info()</code>
</div>
