Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
m
If a module has been placed in the repository (see below), there is no need to specify the location. The following example calls a function from the FunctX modulein the repository:
{{Mark|Introduced with Version 9.0}}:
repo/org/basex/modules/
{{Mark|Introduced with Version 9.0}}:
Text replacement - "syntaxhighlight" to "pre"
==Accessing Modules==
Library modules can be imported with the {{Code|import module}} statement,followed by a freely choosable prefix and the namespace of the target module.The specified location may be absolute or relative; in the latter case, it is resolvedagainst the location (i.e., ''static base URI'') of the calling module.Import module statements must be placed at the beginning of a module:
'''Main Module''' <code>hello-universe.xq</code>:
<pre classlang="brush:'xquery"'>
import module namespace m = 'http://basex.org/modules/hello' at 'hello-world.xqm';
m:hello("Universe")
'''Library Module''' <code>hello-world.xqm</code> (in the same directory):
<pre classlang="brush:'xquery"'>
module namespace m = 'http://basex.org/modules/Hello';
declare function m:hello($world) {
</pre>
If no location is supplied, modules will be looked up in the repository. Repository modules are stored in a directory named {{Code|BaseXRepo}} or the {{Code|repo}}directory, which resides in your [[Configuration#Home Directory|home directory]]. XQuery modules can be manually copied to the repository directory or installed and deleted via [[#Commands|commands]].
<pre classlang="brush:'xquery"'>
import module namespace functx = 'http://www.functx.com';
functx:capitalize-first('test')
A module or package can be installed with {{Command|REPO INSTALL}}. The path to the file has to be given as a parameter:
REPO INSTALL httphttps://files.basex.org/modules/expath/functx-1.0.xar
REPO INSTALL hello-world.xqm
'''Example:'''
Installation (the original file will be copied to the {{Code|org/basex/modules/Hello}} sub-directory subdirectory of the repository):
REPO INSTALL httphttps://files.basex.org/modules/org/basex/modules/Hello/HelloWorld.xqm
Importing the repository module:
<pre classlang="brush:'xquery"'>
import module namespace m = 'http://basex.org/modules/Hello';
m:hello("Universe")
'''Example:'''
Structure of the <code>[httphttps://files.basex.org/modules/org/basex/modules/Hello/HelloWorld.jar HelloWorld.jar]</code> archive:
META-INF/
Contents of the file {{Code|Hello.java}} (comments removed):
<pre classlang="brush:java">
package org.basex.modules;
public class Hello {
REPO INSTALL HelloWorld.jar
XQuery file <code>[httphttps://files.basex.org/modules/org/basex/modules/Hello/HelloUniverse.xq HelloUniverse.xq]</code> (same as above):
<pre classlang="brush:'xquery"'>
import module namespace m = 'http://basex.org/modules/Hello';
m:hello("Universe")
===Additional Libraries===
A Java class may depend on additional libraries. The dependencies can be resolved by creating a fat JAR file, i.e., extracting all files of the library archives and producing a single, flat JAR package.
Another solution is to copy the libraries into a {{Code|lib}} directory of the JAR package. If When the package will be is installed, the additional library archives will be extracted and copied to a hidden sub-directory subdirectory in the repository. If the package will be is deleted, the hidden sub-directory subdirectory will be removed as well.
; Contents Examplary contents of {{Code|Image.jar}}
lib/
Image.class
; Directory structure of the repository directory after installing the package
Image.class
.Images/
Images.jar
==Combined==
It makes sense to combine the advantages of XQuery and Java packages:
; Main Module {{Code|hello-universe.xq}}:
<pre classlang="brush:'xquery"'>
import module namespace m = 'http://basex.org/modules/Hello';
m:hello("Universe")
; Wrapper Module {{Code|Hello.xqm}}:
<pre classlang="brush:'xquery"'>
module namespace hello = 'http://basex.org/modules/Hello';
; Java class {{Code|Hello.java}}:
<pre classlang="brush:java">
package org.basex.modules;
If the JAR file is installed, {{Code|Combined}} will be displayed as type:
REPO INSTALL httphttps://files.basex.org/modules/org/basex/modules/Hello.jar
REPO LIST
=EXPath Packaging=
The [http://expath.org/spec/pkg EXPath specification] defines how the structure of a .xar archive shall look like. The package contains at its root a package descriptor named <code>expath-pkg.xml</code>. This descriptor presents some meta data metadata about the package as well as the libraries which it contains and their dependencies on other libraries or processors.
==XQuery==
Apart from the package descriptor, a {{Code|.xar}} archive contains a directory which includes the actual XQuery modules. For example, the [httphttps://files.basex.org/modules/expath/functx-1.0.xar FunctX XAR archive] is packaged as follows:
<pre>
* Apart from the package descriptor <code>expath-pkg.xml</code>, the package has to contain a descriptor file at its root, defining the included jars and the binary names of their public classes. It must be named <code>basex.xml</code> and must conform to the following structure:
<pre classlang="brush:xml">
<package xmlns="http://expath.org/ns/pkg">
<jar>...</jar>
* The jar file itself along with an XQuery file defining wrapper functions around the java methods has to reside in the module directory. The following example illustrates how java methods are wrapped with XQuery functions:
'''Example:'''<br> Suppose we have a simple class <code>Printer</code> having just one public method <code>print()</code>:
<pre classlang="brush:java">
package test;
We want to extend BaseX with this class and use its method. In order to make this possible we have to define an XQuery function which wraps the <code>print</code> method of our class. This can be done in the following way:
<pre classlang="brush:'xquery"'>
import module namespace j="http://basex.org/lib/testJar";
As it can be seen, the class {{Code|Printer}} is declared with its binary name as a namespace prefixed with "java" and the XQuery function is implemented using the [http://docs.basex.org/wiki/Java_Bindings Java Bindings] offered by BaseX.
On our [httphttps://files.basex.org/modules/ file server], you can find some example libraries packaged as XML archives (xar files). You can use them to try our packaging API or just as a reference for creating your own packages. =Performance= Importing XQuery modules that are located in the repository is just as fast as importing any other modules. Modules that are imported several times in a project will only be compiled once. Imported Java archives will be dynamically added to the classpath and unregistered after query execution. This requires some constant overhead and may lead to unexpected effects in scenarios with highly concurrent read operations. If you want to get optimal performance, it is recommendable to move your JAR files into the {{Code|lib/custom}} directory of BaseX. This way, the archive will be added to the classpath if BaseX is started. If you have installed a [[#Combined|Combined Package]], you can simply keep your XQuery module in the repository, and the Java classes will be automatically detected.
=Changelog=
* Added: [[#Combined|Combined]] XQuery and Java packages
* Added: [[#Additional Libraries|Additional Libraries]]
;Version 7.2.1
