Java Bindings - Revision history

CG: /* Functions and Variables */

2024-01-22T12:23:27Z

Functions and Variables

CG: Text replacement - "syntaxhighlight" to "pre"

2023-12-01T16:38:40Z

Text replacement - "syntaxhighlight" to "pre"

CG: Text replacement - "" to "

2023-12-01T16:34:32Z

Text replacement - "<syntaxhighlight lang="xquery">" to "<pre lang='xquery'>"

CG: Text replacement - "" to ""

2023-12-01T16:33:19Z

Text replacement - "</syntaxhighlight>" to "</pre>"

CG at 12:54, 31 October 2023

2023-10-31T12:54:18Z

CG: /* URI Rewriting */

2023-10-19T08:48:50Z

URI Rewriting

Andy Bunce: is->if

2022-07-27T09:25:53Z

is->if

CG: /* Module Imports */

2022-07-11T09:51:02Z

Module Imports

CG at 10:34, 17 June 2022

2022-06-17T10:34:59Z

CG: /* Conversion to Java */

2021-08-18T09:25:49Z

Conversion to Java

@@ Line 35: / Line 35: @@
 * 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>&amp;#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. Three adjacent dots can be used to address an array argument.
+* The middle dot character <code>[https://www.fileformat.info/info/unicode/char/b7/index.htm ·]</code> (<code>&amp;#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. Three adjacent dots can be used to address an array argument.
 {| class="wikitable"

@@ Line 166: / Line 166: @@
 The imported Java class is shown below:
-<syntaxhighlight lang="java">
+<pre lang="java">
 package org.basex.examples.query;
@@ Line 214: / Line 214: @@
 The result will look as follows:
-<syntaxhighlight lang="xml">
+<pre lang="xml">
 <user>admin</admin>
 <error>Integer conversion failed: abc</error>
@@ Line 226: / Line 226: @@
 The {{Code|@Updating}} annotation can be applied to mark Java functions that perform write or update operations:
-<syntaxhighlight lang="java">
+<pre lang="java">
    @Updating
    public void backup() {
@@ Line 249: / Line 249: @@
 If you want to synchronize the execution of your code with BaseX locks, you can take advantage of the {{Code|@Lock}} annotation:
-<syntaxhighlight lang="java">
+<pre lang="java">
    @Lock("HEAVYIO")
    public void read() {

@@ Line 68: / Line 68: @@
 In the following example, 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">
+<pre lang='xquery'>
 declare namespace math = "java:java.lang.Math";
 math:cos(xs:double(0)), math:PI()
@@ Line 75: / Line 75: @@
 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">
+<pre lang='xquery'>
 Q{java:java.lang.Math}cos(xs:double(0))
 </pre>
@@ Line 81: / Line 81: @@
 The constructor of a class can be invoked by calling the virtual function {{Code|new()}}. Instance methods can then called by passing on the resulting Java object as first argument. In the following example, 256 bytes are written to the file {{Code|output.txt}}. First, a new {{Code|FileWriter}} instance is created, and its {{Code|write()}} function is called in the next step:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 declare namespace fw = 'java:java.io.FileWriter';
 let $file := fw:new('output.txt')
@@ Line 93: / Line 93: @@
 If the result of a Java call contains invalid XML characters, it will be rejected. The validity check can be disabled by setting {{Option|CHECKSTRINGS}} to false. In the example below, a file with a single {{Code|00}} byte is written, and this file will then be accessed by via Java functions:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 declare namespace br = 'java:java.io.BufferedReader';
 declare namespace fr = 'java:java.io.FileReader';
@@ Line 111: / Line 111: @@
 The option can also be specified via a pragma:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 (# db:checkstrings #) {
    br:new(fr:new('00.bin')) ! (br:readLine(.), br:close(.))
@@ Line 123: / Line 123: @@
 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:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 import module namespace set = "java:java.util.HashSet";
 prof:void(
@@ Line 151: / Line 151: @@
 In the following code, information from the static query context is returned by the first function, and a query exception is raised by the second function:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 import module namespace context = 'org.basex.examples.query.ContextModule';
@@ Line 274: / Line 274: @@
 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">
+<pre lang='xquery'>
 (: exact match :)
 Q{String}codePointAt('ABC', xs:int(1)),
@@ Line 288: / Line 288: @@
 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 lang="xquery">
+<pre lang='xquery'>
 declare namespace Scanner = 'java:java.util.Scanner';
 let $scanner := Scanner:new("A B C") => Scanner:useDelimiter(" ")
@@ Line 296: / Line 296: @@
 If no conversion is defined, a string is returned, resulting from the {{Code|toString()}} method of the object. This method is also called if the string representation of a Java item is requested:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 (: returns the string representations of a HashMap and an ArrayList instance :)
 'Map: ' || Q{java.util.HashMap}new(),
@@ Line 327: / Line 327: @@
 In the following example, the result of the first function – a char array – is wrapped and passed on to a {{Code|CharBuffer}} function. Without the option, the single-value array would be converted to an {{Code|xs:unsignedShort}} item and the second function call would fail:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 (: Without the pragma, the result of toChars would be converted to an xs:unsignedShort item, and the second function call would fail :)
@@ Line 338: / Line 338: @@
 The next example demonstrates a use case for the {{Code|instance}} option:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 (: Thanks to the pragma, the function calls can be chained :)
@@ Line 352: / Line 352: @@
 The {{Code|void}} option is helpful if side-effecting methods return values that do not contribute to the final result:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 (: Without the pragma, 100 booleans would be returned by the FLWOR expression :)

@@ Line 71: / Line 71: @@
 declare namespace math = "java:java.lang.Math";
 math:cos(xs:double(0)), math:PI()
-</syntaxhighlight>
+</pre>
 With the [[XQuery 3.0#Expanded QNames|Expanded QName]] notation of XQuery 3.0, the namespace can directly be embedded in the function call:
@@ Line 77: / Line 77: @@
 <syntaxhighlight lang="xquery">
 Q{java:java.lang.Math}cos(xs:double(0))
-</syntaxhighlight>
+</pre>
 The constructor of a class can be invoked by calling the virtual function {{Code|new()}}. Instance methods can then called by passing on the resulting Java object as first argument. In the following example, 256 bytes are written to the file {{Code|output.txt}}. First, a new {{Code|FileWriter}} instance is created, and its {{Code|write()}} function is called in the next step:
@@ Line 89: / Line 89: @@
    fw:close($file)
+)
-</syntaxhighlight>
+</pre>
 If the result of a Java call contains invalid XML characters, it will be rejected. The validity check can be disabled by setting {{Option|CHECKSTRINGS}} to false. In the example below, a file with a single {{Code|00}} byte is written, and this file will then be accessed by via Java functions:
@@ Line 107: / Line 107: @@
    br:close($br)
+)
-</syntaxhighlight>
+</pre>
 The option can also be specified via a pragma:
@@ Line 115: / Line 115: @@
    br:new(fr:new('00.bin')) ! (br:readLine(.), br:close(.))
+}
-</syntaxhighlight>
+</pre>
 =Module Imports=
@@ Line 130: / Line 130: @@
 ),
 set:size()
-</syntaxhighlight>
+</pre>
 The execution of imported classes is more efficient than the execution of instances that have been created via {{Code|new()}}. In turn, no arguments can be supplied in the import statement, and the construction will only be successful if the class can be instantiated without arguments.
@@ Line 162: / Line 162: @@
    element error { $err:description }
+}
-</syntaxhighlight>
+</pre>
 The imported Java class is shown below:
@@ Line 210: / Line 210: @@
+   }
+}
-</syntaxhighlight>
+</pre>
 The result will look as follows:
@@ Line 217: / Line 217: @@
 <user>admin</admin>
 <error>Integer conversion failed: abc</error>
-</syntaxhighlight>
+</pre>
 Please visit the XQuery 3.0 specification if you want to get more insight into
@@ Line 231: / Line 231: @@
      // ...
+   }
-</syntaxhighlight>
+</pre>
 An XQuery expression will be handled as an [[XQuery Update#Updating Expressions|updating expression]] if it calls an updating Java function. In contrast to XQuery update operations, the Java code will immediately be executed, but the result will be cached as if {{Function|Update|update:output}} was called.
@@ Line 260: / Line 260: @@
      // ...
+   }
-</syntaxhighlight>
+</pre>
 If an XQuery expression invokes {{Code|write()}}, any other query that calls {{Code|write()}} or {{Code|read()}} needs to wait for the query to be finished. The {{Code|read()}} function can be run in parallel; whereas queries will be queued if {{Code|write()}} is called.
@@ Line 280: / Line 280: @@
 Q{String}codePointAt('ABC', xs:byte(1)),
 Q{String}codePointAt('ABC', 1)
-</syntaxhighlight>
+</pre>
 ===Conversion to XQuery===
@@ Line 292: / Line 292: @@
 let $scanner := Scanner:new("A B C") => Scanner:useDelimiter(" ")
 return $scanner()
-</syntaxhighlight>
+</pre>
 If no conversion is defined, a string is returned, resulting from the {{Code|toString()}} method of the object. This method is also called if the string representation of a Java item is requested:
@@ Line 300: / Line 300: @@
 'Map: ' || Q{java.util.HashMap}new(),
 string(Q{java:java.util.ArrayList}new())
-</syntaxhighlight>
+</pre>
 The conversion can be further controlled with the {{Option|WRAPJAVA}} option. The following values exist:
@@ Line 334: / Line 334: @@
    => Q{java.nio.CharBuffer}wrap()
+}
-</syntaxhighlight>
+</pre>
 The next example demonstrates a use case for the {{Code|instance}} option:
