Difference between revisions of "Client Module"

From BaseX Documentation
Jump to navigation Jump to search
(57 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This [[Module Library|XQuery Module]] contains functions to access remote BaseX server instances from XQuery. With this module, you can on the one hand execute database commands and on the other hand evaluate queries, the results of which are returned as XDM sequences.
+
This [[Module Library|XQuery Module]] contains functions to access BaseX server instances from XQuery. With this module, you can execute database commands and evaluate XQuery expressions.
 +
 
 +
Please note that the client module should always be used to address independent BaseX server instances. You can create deadlocks if you evaluate a query with a server instance, and if you are addressing the same server instance in your query. See the following example:
 +
 
 +
<syntaxhighlight lang="xquery">
 +
(: Retrieve documents from database :)
 +
let $client-id := client:connect('localhost', 1984, 'admin', '...')
 +
let $docs := client:query($client-id, 'db:get("conflict")')
 +
(: Create database with same name :)
 +
return db:create('conflict', $docs, $docs ! db:path(.))
 +
</syntaxhighlight>
 +
 
 +
The read-only query cannot be processed, because the <code>conflict</code> database is currently write-locked by the main query. See [[Transaction Management]] for more background information.
  
 
=Conventions=
 
=Conventions=
  
All functions in this module are assigned to the {{Code|http://basex.org/modules/client}} namespace, which is statically bound to the {{Code|client}} prefix.<br/>
+
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/client</nowiki></code> namespace, which is statically bound to the {{Code|client}} prefix.<br/>
All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
 
  
 
=Functions=
 
=Functions=
  
 
==client:connect==
 
==client:connect==
{|
+
 
|-
+
{| width='100%'
| width='90' | '''Signatures'''
+
|- valign="top"
|{{Func|client:connect|$host as xs:string, $port as xs:integer, $user as xs:string, $password as xs:string|xs:anyURI}}<br/ >
+
| width='120' | '''Signatures'''
|-
+
|{{Func|client:connect|$host as xs:string, $port as xs:integer, $username as xs:string, $password as xs:string|xs:anyURI}}<br/ >
 +
|- valign="top"
 
|'''Summary'''
 
|'''Summary'''
|This function establishes a connection to a remote BaseX server, creates a new client session, and returns a session id. The parameter {{Code|$host}} is the name of the database server, {{Code|$port}} specifies the server port, and {{Code|$user}} and {{Code|$password}} represent the login data.
+
|This function establishes a connection to a remote BaseX server, creates a new client session, and returns a session id. The parameter {{Code|$host}} is the name of the database server, {{Code|$port}} specifies the server port, and {{Code|$username}} and {{Code|$password}} represent the login data.
|-
+
|- valign="top"
 
|'''Errors'''
 
|'''Errors'''
|{{Error|BXCL0001|#Errors}} an error occurs while creating the session (possible reasons: server not available, access denied).<br/>
+
|{{Error|connect|#Errors}} an error occurs while creating the session (possible reasons: server not available, access denied).<br/>
 
|}
 
|}
  
 
==client:execute==
 
==client:execute==
{|
+
 
|-
+
{| width='100%'
| width='90' | '''Signatures'''
+
|- valign="top"
 +
| width='120' | '''Signatures'''
 
|{{Func|client:execute|$id as xs:anyURI, $command as xs:string|xs:string}}
 
|{{Func|client:execute|$id as xs:anyURI, $command as xs:string|xs:string}}
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
| This function executes a database command and returns the result as string. The parameter {{Code|$id}} contains the session id returned by [[Client Module#client:connect|client:connect()]]. The {{Code|$command}} represents the database command string, which will be executed by the server.
+
| This function executes a [[Commands|command]] and returns the result as a string. The parameter {{Code|$id}} contains the session ID returned by {{Function||client:connect}}. The {{Code|$command}} argument represents a single command, which will be executed by the server.
|-
+
|- valign="top"
 
|'''Errors'''
 
|'''Errors'''
|{{Error|BXCL0003|#Errors}} an I/O error occurs while transferring data from or to the server.<br/>{{Error|BXCL0004|#Errors}} an error occurs while executing a command.
+
|{{Error|error|#Errors}} an I/O error occurs while transferring data from or to the server.<br/>{{Error|command|#Errors}} an error occurs while executing a command.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|The following query creates a new database {{Code|TEST}} on a remote BaseX server:
 
|The following query creates a new database {{Code|TEST}} on a remote BaseX server:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
let $c := client:connect('basex.server.org', 8080, 'admin', 'admin')
+
client:connect('basex.server.org', 8080, 'admin', '...') !
return client:execute($c, 'create database TEST')
+
  client:execute(., 'create database TEST')
</pre>
+
</syntaxhighlight>
 +
|}
 +
 
 +
==client:info==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signatures'''
 +
|{{Func|client:info|$id as xs:anyURI|xs:string}}
 +
|- valign="top"
 +
| '''Summary'''
 +
| This function returns an information string, created by the last call of {{Function||client:execute}}. {{Code|$id}} specifies the session id.
 
|}
 
|}
  
 
==client:query==
 
==client:query==
{|
+
 
|-
+
{| width='100%'
| width='90' | '''Signatures'''
+
|- valign="top"
|{{Func|client:query|$id as xs:anyURI, $query as xs:string|item()*}}<br/>{{Func|client:query|$id as xs:anyURI, $query as xs:string, $bindings as map(*)|item()*}}
+
| width='120' | '''Signatures'''
|-
+
|{{Func|client:query|$id as xs:anyURI, $query as xs:string|item()*}}<br/>{{Func|client:query|$id as xs:anyURI, $query as xs:string, $bindings as map(*)?|item()*}}
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Evaluates a query and returns the result as sequence. The parameter {{Code|$id}} contains the session id returned by [[Client Module#client:connect|client:connect()]], and {{Code|$query}} represents the query string, which will be evaluated by the server.<br />Variables and the context item can be declared via {{Code|$bindings}}. The specified keys must be QNames or strings, the values can be arbitrary items:
+
|Evaluates a query and returns the result as sequence. The parameter {{Code|$id}} contains the session id returned by {{Function||client:connect}}, and {{Code|$query}} represents the query string, which will be evaluated by the server.<br />Variables and the context item can be declared via {{Code|$bindings}}. The specified keys must be QNames or strings:
* variables specified as QNames will be directly interpreted as variable name.
+
* If a key is a QName, it will be directly adopted as variable name.
* variables specified as xs:string may be prefixed with a dollar sign. Namespace can be specified using the [http://www.jclark.com/xml/xmlns.htm Clark Notation]. If the specified string is empty, the value will be bound to the context item.
+
* If a key is a string, it may be prefixed with a dollar sign. A namespace can be specified using the [http://www.jclark.com/xml/xmlns.htm Clark Notation]. If the specified string is empty, the value will be bound to the context item.
|-
+
|- valign="top"
 
|'''Errors'''
 
|'''Errors'''
|{{Error|BXCL0003|#Errors}} an I/O error occurs while transferring data from or to the server.<br/>{{Error|BXCL0005|#Errors}} an error occurs while evaluating a query, and if the original error cannot be extracted from the returned error string.
+
|{{Error|error|#Errors}} an I/O error occurs while transferring data from or to the server.<br/>{{Error|query|#Errors}} an error occurs while evaluating a query, and if the original error cannot be extracted from the returned error string.<br/>{{Error|function|#Errors}} function items (including maps and arrays) cannot be returned.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
|The following query binds the integer {{Code|123}} to the variable {{Code|$n}} and returns {{Code|246}}:
+
|The following query sends a query on a local server instance, binds the integer {{Code|123}} to the variable {{Code|$n}} and returns {{Code|246}}:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
let $c := client:connect('basex.server.org', 8080, 'admin', 'admin')
+
let $c := client:connect('localhost', 1984, 'admin', '...')
return client:query($c, "$n * 2", map{ 'n' := 123 }))
+
return client:query($c, "declare variable $n external; $n * 2", map { 'n': 123 })
</pre>
+
</syntaxhighlight>
 
The following query performs a query on a first server, the results of which are passed on to a second server:
 
The following query performs a query on a first server, the results of which are passed on to a second server:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
let $c1 := client:connect('basex1.server.org', 8080, 'jack', 'C0S19tt2X')
 
let $c1 := client:connect('basex1.server.org', 8080, 'jack', 'C0S19tt2X')
 
let $c2 := client:connect('basex2.server.org', 8080, 'john', '465wFHe26')
 
let $c2 := client:connect('basex2.server.org', 8080, 'john', '465wFHe26')
return
+
for $it in client:query($c1, '1 to 10')
  for $c in client:query($c1, '1 to 10')
+
return client:query($c2, $it || '* 2')
  return client:query($c1, $c || '* 2')
+
</syntaxhighlight>
</pre>
 
 
|}
 
|}
  
 
==client:close==
 
==client:close==
{|
+
 
|-
+
{| width='100%'
| width='90' | '''Signatures'''
+
|- valign="top"
 +
| width='120' | '''Signatures'''
 
|{{Func|client:close|$id as xs:anyURI|empty-sequence()}}
 
|{{Func|client:close|$id as xs:anyURI|empty-sequence()}}
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
| This function closes a client session. {{Code|$id}} specifies the session id.<br/>At the end of query execution, open sessions will be automatically closed.
+
| This function closes a client session. {{Code|$id}} specifies the session id.<br/>Opened connections will automatically be closed after the XQuery expression has been evaluated, but it is recommendable to explicitly close them with this function if you open many connections.
|-
+
|- valign="top"
 
|'''Errors'''
 
|'''Errors'''
|{{Error|BXCL0003|#Errors}} an I/O error occurs while transferring data from or to the server.
+
|{{Error|error|#Errors}} an I/O error occurs while transferring data from or to the server.
 
|}
 
|}
  
Line 87: Line 112:
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
! width="5%"|Code
+
! width="110"|Code
! width="95%"|Description
+
|Description
|-
+
|- valign="top"
|{{Code|BXCL0001}}
+
|{{Code|command}}
 +
| An error occurred while executing a command.
 +
|- valign="top"
 +
|{{Code|connect}}
 
| An error occurred while creating a new session (possible reasons: server not available, access denied).
 
| An error occurred while creating a new session (possible reasons: server not available, access denied).
|-
+
|- valign="top"
|{{Code|BXCL0002}}
+
|{{Code|error}}
| The specified session is unknown, or has already been closed.
 
|-
 
|{{Code|BXCL0003}}
 
 
| An I/O error occurred while transferring data from or to the server.
 
| An I/O error occurred while transferring data from or to the server.
|-
+
|- valign="top"
|{{Code|BXCL0004}}
+
|{{Code|function}}
| An error occurred while executing a command.
+
| Function items (including maps and arrays) cannot be returned.
|-
+
|- valign="top"
|{{Code|BXCL0005}}
+
|{{Code|id}}
 +
| The id with the specified session is unknown, or has already been closed.
 +
|- valign="top"
 +
|{{Code|query}}
 
| An error occurred while evaluating a query. Will only be raised if the XQuery error cannot be extracted from the returned error string.
 
| An error occurred while evaluating a query. Will only be raised if the XQuery error cannot be extracted from the returned error string.
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 9.0
 +
 +
* Updated: error codes updated; errors now use the module namespace
 +
 +
;Version 8.0
 +
 +
* Updated: Bound values may now contain no or more than one item in {{Function||client:query}}.
 +
 +
;Version 7.5
 +
 +
* Added: {{Function||client:info}}
  
 
The module was introduced with Version 7.3.
 
The module was introduced with Version 7.3.
 
[[Category:XQuery]]
 

Revision as of 15:45, 10 August 2022

This XQuery Module contains functions to access BaseX server instances from XQuery. With this module, you can execute database commands and evaluate XQuery expressions.

Please note that the client module should always be used to address independent BaseX server instances. You can create deadlocks if you evaluate a query with a server instance, and if you are addressing the same server instance in your query. See the following example:

<syntaxhighlight lang="xquery"> (: Retrieve documents from database :) let $client-id := client:connect('localhost', 1984, 'admin', '...') let $docs := client:query($client-id, 'db:get("conflict")') (: Create database with same name :) return db:create('conflict', $docs, $docs ! db:path(.)) </syntaxhighlight>

The read-only query cannot be processed, because the conflict database is currently write-locked by the main query. See Transaction Management for more background information.

Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/client namespace, which is statically bound to the client prefix.

Functions

client:connect

Signatures client:connect($host as xs:string, $port as xs:integer, $username as xs:string, $password as xs:string) as xs:anyURI
Summary This function establishes a connection to a remote BaseX server, creates a new client session, and returns a session id. The parameter $host is the name of the database server, $port specifies the server port, and $username and $password represent the login data.
Errors connect: an error occurs while creating the session (possible reasons: server not available, access denied).

client:execute

Signatures client:execute($id as xs:anyURI, $command as xs:string) as xs:string
Summary This function executes a command and returns the result as a string. The parameter $id contains the session ID returned by client:connect. The $command argument represents a single command, which will be executed by the server.
Errors error: an I/O error occurs while transferring data from or to the server.
command: an error occurs while executing a command.
Examples The following query creates a new database TEST on a remote BaseX server:

<syntaxhighlight lang="xquery"> client:connect('basex.server.org', 8080, 'admin', '...') !

 client:execute(., 'create database TEST')

</syntaxhighlight>

client:info

Signatures client:info($id as xs:anyURI) as xs:string
Summary This function returns an information string, created by the last call of client:execute. $id specifies the session id.

client:query

Signatures client:query($id as xs:anyURI, $query as xs:string) as item()*
client:query($id as xs:anyURI, $query as xs:string, $bindings as map(*)?) as item()*
Summary Evaluates a query and returns the result as sequence. The parameter $id contains the session id returned by client:connect, and $query represents the query string, which will be evaluated by the server.
Variables and the context item can be declared via $bindings. The specified keys must be QNames or strings:
  • If a key is a QName, it will be directly adopted as variable name.
  • If a key is a string, it may be prefixed with a dollar sign. A namespace can be specified using the Clark Notation. If the specified string is empty, the value will be bound to the context item.
Errors error: an I/O error occurs while transferring data from or to the server.
query: an error occurs while evaluating a query, and if the original error cannot be extracted from the returned error string.
function: function items (including maps and arrays) cannot be returned.
Examples The following query sends a query on a local server instance, binds the integer 123 to the variable $n and returns 246:

<syntaxhighlight lang="xquery"> let $c := client:connect('localhost', 1984, 'admin', '...') return client:query($c, "declare variable $n external; $n * 2", map { 'n': 123 }) </syntaxhighlight> The following query performs a query on a first server, the results of which are passed on to a second server: <syntaxhighlight lang="xquery"> let $c1 := client:connect('basex1.server.org', 8080, 'jack', 'C0S19tt2X') let $c2 := client:connect('basex2.server.org', 8080, 'john', '465wFHe26') for $it in client:query($c1, '1 to 10') return client:query($c2, $it || '* 2') </syntaxhighlight>

client:close

Signatures client:close($id as xs:anyURI) as empty-sequence()
Summary This function closes a client session. $id specifies the session id.
Opened connections will automatically be closed after the XQuery expression has been evaluated, but it is recommendable to explicitly close them with this function if you open many connections.
Errors error: an I/O error occurs while transferring data from or to the server.

Errors

Code Description
command An error occurred while executing a command.
connect An error occurred while creating a new session (possible reasons: server not available, access denied).
error An I/O error occurred while transferring data from or to the server.
function Function items (including maps and arrays) cannot be returned.
id The id with the specified session is unknown, or has already been closed.
query An error occurred while evaluating a query. Will only be raised if the XQuery error cannot be extracted from the returned error string.

Changelog

Version 9.0
  • Updated: error codes updated; errors now use the module namespace
Version 8.0
  • Updated: Bound values may now contain no or more than one item in client:query.
Version 7.5

The module was introduced with Version 7.3.