administrator, editor
31
edits
Changes
Jump to navigation
Jump to search
m
{{Mark|Updated with Version 9.6:}}
* Java objects are now wrapped into function items.
* New option {{Option|WRAPJAVA}}.
* Mapping rules were refined. The most important changes:
** {{Code|array(*)}} type added.
** {{Code|xs:integer}} values are converted to {{Code|long}} values.
** {{Code|xs:unsignedShort}} values are converted to {{Code|char}} values.
is->if
Please bear in mind that the execution of Java code may cause side effects that conflict with the functional nature of XQuery, or may introduce new security risks to your project.
Some more notes:
* With the middle dot notation, three adjacent dots can be used to specify array types.
* The path to the standard package {{Code|java.lang.}} can be omitted.
* Java objects are wrapped into function items.
* Results of constructor calls are always returned as function item.
* With {{Option|WRAPJAVA}}, it can be controlled how Java values are converted to XQuery.
=Identification=
# The last path segment of the URI is capitalized and rewritten to [https://en.wikipedia.org/wiki/CamelCase CamelCase].
The normalization steps are skipped if the URI is prefixed with {{Code|java:}}. The path to the standard package {{Code|java.lang.}} can be omitted:
* <code><nowiki>http://basex.org/modules/meta-data</nowiki></code> → <code>org.basex.modules.MetaData</code>
* <code>java:java.lang.String</code> → <code>java.lang.String</code>
* <code>StringBuilder</code> → <code>java.lang.StringBuilder</code>
==Functions and Variables==
Java constructors, functions and variables can be referenced and evaluated by the existing XQuery function syntax:
* The namespace of the function name identifies the Java class.
* The local part of the name, which is rewritten to camel case, identifies a variable or function of that class.
* The middle dot character <code>[https://www.fileformat.info/info/unicode/char/b7/index.htm ·]</code> (<code>&#xB7;</code>, a valid character in XQuery names, but not in Java) can be used to append exact Java parameter types to the function name. Class types must be referenced by their full path. Since {{Version|9.6}}, three Three adjacent dots can be used to address an array argument.
{| class="wikitable"
|- valign="top"
| Variable
| <code>Q{java.lang.Integer}MIN_VALUE()</code>
| <code>Integer.MIN_VALUE</code>
|- valign="top"
| Function
| <code>Q{java.lang.Object}hash-code($object)</code>
| <code>object.hashCode()</code>
|- valign="top"
| Function with argument
| <code>Q{java.lang.String}split·java.lang.String·intsplit·String·int($string, ';', xs:int(3))</code>
| <code>string.split(";", 3)</code>
|- valign="top"
| Function Constructor with array argument| <code>Q{java.lang.String}new·byte...(xs:hexBinary('414243'))</code>
| <code>new String(new byte[] { 41, 42, 43 })</code>
|}
=Namespace Declarations=
In the following example, Java’s the Java {{Code|Math}} class is referenced. When executed, the query returns the cosine of an angle by calling the static method {{Code|cos()}}, and the value of π by addressing the static variable via {{Code|PI()}}:
<syntaxhighlight lang="xquery">
</syntaxhighlight>
With the [[XQuery 3.0#Expanded QNames|Expanded QName]] notation of XQuery 3.0,the namespace can directly be embedded in the function call:
<syntaxhighlight lang="xquery">
<syntaxhighlight lang="xquery">
declare namespace fw = "'java:java.io.FileWriter"';
let $file := fw:new('output.txt')
return (
<syntaxhighlight lang="xquery">
declare namespace br = 'java:java.io.BufferedReader';declare namespace fr = 'java:java.io.FileReader';
declare option db:checkstrings 'false';
=Module Imports=
A Java classes class can also be instantiated by ''importing'' them as a module: A new instance of the addressed class will be constructed, which can then be referenced in the query body.
In the (side-effecting) example below, a HashSet instance is created, values are added, and the size of the set is returned. As {{Code|set:add()}} returns boolean values, {{Function|Profiling|prof:void}} is used to swallow the values:
==Data Types==
===Conversion to Java===
Before Java code is executed, the arguments are converted to Java values, depending on the addressed function or constructor parameters. The accepted Java types and the original XQuery types are depicted in the second and first column of the table below.
If a numeric value is supplied for which no exact matching is defined, it is cast to the appropriate type unless it exceeds its limits. The following two function calls are equivalent:
<syntaxhighlight lang="xquery">
(: exact match :)
Q{String}codePointAt('ABC', xs:int(1)),
(: xs:byte and xs:integer casts :)
Q{String}codePointAt('ABC', xs:byte(1)),
Q{String}codePointAt('ABC', 1)
</syntaxhighlight>
===Conversion to XQuery===
By default, Java values with the most common types (as shown in the second and third column of the table) are converted to XQuery values. All other values are returned as ''Java items'', which are function items with a wrapped Java value. The results of constructor calls will are always be returned as Java items.
The conversion of the wrapped Java value to XQuery is enforced by invoking the function item: Values in {{Code|Iterator}} and {{Code|Iterable}} instances (Lists, Sets and Collections) are converted to items, and maps are converted to XQuery maps:
</syntaxhighlight>
If no conversion is defined, the value a string is returned, which is returned by resulting from the object’s {{Code|toString()}} methodof the object. This function method is also called if the string repesentation representation of a Java item is requested:
<syntaxhighlight lang="xquery">
|- valign="top"
| {{Code|none}}
| The All Java values are converted. If no conversion is enforceddefined, a string is returned, and no Java values will be wrappedresulting from the {{Code|toString()}} method.
|- valign="top"
| {{Code|all}}
|- valign="top"
| {{Code|instance}}
| If the Java code was called with method of a class instancewas called, this the Java value is ignored and the instance is wrapped into a Java item. Otherwise, the Java value is returned.
|- valign="top"
| {{Code|void}}
(# db:wrapjava all #) {
Q{java.lang.Character}toChars(xs:int(33))
=> Q{java.nio.CharBuffer}wrap()
}
<syntaxhighlight lang="xquery">
(: Without Thanks to the pragma, set:add would return a boolean, indicating if a new entry was added the function calls can be chained :)
declare namespace set = 'java:java.util.HashSet';
; Version 9.6
* Updated: Java Bindings revised (new mappings, Java functiom items, {{AnchorOption|Data TypesWRAPJAVA}}: {{Code|array(*option)}} type added; {{Code|xs:integer}} are converted to {{Code|long}} values.
; Version 9.4
