_:basic-auth-decode

• 
  ( $encoded-auth as xs:string) as xs:string
  
  

Decodes the user name and password passed in Basic Auth.

• Parameters:
• $encoded-auth - Basic Auth header string Base64 encoded
  
• Return:
• user name:password

_:basic-auth-decode-test

• 
  %unit:test
  ( ) as item()*
  
  

_:db-name

• 
  ( $n as node()) as xs:string
  
  

Get the db name containing a particular node.
BaseX' db:name causes global read lock.

• Parameters:
• $n - A node
  
• Return:
• Name of the DB containing the node $n.

_:dehydrate

• 
  ( $nodes as node()* ,
    $data-extractor-xquery as (function(node()) as attribute()*)?) as element(_:dryed)*
  
  

Reduce a result of an XQuery to references of DB nodes.

• Parameters:
• $nodes - Nodes to turn into references to them
  
• $data-extractor-xquery - A function that extracts some attribute from the nodes
  and makes it available in the reference data directly e. g. for sorting
  
• Return:
• References to the nodes. The result is not sorted, most probably document order applies
• See:
• _:hydrate

_:eval

• 
  ( $query as xs:string ,
    $bindings as (map(*))? ,
    $jobName as xs:string) as item()*
  
  

Executes a reading query as separate job so without any locks in the calling XQuery.
Shortcut for eval with $dontCheckQuery = false().

• Parameters:
• $query - Query to execute.
  
• $bindings - Map with bindings for external variables contained in the query
  
• $jobName - A discriptive name for the query so it can be identified
  
• Return:
• Result of the query.
  Reraises any exceptions that the query may have raised.

_:eval

• 
  ( $query as xs:string ,
    $bindings as (map(*))? ,
    $jobName as xs:string ,
    $dontCheckQuery as xs:boolean) as item()*
  
  

Executes any query as separate job so without any locks in the calling XQuery.
For potentially dangerous queries $dontCheckQuery has to be true()
Details are implemented in start-eval-job.

• Parameters:
• $query - Query to execute.
  
• $bindings - Map with bindings for external variables contained in the query.
  
• $jobName - A discriptive name for the query so it can be identified.
  
• $dontCheckQuery - Allow updating and more destructive XQueries.
  
• Return:
• Result of the query.
  Reraises any exceptions that the query may have raised.
• See:
• _:start-eval-job

_:eval-test

• 
  %unit:test
  ( ) as item()*
  
  

_:evals

• 
  ( $queries as xs:string+ ,
    $bindings as (map(*))? ,
    $jobName as xs:string ,
    $dontCheckQuery as xs:boolean) as item()*
  
  

Executes queries as separate jobs without locks in the calling XQuery.
Uses jobs:eval() with caching to execute batches of $queries truely independently of the
calling XQuery including locks and indexes if the optimizer recognizes the databases in the
probably much shorter (sub)query.
Tries to create meaningful names and base-uris for each query in $queries.
Uses a small random delay to not start all queries at once.
Logs if execution needs more than 100ms.
The main use of this function is to query a set of similar databases with pre created
XQueries that contain any database name as string literal.
This is easy to achieve with the XQuery 3.1 String constructors.

• Parameters:
• $queries - Queries to execute.
  
• $bindings - Map with bindings for external variables contained in the query.
  
• $jobName - A descriptive name of the job $query does
  
• $dontCheckQuery - Allow updating and more destructive XQueries.
  
• Return:
• The job ID which jobs:* function take as an argument.
  Raises an _err:too-many-parallel-requests if there are currently more jobs running
  then the maximum of parallel jobs configured for BaseX.
  Will reraise any error while executing $queries.
• See:
• _:start-eval-job
• _:get-results-or-errors
• _:throw-on-error-in-returns

_:evals

• 
  ( $query as xs:string ,
    $bindings as (map(*))? ,
    $sequenceKey as xs:string ,
    $batch-size as xs:integer ,
    $jobName as xs:string ,
    $dontCheckQuery as xs:boolean) as item()*
  
  

Executes one query and binds a sequence of $batch-size items in sequence $sequencKey of $bindings per job.
For example with seqenceKey := 'aKey':
map { 'aKey': (<a/>,<b/>)}
If $batch-size is one two jobs are executed with <a/> and <b/> bound respectively,
if $batch-size is two one job is executed with (<a/>,<b/>) bound
and so on.

• Parameters:
• $query - A query with at least one external variable $sequenceKey
  
• $bindings - Map with bindings for external variables contained in the query.
  
• $sequenceKey - The name of the key in bindings which should be split $batch-size per job.
  
• $bach-size - The maximum number of jobs this query should create simultaneously.
  
• $jobName - A descriptive name of the job $query does
  
• $dontCheckQuery - Allow updating and more destructive XQueries.
  
• Return:
• The job ID which jobs:* function take as an argument.
  Will reraise any error while executing $queries.

_:get-base-uri-public

• 
  ( ) as xs:string
  
  

Use the X-Forwarded-Request-Uri custom request header to get the correct base URI as seen by the reverse proxy

