Changes

==Introduction==This article is part of the [[XQuery|XQuery Portal]].The functionality of an It describes how external XQuery processor modules and Java code can be extended with a variety of libraries. This, howeverinstalledin the XQuery module repository, becomes often a difficult task as there is no common defined installation process and different libraries comply with different rules. EXPath addresses this problem by creating a generic mechanism for extending an XQuery processor with how new packages. BaseX offers an implementation of this mechanism based on the [http://expath.org/spec/pkg specification] created by [http://expath.org/ EXPath]are built and deployed.

==What One of the things that makes languages successful is a package?==A package is a .xar archive encapsulating one or more extension the availability of external libraries. The implementation of BaseX currently supports extensions As XQuery comes with XQuery libraries and java libraries packed only 150 pre-defined functions, which cannot meet all requirements, additional library modules exist – such as [http://www.jar filesfunctx.com/ FunctX] – which extend the language with new features.

BaseX offers the following mechanisms to make external modules accessible to the XQuery processor: # The internal [[#Packaging|Packaging]] mechanism will install single XQuery and JAR modules in the repository.# 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 resolved against 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 lang='xquery'>import module namespace m ='http://basex.org/modules/hello' at 'hello-world.xqm';m:hello("Universe")</pre> '''Library Module''' <code>hello-world.xqm</code> (in the same directory): <pre lang='xquery'>module namespace m = 'http://basex.org/modules/Hello';declare function m:hello($world) { 'Hello ' || $world};</pre> If no location is supplied, modules will be looked up in the repository. Repository modules are stored in 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]]. The following example calls a function from the FunctX module in the repository: <pre lang='xquery'>import module namespace functx = 'http://www.functx.com';functx:capitalize-first('test')</pre> =Commands= There are various ways to organize your packages: * Execute BaseX REPO commands (listed below)* Call XQuery functions of the [[Repository Module]]* Use the GUI (''Options'' → ''Packages'') You can even manually add and remove packages in the repository directory; all changes will automatically be detected by BaseX. ==Installation== 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 https://files.basex.org/modules/expath/functx-1.0.xar REPO INSTALL hello-world.xqm The installation will only succeed if the specified file conforms to the constraints described below. If you know that your input is valid, you may as well copy the files directly to the repository directory, or edit its contents in the repository without deleting and reinstalling them. ==Listing== All currently installed packages can be listed with {{Command|REPO LIST}}. The names of all packages are listed, along with their version, their package type, and the repository path:  Name Version Type Path ----------------------------------------------------------------- <nowiki>http://www.functx.com</nowiki> 1.0 EXPath http-www.functx.com-1.0 ==Removal== 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> REPO DELETE <nowiki>http://www.functx.com-1.0</nowiki> =Packaging= ==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:''' Installation (the original file will be copied to the {{Code|org/basex/modules/Hello}} subdirectory of the repository):  REPO INSTALL https://files.basex.org/modules/org/basex/modules/Hello/HelloWorld.xqm Importing the repository module: <pre lang='xquery'>import module namespace m = 'http://basex.org/modules/Hello';m:hello("Universe")</pre> ==Java== For general notes on importing Java classes, please read the Java Bindings article on [[Java Bindings#Module_Imports|Module Imports]]. 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#Annotations|Annotations]]). '''Example:''' Structureof the <code>[https://files.basex.org/modules/org/basex/modules/Hello/HelloWorld.jar HelloWorld.jar]</code> archive:  META-INF/ MANIFEST.MF org/basex/modules/ Hello.class Contents of the file {{Code|MANIFEST.mf}} (the whitespaces are obligatory):  Manifest-Version: 1.0 Main-Class: org.basex.modules.Hello Contents of the file {{Code|Hello.java}} (comments removed): <pre lang="java">package org.basex.modules;public class Hello { public String hello(final String world) { return "Hello " + world; }}</pre> Installation (the file will be copied to {{Code|org/basex/modules/Hello.jar}}):  REPO INSTALL HelloWorld.jar XQuery file <code>[https://files.basex.org/modules/org/basex/modules/Hello/HelloUniverse.xq HelloUniverse.xq]</code> (same as above): <pre lang='xquery'>import module namespace m ='http://basex.org/modules/Hello';m:hello("Universe")</pre> 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. When the package is installed, the additional library archives will be extracted and copied to a hidden subdirectory in the repository. If the package is deleted, the hidden subdirectory 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: * Instead of directly calling Java code, a wrapper module can be provided. This module contains functions that invoke the Java functions.* These functions can be strictly typed. This reduces the danger of erroneous or unexpected conversions between XQuery and Java code.* In addition, the entry functions can have properly maintained XQuery comments. XQuery and Java can be combined as follows: * First, a JAR package is created (as described above).* A new XQuery wrapper module is created, which is named identically to the Java main class.* The URL of the {{Code|import module}} statement in the wrapper module must start with the {{Code|java:}} prefix.* The finalized XQuery module must be copied into the JAR file, and placed in the same directory as the Java main class. If the resulting JAR file is installed, the embedded XQuery module will be extracted, and will be called first if the module will be imported. ; Main Module {{Code|hello-universe.xq}}: <pre lang='xquery'>import module namespace m = 'http://basex.org/modules/Hello';m:hello("Universe")</pre> ; Wrapper Module {{Code|Hello.xqm}}: <pre lang='xquery'>module namespace hello = 'http://basex.org/modules/Hello'; (: Import JAR file :)import module namespace java = 'java:org.basex.modules.Hello'; (:~ : Say hello to someone. : @param $world the one to be greeted : @return welcome string :)declare function hello:hello( $world as xs:string) as xs:string { java:hello($world)};</pre> ; Java class {{Code|Hello.java}}: <pre lang="java">package org.basex.modules; public class Hello { public String hello(final String world) { return "Hello " + world; }}</pre> If the JAR file is installed, {{Code|Combined}} will be displayed as type:  REPO INSTALL https://files.basex.org/modules/org/basex/modules/Hello.jar REPO LIST Name Version Type Path ----------------------------------------------------------------------- org.basex.modules.Hello - Combined org/basex/modules/Hello.xqm =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 librariesmodules. For example , the [httphttps://wwwfiles.basex.org/modules/expath/functx-1.com/ 0.xar FunctX XQuery LibraryXAR archive] is packaged as follows:

functx.xql functx.xsl

In case you want to extend BaseX with a java library, some additional requirements have to be fulfilled: * Apart from the package descriptor <code>expath-pkg.xml</code> the package has to contain at its root a descriptor defining the included jars and the binary names of the public classes from them. It has to be named <code>basex.xml</code> and has to have the following structure:==Java==

<pre class="brush:xml"><If you want to package xmlns="httpan EXPath archive with Java code, some additional requirements have to be fulfilled://www.basex.org/pkg">

* Apart from the package descriptor <jarcode>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</jarcode>and must conform to the following structure:

  <class>...</class> <class>...</class>

'''Example:'''<br> Suppose we have a simple class <code>Printer</code> having just one public method <code>print()</code>:

<pre classlang="brush:java">

public String print(final String s) { return new Writer(s).write(); }

<pre classlang="brush:'xquery"'>

let $printer := p:new() return p:print($printer, $str)

As it can be seen , the class <code>{{Code|Printer</code> }} 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. [http://files.basex.org/xar/ Here] you can find the FunctX library packaged as a .xar and a sample package containing a .jar file. You can use them to try our packaging API or just as a reference if you want to create your own packages. ==Package repository==Unzipped packages are stored in the package repository. This is a directory named <code>BaseXRepo</code>, which is located in your home folder. Depending on your [[Configuration]], the location of your home folder varies. ==Interacting with the package repository==Now after you know what is a package and where it is stored, it comes the question how can you install and make use of such packages. BaseX offers three commands for interaction with the package repository - <code>REPO INSTALL</code>, <code>REPO DELETE</code> and <code>REPO LIST</code>. The syntax of these commands is described in [http://docs.basex.org/wiki/Commands_(Snapshot) Commands (Snapshot)]. Here we give just simple examples of their usage and the usage of a package after it is installed. ===Installing a package===A package can be installed using the <code>REPO INSTALL</code> command. The path to the package on the file system has to be given as a parameter:

<code>REPO INSTALL On our [https:/path/tofiles.basex.org/modules/file server], you can find some example libraries packaged as XML archives (xar/archive</code>files). You can use them to try our packaging API or just as a reference for creating your own packages.

=Performance==Using a package===The functionality offered by an already installed package can be used by a module import. Since we have the package repository where all packages reside, it is not needed to indicate the exact place of the module you want to use. It is enough to just import its namespace:

<pre class="brush:xquery">import module namespace functx="http://wwwImporting XQuery modules that are located in the repository is just as fast as importing any other modules.functxModules that are imported several times in a project will only be compiled once.com";</pre>

At "seeing" this statement BaseX Imported Java archives will check if be dynamically added to the namespace "http://wwwclasspath and unregistered after query execution.functxThis requires some constant overhead and may lead to unexpected effects in scenarios with highly concurrent read operations.com" If you want to get optimal performance, it is used in some 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 packages and if yesa [[#Combined|Combined Package]], it will load their modules. After that you can call the functions from a simply keep your XQuery module in the standard wayrepository, eand the Java classes will be automatically detected.g:

<pre class="brush:xquery">functx:capitalize-first("test")</pre>Changelog=

If you want to use a package which encapsulates jar files, you will have to import in the same way the namespace of the module which wraps the java methods and call the XQuery wrapper functions for these methods;Version 9.0

<code>REPO DELETE http://www;Version 7.functx2.com</code>1

<code>REPO DELETE functx-;Version 7.1.0</code>

===Listing installed packages===All currently installed packages can be listed using the <code>REPO LIST</code> command. It will list the names of all packages which currently reside in the repository along with their versions* Added:[[Repository Module]]

<pre>Name URI ;Version----------------------------------------------------functx-1.0 http://www.functx.com 17.0