Server Protocol - Revision history

CG: /* Command Protocol */

2023-06-29T14:30:12Z

Command Protocol

CG: /* CRAM-MD5 */

2022-10-26T08:13:28Z

CRAM-MD5

CG at 13:42, 25 July 2022

2022-07-25T13:42:44Z

CG at 13:42, 25 July 2022

2022-07-25T13:42:38Z

CG at 13:40, 25 July 2022

2022-07-25T13:40:58Z

CG at 15:26, 19 July 2022

2022-07-19T15:26:17Z

CG at 18:55, 18 July 2022

2022-07-18T18:55:27Z

CG: /* Workflow */

2022-02-23T10:17:02Z

Workflow

CG: /* Workflow */

2022-02-23T10:14:34Z

Workflow

CG: /* Workflow */

2022-02-23T10:09:38Z

Workflow

@@ Line 83: / Line 83: @@
 |-
 | ADD
-| <code>\09 {name} {path} {input}</code>
+| <code>\09 {path} {input}</code>
 | <code>{info} \00</code>
 | Adds a new document to the opened database.

@@ Line 45: / Line 45: @@
 ====CRAM-MD5====
-CRAM-MD5 was discarded, because unsalted md5 hashes could easily be uncovered
+CRAM-MD5 was discarded because unsalted md5 hashes can easily be uncovered using rainbow tables. However, most client bindings still provide support for the outdated handshaking, as it only slightly differs from the new protocol:
 # Client connects to server socket
@@ Line 56: / Line 54: @@
 # Server replies with <code>\00</code> (success) or <code>\01</code> (error)
-Clients can easily be implemented to both support {{Code|digest}} and {{Code|cram-md5}} authentication: If the first server response contains no colon, {{Code|cram-md5}} should be chosen.
+It is possible to support both {{Code|digest}} and {{Code|cram-md5}} authentication in clients: If the first server response contains no colon, {{Code|cram-md5}} should be chosen.
 ===Command Protocol===

@@ Line 166: / Line 166: @@
 ====Binding Sequences====
-Also sequences can be bound to variables and the context:
+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.

@@ Line 159: / Line 159: @@
 | <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 Data|XDM Meta Data]]. This command is e. g. used by the [[Developing|XQJ API]].
+| Returns all resulting items as strings, prefixed by the [[Server Protocol: Types#XDM Metadata|XDM Metadata]]. This command is e. g. used by the [[Developing|XQJ API]].
 |}

@@ Line 8: / Line 8: @@
 * 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 and password as arguments.
+* 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, 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.
@@ Line 38: / Line 38: @@
 # Client connects to server socket
 # Server sends a '''realm''' and '''nonce''', separated by a colon: <code>{realm:nonce}</code>
-# Client sends the '''user name''' and a hash value. The hash is composed of the md5 hash of
+# Client sends the '''username''' and a hash value. The hash is composed of the md5 hash of
-## the md5 hash of the '''user name''', '''realm''', and '''password''' (all separated by a colon), and
+## the md5 hash of the '''username''', '''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)
@@ Line 51: / Line 51: @@
 # Client connects to server socket
 # Server sends a '''nonce''' (timestamp): <code>{nonce}</code>
-# Client sends the '''user name''' and a hash value. The hash is composed of the md5 hash of
+# Client sends the '''username''' 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>
@@ Line 183: / Line 183: @@
 * '''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 "jack": {{Code|6A 61 63 6B 00 ►}}
+* '''Client''' sends 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}}
@@ Line 207: / Line 207: @@
 ===Session===
-* Create and return session with host, port, user name and password:<br/><code>Session(String host, int port, String name, String password)</code>
+* Create and return session with host, port, 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>

@@ Line 14: / Line 14: @@
 * 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|replace()}} and {{Code|store()}} 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.
+* The {{Code|create()}}, {{Code|add()}}, {{Code|put()}} and {{Code|putbinary()}} 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.
@@ Line 87: / Line 87: @@
 | <code>\09 {name} {path} {input}</code>
 | <code>{info} \00</code>
-| Adds a new resource to the opened database.
+| Adds a new document to the opened database.
 |-
-| REPLACE
+| PUT
 | <code>\0C {path} {input}</code>
 | <code>{info} \00</code>
-| Replaces a resource with the specified input.
+| Puts (adds or replaces) an XML document resource in the opened database.
 |-
-| STORE
+| PUTBINARY
 | <code>\0D {path} {input}</code>
 | <code>{info} \00</code>
-| Stores a binary resource in the opened database.
+| Puts (adds or replaces) a binary resource in the opened database.
 |-
 | ↯ error
@@ Line 217: / Line 217: @@
 * Add a document to the current database from an input stream:<br/><code>void add(String path, InputStream input)</code>
-* Replace a document with the specified input stream:<br/><code>void replace(String path, InputStream input)</code>
+* Put a document with the specified input stream:<br/><code>void put(String path, InputStream input)</code>
-* Store raw data at the specified path:<br/><code>void store(String path, InputStream input)</code>
+* Put a binary resource at the specified path:<br/><code>void putBinary(String path, InputStream input)</code>
 * Return process information:<br/><code>String info()</code>

@@ Line 179: / Line 179: @@
 ==Example==
-In the following example, a client registers a new session and executes the [[Commands#INFO|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.
+In the following example, a client registers a new session and executes the {{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