Bureaucrats, editor, reviewer, Administrators
13,550
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}}:
# 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.=Performance=
If Importing XQuery modules that are located in the resulting path has no file suffix, it may point to either an XQuery module or repository is just as fast as importing any other modules. Modules that are imported several times in a Java archiveproject will only be compiled once.The following examples show some rewritings:
* {{Code|<nowiki>http://basexImported 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.org/modules/hello/World</nowiki>}} → If you want to get optimal performance, it is recommendable to move your JAR files into the {{Code|org/basex/modules/hellolib/Worldcustom}}* {{Code|<nowiki>http://wwwdirectory of BaseX.exampleThis way, the archive will be added to the classpath if BaseX is started.com</nowiki>}} → {{Code|com/example/www/index}}* {{Code|If you have installed a/little/example}} → {{Code[[#Combined|a/little/example}}* {{Code|a:b:c}} → {{Code|a/b/c}}Combined Package]], you can simply keep your XQuery module in the repository, and the Java classes will be automatically detected.
;Version 8.2 * Added: [[#URI RewritingAdditional Libraries|URI RewritingAdditional Libraries]]: support for URNs
* Added: [[#Packaging|Packaging]], [[#URI Rewriting|URI Rewriting]]
Text replacement - "[http://files.basex.org/" to "[https://files.basex.org/"
# The [[#EXPath Packaging|EXPath Packaging]] system provides a generic mechanism for adding XQuery modules to query processors. A package is defined as a {{Code|.xar}} archive, which encapsulates one or more extension libraries.
==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 classsyntaxhighlight lang="brush:xquery">
import module namespace m = 'http://basex.org/modules/hello' at 'hello-world.xqm';
m:hello("Universe")
</presyntaxhighlight>
'''Library Module''' <code>hello-world.xqm</code> (in the same directory):
<pre classsyntaxhighlight lang="brush:xquery">
module namespace m = 'http://basex.org/modules/Hello';
declare function m:hello($world) {
'Hello ' || $world
};
</presyntaxhighlight>
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 classsyntaxhighlight lang="brush:xquery">
import module namespace functx = 'http://www.functx.com';
functx:capitalize-first('test')
</presyntaxhighlight>
=Commands=
There are various ways to handle organize your packages:
* Execute BaseX REPO commands (listed below)
* Use the GUI (''Options'' → ''Packages'')
You can even manually add and remove packages in the repository directory; all changes will automatically be detected by the query processorBaseX.
==Installation==
==Listing==
All currently installed packages can be listed with the {{Command|REPO LIST}} command. The names of all packages are listed, along with their version, their package type, and the repository path:
Name Version Type Path
A package can be deleted with {{Command|REPO DELETE}} and an additional argument, containing its name or the name suffixed with a hyphen and the package version:
REPO DELETE <nowiki>http://www.functx.com</nowiki> ...or...
REPO DELETE <nowiki>http://www.functx.com-1.0</nowiki>
==XQuery==
If an XQuery file is specified as input for the install command, it will be parsed as XQuery library module. If the file can successfully be parsed, the module URI will be [[Java Bindings#URI Rewriting|rewritten]] to a file path and attached with the {{Code|.xqm}} file suffix, and the original file will possibly be renamed and copied to that path into the repository.
'''Example:'''
Importing the repository module:
<pre classsyntaxhighlight lang="brush:xquery">
import module namespace m = 'http://basex.org/modules/Hello';
m:hello("Universe")
</presyntaxhighlight>
==Java==
Java archives (JARs) may contain one or more class files. One of them will be chosen as main class, which must be specified in a {{Code|Main-Class}} entry in the manifest file ({{Code|META-INF/MANIFEST.MF}}). This fully qualified Java class name will be rewritten to a file path by replacing the dots with slashes and attaching the {{Code|.jar}} file suffix, and the original file will be renamed and copied to that path into the repository.
If the class will be imported in the prolog of the XQuery module, an instance of it will be created, and its public functions can then be addressed from XQuery. A class may extend the {{Code|QueryModule}} class to get access to the current query context and to be enriched by some helpful annotations (see [[Java_Bindings#Context-AwarenessAnnotations|Context-AwarenessAnnotations]]).
'''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 classsyntaxhighlight lang="brush:java">
package org.basex.modules;
public class Hello {
}
}
</presyntaxhighlight>
Installation (the file will be copied to {{Code|org/basex/modules/Hello.jar}}):
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 classsyntaxhighlight lang="brush:xquery">
import module namespace m = 'http://basex.org/modules/Hello';
m:hello("Universe")
</presyntaxhighlight>
After having installed the module, all of the following URIs can be used in XQuery to import this module or call its functions (see [[Java Bindings#URI Rewriting|URI Rewriting]] for more information):
<nowiki>http://basex.org/modules/Hello</nowiki>
org/basex/modules/Hello
org.basex.modules.Hello
===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 the package will be installed, the additional library archives will be extracted and copied to a hidden sub-directory in the repository. If the package will be deleted, the hidden sub-directory will be removed as well.
; Examplary contents of {{Code|Image.jar}}
lib/
Images.jar
META-INF/
MANIFEST.MF
org/basex/modules/
Image.class
; Directory structure of the repository directory after installing the package
org/basex/modules/
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 classsyntaxhighlight lang="brush:xquery">
import module namespace m = 'http://basex.org/modules/Hello';
m:hello("Universe")
</presyntaxhighlight>
; Wrapper Module {{Code|Hello.xqm}}:
<pre classsyntaxhighlight lang="brush:xquery">
module namespace hello = 'http://basex.org/modules/Hello';
java:hello($world)
};
</presyntaxhighlight>
; Java class {{Code|Hello.java}}:
<pre classsyntaxhighlight lang="brush:java">
package org.basex.modules;
}
}
</presyntaxhighlight>
If the JAR file is installed, {{Code|Combined}} will be displayed as type:
==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:
<presyntaxhighlight>
expath-pkg.xml
functx/
functx.xql
functx.xsl
</presyntaxhighlight>
==Java==
* 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 classsyntaxhighlight lang="brush:xml">
<package xmlns="http://expath.org/ns/pkg">
<jar>...</jar>
....
</package>
</presyntaxhighlight>
* 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 classsyntaxhighlight lang="brush:java">
package test;
}
}
</presyntaxhighlight>
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 classsyntaxhighlight lang="brush:xquery">
import module namespace j="http://basex.org/lib/testJar";
return p:print($printer, $str)
};
</presyntaxhighlight>
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. =URI Rewriting= If a module is looked up in the repository, the namespace URI is rewritten to a local file path:
=Changelog=
* Added: [[#Combined|Combined]] XQuery and Java packages
;Version 7.2.1
* Updated: [[#Installation|Installation]]: existing packages will be replaced without raising an error
* Updated: [[#Removal|Removal]]: remove specific version of a package
;Version 7.1
