Changes

==Introduction==

One of the reasons why things that makes languages such as Java or Perl have been so successful is the vast amount availability of external libraries that are available to developers.As XQuery comes with only 150 pre-defined functions, which cannot meet all requirements, there is some need for additional library modules exist – such as [http://www.xqueryfunctionsfunctx.com/ FunctX] – that which extend the language with new features.

BaseX offers the following mechanisms to make external modules accessible to the XQuery processor:

# The default internal [[#Packaging|Packaging]] mechanism will install single XQuery and Java JAR modules in the repository.

==Importing 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>[http://files.basex.org/modules/org/basex/modules/Hello/HelloUniverse.xq HelloUniversehello-universe.xq]</code>:

<pre classlang="brush:'xquery"'>import module namespace m = 'http://basex.org/modules/Hellohello' at 'HelloWorldhello-world.xqm';

'''Library Module''' <code>[http://files.basex.org/modules/org/basex/modules/Hello/HelloWorld.xqm HelloWorldhello-world.xqm]</code> (in the same directory):

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

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]].

If a modules is placed in the repository, there is no need to specify a location. The following example calls a function from the FunctX modulein the repository:

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

==Commands==

BaseX provides three commands for interaction with the package repositoryThere are various ways to organize your packages: <code>[[Commands#REPO_INSTALL|REPO INSTALL]]</code>, <code>[[Commands#REPO_DELETE|REPO DELETE]]</code>, and <code>[[Commands#REPO_LIST|REPO LIST]]</code>. Packages can also be managed from within XQuery, using the [[Repository Module]].

A module or package You can even manually add and remove packages in the repository directory; all changes will automatically be installed with the {{Code|REPO INSTALL}} commanddetected by BaseX. The path to the file has to be given as a parameter:

==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 httphttps://files.basex.org/modules/expath/functx-1.0.xar

===Listing===

All currently installed packages can be listed with the <code>{{Command|REPO LIST</code> command}}. It will return the The names of all packagesare listed, along with their version, their package type, and the directory in which they are installedrepository path:

URI Name Version DirectoryType Path ----------------------------------------------------------------- <nowiki>http://www.functx.com</nowiki> 1.0 EXPath http-www.functx.com-1.0 1 package(s).

===Removal===

A package can be deleted with the command {{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...

Modules can also be installed, deleted and listed from within XQuery via the [[Repository Module]]. ==Packaging==

===XQuery===

If an XQuery file is specified as input for the install command, it will be parsed as XQuery library module. If parsing was successfulthe 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.

Installation (the original file will be copied to the {{Code|org/basex/modules/Hello.xqm}} sub-directory subdirectory of the repository):

REPO INSTALL httphttps://files.basex.org/modules/org/basex/modules/Hello/HelloWorld.xqm

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

===Java===

Suitable JAR archives may contain one or more class files. One of them will be chosen as main classFor general notes on importing Java classes, which must be specified in a {{Code|Main-Class}} entry in please read 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 with the {{CodeBindings article on [[Java Bindings#Module_Imports|.jar}} file suffix, and the original file will be renamed and copied to that path into the repositoryModule Imports]].

The public functions Java archives (JARs) may contain one or more class files. One of this them will be chosen as main class can then , which must be addressed from XQuery, using specified in a {{Code|Main-Class}} entry in the manifest file ({{Code|META-INF/MANIFEST.MF}}). This fully qualified Java class or name will be rewritten to a file path as namespace URIby replacing the dots with slashes and attaching the {{Code|.jar}} file suffix, or an alternative writing and the original file will be renamed and copied to that can path into the repository. If the class will be [[#URI Rewriting|rewritten]] to imported in the prolog of the XQuery module file path, an instance of it will be created, and its public functions can then be addressed from XQuery. Moreover, a A class may extend the {{Code|QueryModule}} class to get access to the current query context and to be enriched by some helpful annotations (please consult see [[Java_Bindings#Context-AwarenessAnnotations|Context Awareness of Java BindingsAnnotations]] for more information).

Structure of the <code>[httphttps://files.basex.org/modules/org/basex/modules/Hello/HelloWorld.jar HelloWorld.jar]</code> archive:

<pre classlang="brush:java">

XQuery file <code>[httphttps://files.basex.org/modules/org/basex/modules/Hello/HelloUniverse.xq HelloUniverse.xq]</code> (same as above):

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

After installing 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):

Please ===Additional Libraries=== A Java class may depend on additional libraries. The dependencies can be aware that 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 execution advantages of XQuery and Java packages: * Instead of directly calling Java code , a wrapper module can cause side effects be provided. This module contains functions that conflict with invoke the Java functions.* These functions can be strictly typed. This reduces the functional nature danger of erroneous or unexpected conversions between XQuery and Java code.* In addition, the entry functions can have properly maintained XQuery comments. XQueryand Java can be combined as follows: * First, or may introduce a JAR package is created (as described above).* A new security risksXQuery wrapper module is created, which is named identically to the Java main class. * The article on [[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 Bindings]] gives more insight on how Java code main class. If the resulting JAR file is handled from installed, the embedded XQuery processormodule 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 modules. For example, the [httphttps://wwwfiles.basex.org/modules/expath/functx-1.com/ 0.xar FunctX XQuery LibraryXAR archive] is packaged as follows:

===Java===

In case If you want to extend BaseX package an EXPath archive with a Java archivecode, some additional requirements have to be fulfilled:

<pre classlang="brush:xml">

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

<pre classlang="brush:java">

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

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=Performance=

If Importing XQuery modules that are looked up located in the repository, their URIs is just as fast as importing any other modules. Modules that are rewritten to imported several times in a local file path. The URI transformation has been inspired by [http://www.zorba.io/documentation/3project will only be compiled once.0/zorba/architecture/uriresolvers Zorba]:

# In Imported Java archives will be dynamically added to the URI authority, the order of all substrings separated by dots is reversedclasspath and unregistered after query execution.# Dots This requires some constant overhead and may lead to unexpected effects in the authority and the path are replaced by slashesscenarios with highly concurrent read operations. If no path existsyou want to get optimal performance, a single slash it is appended.# If the resulting string ends with a slash, recommendable to move your JAR files into the {{Code|indexlib/custom}} string directory of BaseX. This way, the archive will be added to the classpath if BaseX is appendedstarted.# Repository modules are required to If you have installed a [path component http://en.wikipedia.org/wiki/URI_scheme[#Generic_syntaxCombined|Combined Package]], you can simply keep your XQuery module in the repository, and the Java classes will be automatically detected.

* {{Code|<nowiki>http://basex;Version 9.org/modules/hello/World</nowiki>}} → {{Code|org/basex/modules/hello/World}}* {{Code|<nowiki>http://www.example.com</nowiki>}} → {{Code|com/example/www/index}}* {{Code|a/little/example}} → {{Code|a/little/example}}* {{Code|a:b:c}} → ''not supported''0