Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
The [https://github.com/BaseXdb/basex/blob/master/basex-core/src/main/java/org/basex/query/QueryResource.java QueryResource] interface can be implemented to enforce finalizing operations, such as the closing of opened connections or resources in a module. Its {{Code|close()}} method will be called after a query has been fully evaluated.
→URI Rewriting
A Java class is identified by a namespace URI. The original URI is rewritten as follows:
# The [[Repository#URI_RewritingURI Rewriting|URI Rewriting]] steps are applied to the URI.
# Slashes in the resulting URI are replaced with dots.
# The last path segment of the URI is capitalized and rewritten to [https://en.wikipedia.org/wiki/CamelCase camel caseCamelCase].
The normalization steps are skipped if the URI is prefixed with {{Code|java:}}. See the following examples:
=Module Imports=
An alternative solution is to access Java code can also be integrated by ''importing'' classes as modules. A new instance of the addressed class is will be created, which can then be accessed referenced in the query body.
The following, (side-effecting ) example returns the number of distinct values added to a hash set (the . The boolean values returned by {{Code|set:add()}} will be swallowed):
<pre class="brush:xquery">
import module namespace set = "java:java.util.HashSet";
prof:void(
for $s in ("one", "two", "one")
</pre>
The advantages of this approach is that the execution of imported code classes is executed faster more efficient than the execution of instances that are created at runtime via {{Code|new()}}. A drawback is that no arguments can be passed on to the class constructor. As a consequence, the import will fail fails if the addressed class has no default constructor, but at least one constructor with arguments and no default constructor.
=Context-AwarenessIntegration=
Java classes can be coupled even more closely to the BaseX core library.If a class inherits the abstract [https://github.com/BaseXdb/basex/blob/master/basex-core/src/main/java/org/basex/query/QueryModule.java QueryModule] class, the two variables [https://github.com/BaseXdb/basex/blob/master/basex-core/src/main/java/org/basex/query/QueryContext.java queryContext] and [https://github.com/BaseXdb/basex/blob/master/basex-core/src/main/java/org/basex/query/StaticContext.java staticContext] get available, which provide access to the global and static context of a query. Additionally The [https://github.com/BaseXdb/basex/blob/master/basex-core/src/main/java/org/basex/query/QueryResource.java QueryResource] interface can be implemented to enforce finalizing operations, such as the default closing of opened connections or resources in a module. Its {{Code|close()}} method will be called after a query has been fully evaluated. ==Annotations== The internal properties of functions can be changed assigned via annotations:
* Java functions can only be executed by users with [[User_Management|Admin permissions]]. You may annotate a function with {{Code|@Requires(<Permission>)}} to also make it accessible to users with less privileges.
* Java code is treated as ''context-independent''. If a function accesses the query context, it should be annotated as {{Code|@ContextDependent}}
* Java code is treated as ''focus-independent''. If a function accesses the current context item, position or size, it should be annotated as {{Code|@FocusDependent}}
The following XQuery code invokes two Java methods. The first Java function retrieves information from the static query context, and the second one throws a query exception:
[http://www.w3.org/TR/xpath-functions-30/#properties-of-functions function properties].
==Locking==
By default, a Java function will be executed in parallel with other code. However, if a Java function performs sensitive write operations, it is advisable to explicitly lock the code. This can be realized via locking annotations:
If an XQuery expression is run which calls the Java {{Code|write()}} function, every other query that calls {{Code|write()}} or {{Code|read()}} needs to wait for the query to be finished. If a query calls the {{Code|read()}} function, only those queries are queued that call {{Code|write()}}, because this function is only annotated with a {{Code|read}} lock. More details on parallel query execution can be found in the article on [[Transaction Management]].
==Data Types==
The following table lists the mappings of XQuery and Java types:
| <code>null</code>
|}
==URI Rewriting==
Before a Java class or module is accessed, its namespace URI will be normalized:
# If the URI is a URL:
## colons will be replaced with slashes,
## in the URI authority, the order of all substrings separated by dots is reversed, and
## dots in the authority and the path are replaced by slashes. If no path exists, a single slash is appended.
# Otherwise, if the URI is a URN, colons will be replaced with slashes.
# Characters other than letters, dots and slashes will be replaced with dashes.
# If the resulting string ends with a slash, the {{Code|index}} string is appended.
If the resulting path has no file suffix, it may point to either an XQuery module or a Java archive.
The following examples show some rewritings:
* {{Code|<nowiki>http://basex.org/modules/hello/World</nowiki>}} → {{Code|org/basex/modules/hello/World}}
* {{Code|<nowiki>http://www.example.com</nowiki>}} → {{Code|com/example/www/index}}
* {{Code|a/little/example}} → {{Code|a/little/example}}
* {{Code|a:b:c}} → {{Code|a/b/c}}
=Changelog=
* Updated: Rewriting rules
;Version 8.2
* Added: [[#URI Rewriting|URI Rewriting]]: support for URNs
; Version 8.0
* Added: import of Java modules, context awareness
* Added: [[#Packaging|Packaging]], [[#URI Rewriting|URI Rewriting]]