• Return:
• Either the base URI as seen by the reverse proxy or request:path() reported by jetty.

_:get-base-uri-public-test

• 
  %unit:test
  %unit:ignore("needs HTTP connection")
  ( ) as item()*
  
  

_:get-batch-size

• 
  ( ) as xs:integer
  
  

Set the batch size to 1/3 of all possible parallel jobs

• Return:
• Number of jobs in on batch.

_:get-public-scheme-and-hostname

• 
  ( ) as xs:string
  
  

Try to get the correct scheme and hostname as seen by the reverse proxy

• Return:
• scheme://hostname:port/

_:get-public-scheme-and-hostname-test

• 
  %unit:test
  %unit:ignore("needs HTTP connection")
  ( ) as item()*
  
  

_:get-results-or-errors

• 
  ( $js as xs:string*) as item()*
  
  

Get results or errors for a sequence of job IDs.
Gets all results of a sequence of jobs.
If there were errors raised they are encoded and also returned.

• Parameters:
• $js - Job IDs.
  
• Return:
• The results of the jobs or encoded errors if there were any.
• See:
• _:throw-on-error-in-returns

_:get-xml-file-or-default

• 
  ( $fn as xs:string ,
    $default as xs:string) as document-node()
  
  

Return doc($fn) or if it cannot be resolves doc($default) without any locks in the calling query.

• Parameters:
• $fn - A filename doc() and doc-available() can usually resolve.
  
• $default - A filename doc() can always open.
  
• Return:
• The contents of the opened document as in memory copy.

_:get-xml-file-or-default

• 
  ( $fn as xs:string ,
    $default as xs:string ,
    $fn-is-valid as xs:boolean) as document-node()
  
  

Return doc($fn) or if it cannot be resolves doc($default) without any locks in the calling query.
If there is a way to know when $fn is definitly not there this can be passed in $fn-is-valid.

• Parameters:
• $fn - A filename doc() and doc-available() can usually resolve.
  
• $default - A filename doc() can always open.
  
• $fn-is-valid - Whether $fn is tried at all
  
• Return:
• The contents of the opened document as in memory copy.

_:hydrate

• 
  ( $dryed as element(_:d)+) as node()*
  
  

Fetch the real XML data from databases according to $dryed references.

• Parameters:
• $dryed - References to data in some BaseX database
  
• Return:
• The actual XML data from the databases.
• See:
• _:dehydrate

_:hydrate

• 
  ( $dryed as element(_:d)+ ,
    $filter_code as xs:string) as node()*
  
  

Fetch the real XML data from databases according to $dryed references.

• Parameters:
• $dryed - References to data in some BaseX database
  
• $filter_code - A XQuery function
  declare function filter($nodes as node()*) as node()* {()};
  used to filter the data fetched from BaseX databases usung the references in $dryed
  
• Return:
• The actual XML data from the databases.
• See:
• _:dehydrate

_:query-is-sane

• 
  %private
  ( $query as xs:string) as xs:boolean
  
  

Implementation detail: Check whether this XQuery uses updating or other functions that can be destructive.

• Blocks updating queries
• Blocks queries that use xquery:eval()
• Blocks queries that use http:send-request()

• Parameters:
• $query - The query to check.
  
• Return:
• True if the function does not use anything unwanted.
  If there is unwanted code in the XQuery this raises an _err:dubious-query.

_:start-eval-job

• 
  %private
  ( $query as xs:string ,
    $bindings as (map(*))? ,
    $jobName as xs:string ,
    $dontCheckQuery as xs:boolean ,
    $subJobNumber as xs:integer) as xs:string
  
  

Implementation detail: Executes a query as separate job.
Uses jobs:eval() with caching to execute $query truely independently of the calling XQuery
including locks and indexes if the optimizer recognizes the databases in the
probably much shorter (sub)query.
Tries to create meaningful names and base-uris for $query.

• Parameters:
• $query - Query to execute.
  
• $bindings - Map with bindings for external variables contained in the query.
  
• $jobName - A descriptive name of the job $query does
  
• $dontCheckQuery - Allow updating and more destructive XQueries.
  
• $subJobNumber - An integer used to differentiate very similar jobs.
  
• Return:
• The job ID which jobs:* function take as an argument.
  Raises an _err:too-many-parallel-requests if there are currently more jobs running
  then the maximum of parallel jobs configured for BaseX.
  Will reraise any error while executing $query.

_:throw-on-error-in-returns

• 
  ( $ret as item()*) as item()*
  
  

Raises an error if there were any reported in the encoded results passed to this function.
Gets all results of a sequence of jobs.
If there were errors raised they are encoded and also returned.

• Parameters:
• $ret - Some returned results from multiple jobs.
  
• Return:
• The results of the jobs.
  Raises errors encoded in $ret.
• See:
• _:get-results-or-errors

_:zzz-unit-test-after

• 
  %unit:after
  %updating
  ( ) as item()*
  
  

_:zzz-unit-test-before

• 
  %unit:before
  %updating
  ( ) as item()*