Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
By default, access to external resources (files on hard disk, HTTP requests, ...) A global lock will be assigned if the name of the database is not controlled by the transaction monitor of BaseX. You can use custom XQuery locks to do soa static string:
===Option Declarations, Pragmas* {{Code|for $db in ('db1', Function Annotations=='db2') return db:open($db)}}* {{Code|doc(doc('test')/reference/text())}}* <code>let $db :='test' return insert nodes <test/> into db:open($db)</code>
* You can declare custom locks via options, pragmas or function annotations.* The value consult the query info output (which you find in the [[GUI#Visualizations|Info View]] of the lock may contain one GUI or multiple lock keys (separated with commaswhich you can turn on by setting {{Option|QUERYINFO}} to {{Code|true}}).* Similar to the internal database locks, write locks block all other operations while read locks allow parallel access.* The internal locks and XQuery locks can co-exist (there will be no conflicts, even if your lock string equals the name of a database that will be find out which databases have been locked by the transaction manager)a query.
Local locks can also be declared via pragmas:==Pragmas==
Locks for The write locks is enforced via the functions of a module can be assigned via option declarations{{Code|Update|update:output}}.
<pre class="brush:xquery">declare option basex:write-lock 'HTTPLOCK';file:write('config.xml', <config/>)</pre>=Options==
Before {{Version|9.1}}, locks were declared in Locks for the {{Code|query}} namespace.functions of a module can also be assigned via option declarations:
Locks can also be acquired on [[Java Bindings#Locking|Java functions]] which are imported and invoked from an XQuery expression. It is advisable to explicitly lock Java code whenever it performs sensitive read and update:output(file:write operations('config.xml', <config/>))</syntaxhighlight>
==Limitations==Once again, a write lock is enforced.
Database locking works with all commands unless the glob syntax is used, such as in the following command call: * {{Code|DROP DB new*}}: drop all databases starting with "new" ===XQuery=== Deciding which databases will Locks can also be accessed by a complex XQuery expression is a non-trivial task. Database detection works for the following types of queries: * {{Code|//item}}, read-locking of the database opened by a client* {{Code|doc('factbook')}}, read-locking of "factbook"* {{Code|collection('db/path/to/docs')}}, read-locking of "db"* {{Code|fn:sum(1 to 100)}}, locking nothing at all* {{Code|delete nodes doc('test')//*acquired on [string-length(local-name(.)) > 5]}}, write-locking of "test" All databases will be locked by queries of the following kind: * {{Code|for $db in ('db1', 'db2') return doc($db)}}* {{Code|doc(doc('test')/reference/text())}}* <code>let $db := 'test' return insert nodes <test/> into doc($db)</code> You can consult the query info output (which you find in the [[GUIJava Bindings#VisualizationsLocking|Info ViewJava functions]] of the GUI or which you can turn on by setting <are imported and invoked from an XQuery expression. It is advisable to explicitly lock Java code>[[Options#QUERYINFO|QUERYINFO]]</code> to {{Code|true}}) to find out which databases have been locked by a querywhenever it performs sensitive read and write operations.
→XQuery Locks
* By default, read transactions are favored, and transactions that access no databases can be evaluated even if the transactions limit has been reached. This behavior can be changed via the {{Option|FAIRLOCK}} option.
==Limitations== ===Commands=== Database locking works with all commands unless the glob syntax is used, such as in the following command call: * {{Code|DROP DB new*}}: drop all databases starting with "new" ===XQuery Locks=== Deciding which databases will be accessed by a complex XQuery expression is a non-trivial task. Database detection works for the following types of queries: * {{Code|//item}}, read-locking of the database opened by a client* {{Code|doc('factbook')}}, read-locking of "factbook"* {{Code|collection('db/path/to/docs')}}, read-locking of "db"* {{Code|fn:sum(1 to 100)}}, locking nothing at all* {{Code|delete nodes db:open('test')//*[string-length(local-name(.)) > 5]}}, write-locking of "test"
The functions [[Databases#XML Documents|fn:doc]] and [[Databases#XML Documents|fn:collection]] can also be used to address that are not stored in a database. However, this may lead to unwanted locks, and you have two options to reduce the number of locks: No database lookups will take place if {{MarkOption|Introduced with Version 9.1WITHDB}} option is disabled, or if {{Function|Fetch|fetch:xml}}is used instead of [[Databases#XML Documents|fn: locks via pragmas and function annotationsdoc]].
=XQuery Locks= {{CodeMark|basexUpdated with Version 9.4:read-lock}} Single lock option for reads and {{Code|basexwrites. By default, access to external resources (files on hard disk, HTTP requests, ...) is not controlled by the transaction monitor of BaseX. Custom locks can be assigned via annotations, pragmas or options: * A lock string may consist of a single key or multiple keys separated with commas.* Internal locks and XQuery locks can co-exist. No conflicts arise, even if a lock string equals the name of a database that is locked by the transaction manager.* The lock is transformed into a write-lock}} options in by making the query prolog corresponding expression updating. ==Annotations==
In the following module, lock annotations are used to prevent concurrent write operations on the same file:
<pre classsyntaxhighlight lang="brush:xquery">
module namespace config = 'config';
declare %basex:read-lock('CONFIG') function config:read() as xs:string {
file:read-text('config.txt')
};
declare %updating %basex:write-lock('CONFIG') function config:write($dataas xs:string) {
file:write-text('config.txt', $data)
};
</presyntaxhighlight>
Some explanations:
* If a query calls the <code>config:read</code> function, a read lock will be acquired for the user-defined {{Code|CONFIG}} lock string before query evaluation.
* If <code>config:write</code> is called by a query, a write lock on this lock string will be set for this queryapplied.* If a another query calls <code>config:write</code>, it will be queued until there is no running query left that has {{Code|CONFIG}} locked.* If the writing first query will be is evaluated, all other queries that will set a {{Code|CONFIG}} lock (reading or writing) will have to wait.
Locks can also be declared via pragmas: <pre classsyntaxhighlight lang="brush:xquery">update:output((# basex:write-lock CONFIGLOCK CONFIG #) {
file:write('config.xml', <config/>)
})</presyntaxhighlight>
<syntaxhighlight lang===Java Modules==="xquery">declare option basex:lock 'CONFIG';
===Commands=Java Modules==
=File-System Locks=
=Changelog=
;Version 9.4
* Updated: Single lock option for reads and writes.
;Version 9.1