@@ Line 348: / Line 348: @@
+}
 return $set()
-</syntaxhighlight>
+</pre>
 The {{Code|void}} option is helpful if side-effecting methods return values that do not contribute to the final result:
@@ Line 364: / Line 364: @@
    $set()
+)
-</syntaxhighlight>
+</pre>
 The irrelevant results could also be swallowed with {{Function|Profiling|prof:void}}.

@@ Line 145: / Line 145: @@
 * Java functions can only be executed by users with [[User_Management|Admin permissions]]. You can annotate a function with {{Code|@Requires(<Permission>)}} to also make it accessible to users with fewer privileges.
-* Java code is treated as ''non-deterministic'', as its behavior cannot be predicted by the XQuery processor. You may annotate a function as {{Code|@Deterministic}} if you know that it will have no side effects and will always yield the same result.
+* Java code is treated as ''nondeterministic'', as its behavior cannot be predicted by the XQuery processor. You may annotate a function as {{Code|@Deterministic}} if you know that it will have no side effects and will always yield the same result.
 * 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}}

@@ Line 505: / Line 505: @@
 * {{Code|a/little/example}} → {{Code|a/little/example}}
 * {{Code|a:b:c}} → {{Code|a/b/c}}
 =Changelog=

@@ Line 119: / Line 119: @@
 =Module Imports=
-A Java classes 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.
+A Java class can 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:

@@ Line 6: / Line 6: @@
 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.
-{{Mark|Updated with Version 9.6:}}
+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 now be omitted.
+* The path to the standard package {{Code|java.lang.}} can be omitted.
-* Java objects are now wrapped into function items.
+* Java objects are wrapped into function items.
 * Results of constructor calls are always returned as function item.
-* A new option {{Option|WRAPJAVA}} was added to control how Java values are converted to XQuery.
+* With {{Option|WRAPJAVA}}, it can be controlled how Java values are converted to XQuery.
 =Identification=

← Older revision		Revision as of 09:25, 18 August 2021
Line 276:		Line 276:

	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.		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===		===Conversion to XQuery===