BaseX Documentation Version 7.2
PDF generated using the open source mwlib toolkit. See http://code.pediapress.com/ for more information. PDF generated at: Sat, 24 Mar 2012 17:30:37 UTC Contents
Articles Main Page 1
Getting Started 3 Getting Started 3 Startup 4 Startup Options 6 Start Scripts 13
User Interfaces 16 Graphical User Interface 16 Shortcuts 20 Database Server 23 Standalone Mode 26 Web Application 27
General Info 30 Databases 30 Binary Data 32 Parsers 33 Commands 37 Options 50
Integration 64 Integrating oXygen 64 Integrating Eclipse 66
Query Features 68 Querying 68 XQuery 3.0 69 Higher-Order Functions 75 Full-Text 82 Full-Text/Japanese 85 XQuery Update 87 Java Bindings 91 Packaging 92 XQuery Errors 95 Serialization 105
XQuery Modules 108 Cryptographic Module 108 Database Module 113 File Module 120 Full-Text Module 125 HTTP Module 128 Higher-Order Functions Module 131 Index Module 133 JSON Module 135 Map Module 140 Math Module 144 Repository Module 148 SQL Module 149 Utility Module 153 XSLT Module 157 ZIP Module 160 ZIP Module: Word Documents 162
Developing 164 Developing 164 Integrate 165 Git 166 Maven 172 Releases 174 Translations 175
HTTP Services 176 REST 176 REST: POST Schema 184 RESTXQ 185 WebDAV 189 WebDAV: Windows 7 190 WebDAV: Windows XP 192 WebDAV: Mac OSX 195 WebDAV: GNOME 197 WebDAV: KDE 199
Client APIs 201 Clients 201 Standard Mode 202 Query Mode 203 PHP Example 205 Server Protocol 206 Server Protocol: Types 210 Java Examples 212
Advanced User's Guide 214 Advanced User's Guide 214 Configuration 215 Catalog Resolver 216 Statistics 218 Backups 222 User Management 222 Transaction Management 224 Logging 225 Events 226 Indexes 228 Execution Plan 230 References Article Sources and Contributors 231 Image Sources, Licenses and Contributors 233 Article Licenses License 234 Main Page 1 Main Page
Welcome to the documentation of BaseX!
BaseX [1] is both a light-weight, high-performance and scalable XML Database and an XPath/XQuery Processor with full support for the W3C Update and Full Text extensions. It focuses on storing, querying, and visualizing large XML and JSON documents and collections. A visual frontend allows users to interactively explore data and evaluate queries in realtime (i.e., with each key click). BaseX is platform-independent and distributed under the free BSD License (find BaseX GUI more in Wikipedia [2]).
This documentation is based on BaseX 7.1.1. Features that have recently been changed are flagged in red (e.g.: Version 7.2).
Getting Started The Getting Started Section gives you a quick introduction to BaseX. We suggest you to start with the Graphical User Interface as this is the easiest way to access your XML data, and to get an idea of how XQuery and BaseX works. Categories: Beginners
XQuery Portal More information on using the wide range of XQuery functions and performing XPath and XQuery requests with BaseX can be found in our XQuery Portal. Categories: XQuery
Developer Section The Developer Section provides useful information for developers. Here you can find information on various alternatives to integrate BaseX into your own project. Categories: Developer, HTTP, API
Advanced User's Guide Information for advanced users can be found in our Advanced Usage Section, which contains details on the BaseX storage and the Server architecture, and presents some more GUI features. Categories: Internals You are invited to contribute to our Wiki: it's easy to get a new account. If you have questions and are looking for direct contact to developers and users, please write to our mailing list [3] (basex[email protected]). Main Page 2
References
[1] http:/ / basex. org
[2] http:/ / en. wikipedia. org/ wiki/ BaseX
[3] http:/ / basex. org/ open-source/ 3
Getting Started
Getting Started
This page is one of the Main Sections of the documentation. It gives a quick introduction on how to start, run, and use BaseX.
Getting Started • Startup: How to get BaseX running • Startup Options: See which command-line flags exist
User Interfaces • Graphical User Interface: Working with the GUI (see available Shortcuts) • Database Server: Working with the client/server architecture • Standalone Mode: Working with the BaseX console on local databases • Web Application: Working with the HTTP server architecture
General Info • Databases: Describes how Databases are created, populated and deleted in BaseX • Parsers: Describes how to convert different input formats to XML • Commands: Commands for managing BaseX and the databases • Options: Overview on all settable options
Integration • Integrating oXygen: Use BaseX within the oXygen XML Editor • Integrating Eclipse: Use BaseX within Eclipse Startup 4 Startup
This article is part of the Getting Started Guide. It tells you how to get BaseX running.
Requirements
BaseX Please download [1] the latest BaseX version from our homepage. The official releases include the BaseX JAR file, libraries and optional Start Scripts. If you do not use an installer, we recommend to manually add the project’s bin directory to your path environment; this way, you will be able to run BaseX from everywhere in your shell/terminal.
Java A Runtime Environment of Java 1.6 [2] (JRE) is needed to run BaseX. BaseX is platform independent and runs on any system that provides a Java Virtual Machine. BaseX has been tested on Windows (2000, XP, Vista, 7), Max OS X (10.x), Linux(SuSE xxx, Debian, Ubuntu) and OpenBSD (4.x).
GUI/Standalone vs. Client/Server The standalone client and the GUI of BaseX are not synchronized with other BaseX instances. If you plan to concurrently write to the same database instances, the client/server architecture is mandatory! You may encounter unexpected behavior, and your databases might even get corrupt, if you use BaseX instances that run in different Java VMs.
BaseX GUI The GUI is the visual interface to the features of BaseX. It can be used to create new databases, perform queries or interactively explore your XML data. The GUI can be started as follows (get more information on all Startup Options): • Double click on the BaseX.jar file. • Run one of the basexgui or basexgui.bat scripts. • Execute the following command: java -cp BaseX.jar org.basex.BaseXGUI • On Windows: Double click on the BaseX GUI icon. • For Maven users: type in mvn exec:java in the main directory of the basex project.
BaseX Standalone The Standalone Mode can be used to enter database commands, or execute automated database operations and queries, on command line. The standalone version can be started as follows (get more information on all Startup Options): • Run one of the basex or basex.bat scripts. • Execute the following command: java -cp BaseX.jar org.basex.BaseX • On Windows: Double click on the BaseX icon. Startup 5
BaseX Server The Database Server comes into play if BaseX is to be used by more than one user (client). It handles concurrent read and write transactions, provides user management and logs all user interactions. By default, the server listens to the port 1984. There are several ways of starting and stopping the server (get more information on all Startup Options): • Run one of the basexserver or basexserver.bat scripts. Add the stop keyword to gracefully shut down the server. • Execute the following command: java -cp BaseX.jar org.basex.BaseXServer. Again, the stop keyword will ensure a graceful shutdown. • On Windows: Double click on the BaseX Server icon, which will also start the HTTP Server, or the BaseX Server (stop) icon. Pressing Ctrl+c will close all connections and databases and shut down the server process.
BaseX Client The BaseX Client interface can be used to send commands and queries to the server instance on command line. It can be started as follows (get more information on all Startup Options): • Run one of the basexclient or basexclient.bat scripts. • Execute the following command: java -cp BaseX.jar org.basex.BaseXClient • On Windows: Double click on the BaseX Client icon. The default admin user can be used to connect to the server: • Username: admin • Password: admin The password should be changed with the PASSWORD command after the first login. Please check out the article on the Database Server for more details.
BaseX HTTP Server The HTTP Server gives access to the REST, RESTXQ and WebDAV Services of BaseX. By default, it starts an instance of the Jetty Web Server [3], which listens to the port 8984, and the BaseX Server, which listens to 1984. The HTTP Server can be started as follows (get more information on all Startup Options): • Run one of the basexhttp or basexhttp.bat scripts. Add the stop keyword to gracefully shut down the server. • On Windows: Double click on the BaseX Server or BaseX Server (stop) icon. • For Maven users: type in mvn jetty:run in the main directory of the basex-api project, and press Ctrl+c to shut down the process. • You may also want to deploy BaseX as a Web Application. Startup 6
Changelog
Version 7.0 • Updated: the BaseXJAXRX has been replaced with BaseXHTTP
References
[1] http:/ / basex. org/ download
[2] http:/ / www. java. com
[3] http:/ / jetty. codehaus. org/ jetty/
Startup Options
This article is part of the Getting Started Guide. It gives more details on the command-line options of all BaseX start scripts.
BaseX GUI Launch the GUI
$ basexgui [file]
One or more XML and XQuery files can be passed on as parameters. If an XML file is specified, a database instance is created from this file, or an existing database is opened. XQuery files are opened in the XQuery editor.
BaseX Standalone Launch the console mode
$ basex BaseX [Standalone] Try "help" to get more information. > _
Available command-line flags can be listed with -h:
$ basex -h BaseX [Standalone] Usage: basex [-bcCdiLoqsuvVwxz] [file] [file] Execute XQuery file -b
-v/V Show (all) process info -w Preserve whitespaces from input files -x Show query execution plan -z Skip output of results
The meaning of all flags is listed in the following. If an equivalent database option exists (which can be specified via the SET command), it is listed as well:
Flag Description Option Examples
[file] Executes the specified XQuery file.
-b
-c
-C
-d Turns on the debugging mode. Debugging information is output to standard DEBUG error.
-i Opens a database or XML document specified by the argument. The opened -iitems.xml -q"//item" input may be further processed by an XQuery expression.
-L Add trailing newline after query result. Useful for batch processing or pipelining on Unix systems.
-o
-q
-s
-u Modifies original files after evaluating XQuery Update expressions. WRITEBACK
-v Prints process and timing information to the standard output.
-V Prints detailed query information to the standard output, including details QUERYINFO on the compilation and profiling steps.
-w By default, whitespaces around text nodes are chopped when a database is CHOP created. This flag can be specified to preserve whitespaces.
-x This flags turn on the output of the query execution plan, formatted in XMLPLAN XML.
-z Skips the serialization of XQuery results. This flag is useful if the query is SERIALIZE profiled or analyzed.
Multiple query files and -c/-i/-q flags can be specified. All other options will be set before any other operation takes place. The specified inputs, query files, queries and commands will be subsequently evaluated after that in the given order. The standard input can be parsed by specifying a single dash (-) as argument. Startup Options 8
BaseX Server Launch the server
$ basexserver BaseX [Server] Server was started.
Available command-line flags can be listed with -h:
$ basexserver -h BaseX [Server] Usage: basexserver [-cdeipSz] [stop] stop Stop running server -c
The flags have the following meaning (equivalent database options are shown in the table as well):
Flag Description Option Default Examples
stop Stops an existing server instance and quits.
-c
-d Turns on the debugging mode. Debugging information is output to standard DEBUG error.
-e
-i Starts the interactive console mode, which can be used to enter database commands. This mode is similar to the default standalone and client mode.
-p
-S Starts the server as service (i.e., in the background).
-z Does not generate any log files.
Multiple -c and -i flags can be specified. All other options will be set before any other operation takes place. The specified inputs, query files, queries and commands will be subsequently evaluated after that in the given order. The standard input can be parsed by specifying a single dash (-) as argument. Startup Options 9
BaseX Client Launch the console mode communicating with the server The user name and password will be requested. The default user/password combination is admin/admin:
$ basexclient Username: admin Password: ***** BaseX [Client] Try "help" to get more information. > _
Available command-line flags can be listed with -h:
$ basexclient -h BaseX [Client] Usage: basexclient [-bcCdiLnopPqsUvVwxz] [file] [file] Execute XQuery file -b
The flags have the following meaning (equivalent database options are shown in the table as well):
Flag Description Option Default Examples
[file] Executes the specified XQuery file.
-b
-c
-C
-d Turns on the debugging mode. Debugging information is DEBUG output to standard error.
-i Opens a database or XML document specified by the -iitems.xml -q"//item" argument. The opened input may be further processed by an XQuery expression.
-L Add trailing newline after query result. Useful for batch processing or pipelining on Unix systems.
-n
-o
-p
-P
-q
-s
-U
-v Prints process and timing information to the standard output.
-V Prints detailed query information to the standard output, QUERYINFO including details on the compilation and profiling steps.
-w By default, whitespaces around text nodes are chopped CHOP when a database is created. This flag can be specified to preserve whitespaces.
-x This flags turn on the output of the query execution plan, XMLPLAN formatted in XML.
-z Skips the serialization of XQuery results. This flag is SERIALIZE useful if the query is profiled or analyzed.
Multiple query files and -c/-i/-q flags can be specified. All other options will be set before any other operation takes place. The specified inputs, query files, queries and commands will be subsequently evaluated after that in the given order. The standard input can be parsed by specifying a single dash (-) as argument. Startup Options 11
BaseX HTTP Server Launch the HTTP server
$ basexhttp BaseX [Server] Server was started. 2011-01-02 03:04:05.600:INFO::Logging to STDERR via org.mortbay.log.StdErrLog 2011-01-02 03:04:05.700:INFO::jetty-6.1.26 2011-01-02 03:04:05.800:INFO::Started [email protected]:8984
Available command-line flags can be listed with -h:
$ basexhttp -h BaseX [HTTP] Usage: basexhttp [-dehlnpPRUWz] [stop] stop Stop running server -c Start in client mode -d Activate debugging mode -e
The flags have the following meaning (equivalent database options are shown in the table as well):
Flag Description Option Default Examples
stop Stops a running HTTP server. By default, the database server will be stopped as well, unless one of the flags -c or -l is specified.
-c Starts the server in client mode, and sends all commands to a database server instance.
-d Turns on the debugging mode. Debugging information is output to DEBUG standard error.
-e
-h
-l Starts the server in local mode, and executes all commands in the embedded database context.
-n
-p
-P
-R Deactivates the REST service.
-s
-S Starts the server as service (i.e., in the background).
-U
-W Deactivates the WebDAV service.
-X Deactivates the RESTXQ service. Since Version 7.2
-z Does not generate any log files.
Some options can also be triggered by setting the following system properties: • org.basex.user: user name for opening new sessions • org.basex.password: user password for opening new sessions • org.basex.mode: by default, the HTTP server also starts an instance of the database server. If the mode is set to local, an embedded database context is used for executing commands. If the mode is set to client, all commands are sent to an existing database server instance. • org.basex.path: path to the BaseX Home Directory
Changelog
Version 7.2 • Added: RESTXQ Service
Version 7.1.1 • Added: Options -C and -L in standalone and client mode
Version 7.1 • Multiple query files and -c/-i/-q flags can be specified.
References
[1] http:/ / www. jclark. com/ xml/ xmlns. htm
[2] http:/ / www. w3. org/ TR/ xquery-30/ #id-basics Start Scripts 13 Start Scripts
The following scripts, which are mentioned on the Startup and Startup Options pages, are also included in our official Windows and ZIP release files, and available in our GitHub repository [1]: • The installers automatically add the project’s bin directory to your path environment. • Otherwise, you can manually add the bin directory to your PATH environment variable.
BaseX Main Package The following scripts launch the standalone version of BaseX. Please replace the class name in org.basex.BaseX with either BaseXClient, BaseXServer, or BaseXGUI to run the client, server or GUI version.
Windows: basex.bat @setlocal @echo off
REM Path to this script set PWD=%~dp0
REM Paths to distributed JAR archives or class files set BASEX=basex.jar
REM Options for virtual machine set VM=-Xmx512m
REM Classpath set LIB=%PWD%/../lib set CP=%BASEX%;%LIB%/lucene-analyzers-3.0.2.jar;%LIB%/tagsoup-1.2.jar;%LIB%/snowball.jar
REM Run BaseX java -cp "%CP%" %VM% org.basex.BaseX %*
Linux/Mac: basex #!/bin/bash
# Path to this script PWD=`dirname $0`
# Paths to distributed JAR archives or class files BASEX=basex.jar
# Options for virtual machine VM=-Xmx512m Start Scripts 14
# Classpath LIB=$PWD/../lib CP=$BASEX:$LIB/lucene-analyzers-3.0.2.jar:$LIB/tagsoup-1.2.jar:$LIB/snowball.jar
# Run BaseX java -cp "$CP" $VM org.basex.XXX "$@"
BaseX HTTP Server The scripts for starting the HTTP server, which gives access to the REST, RESTXQ and WebDAV services, can be found below. Note: In Version 7.2, the BaseXHTTP start class will be moved from the org.basex.api package to org.basex.
Windows: basexhttp.bat @echo off setlocal
REM Path to this script set PWD=%~dp0
REM Paths to distributed JAR archives or class files set BASEX=%PWD%/basex.jar set BASEXAPI=%PWD%/basex-api.jar
REM Classpath set LIB=%PWD%/../lib set CP=%BASEX%;%BASEXAPI%;%LIB%/commons-beanutils-1.8.2.jar;%LIB%/commons-codec-1.4.jar;%LIB%/commons-fileupload-1.2.2.jar;%LIB%/commons-io-1.4.jar;%LIB%/commons-logging-1.1.1.jar;%LIB%/jdom-1.1.jar;%LIB%/jetty-6.1.26.jar;%LIB%/jetty-util-6.1.26.jar;%LIB%/log4j-1.2.14.jar;%LIB%/lucene-analyzers-3.0.2.jar;%LIB%/milton-api-1.6.4.jar;%LIB%/mime-util-2.1.3.jar;%LIB%/resolver.jar;%LIB%/servlet-api-2.5-20081211.jar;%LIB%/slf4j-api-1.5.8.jar;%LIB%/slf4j-log4j12-1.5.6.jar;%LIB%/snowball.jar;%LIB%/tagsoup-1.2.jar;%LIB%/xmldb-api-1.0.jar;%LIB%/xqj-api-1.0.jar
REM Options for virtual machine set VM=-Xmx512m
REM Run code java -cp "%CP%;." %VM% org.basex.api.BaseXHTTP %*
Linux/Mac: basexhttp #!/bin/bash
# Path to this script PWD=`dirname $0`
# Paths to distributed JAR archives or class files BASEX=$PWD/basex.jar BASEXAPI=$PWD/basex-api.jar Start Scripts 15
# Classpath LIB=$PWD/../lib CP=$BASEX:$BASEXAPI:$LIB/commons-fileupload-1.2.2.jar:$LIB/commons-beanutils-1.8.2.jar:$LIB/commons-codec-1.4.jar:$LIB/commons-fileupload-1.2.2.jar:$LIB/commons-io-1.4.jar:$LIB/commons-logging-1.1.1.jar:$LIB/jdom-1.1.jar:$LIB/jetty-6.1.26.jar:$LIB/jetty-util-6.1.26.jar:$LIB/log4j-1.2.14.jar:$LIB/lucene-analyzers-3.0.2.jar:$LIB/milton-api-1.6.4.jar:$LIB/mime-util-2.1.3.jar:$LIB/resolver.jar:$LIB/servlet-api-2.5-20081211.jar:$LIB/slf4j-api-1.5.8.jar:$LIB/slf4j-log4j12-1.5.6.jar:$LIB/snowball.jar:$LIB/tagsoup-1.2.jar:$LIB/xmldb-api-1.0.jar:$LIB/xqj-api-1.0.jar
# Options for virtual machine VM=-Xmx512m
# Run code java -cp "$CP" $VM org.basex.api.BaseXHTTP "$@"
Changelog
Version 7.2 • The BaseXHTTP start class will be moved from org.basex.api to org.basex.
Version 7.0 • The basexjaxrx scripts have been replaced with the basexhttp scripts.
References
[1] https:/ / github. com/ BaseXdb/ basex-dist/ tree/ master/ bin 16
User Interfaces
Graphical User Interface
This page is part of the Getting Started Section. The BaseX homepage gives you a visual impression [1] of the graphical user interface (GUI) of BaseX, and the introductory video [2] presents some of the interactive features that the BaseX GUI provides. This small tutorial demonstrates how easy it is to perform simple XPath queries.
Startup First of all, please launch a GUI instance of BaseX. Depending on your operating system, double click on the BaseX GUI start icon or run the basexgui script. Follow this link for more information (or check out the additional command-line options).
Create Database Select Database → New and browse to an XML document of your choice. As an example, the factbook.xml document, which contains statistical information on the worlds' countries, is included in the official releases of BaseX, and it can also be downloaded here [3]. Next, choose the OK button, and BaseX will create a database that you can visually explore.
Realtime Options Via the Options menu, you can change the way how queries are executed and visualized: • Realtime Execution: If realtime execution is enabled, your searches and queries will be executed with each key click and the results will be instantly shown. • Realtime Filtering: If enabled, all visualizations will be limited to the actual results in realtime. If this feature is disabled, the query results are highlighted in the visualizations and can be ecplicitly filtered with the 'Filter' button.
Querying
Keyword Search The Keyword Search can be executed in the Search mode in the combo box of the main window. This options allows for a simple, keyword-based search in the opened database. The following syntax is supported: Graphical User Interface 17
Query Description
world Find tags and texts containing world
=world Find exact matching text nodes
~world Find text nodes similar to world
@world Find attributes and attribute values
@=world Find exact attribute values
"united world" Find tags and texts containing the phrase "united world"
XPath/XQuery Apart from the basic search facilities, BaseX offers far more sophisticated processing options to query your documents. Below are some examples you might give a try. This guide is far from being a comprehensive XQuery reference, but might point you in the right direction. To execute the following queries, enter them in the XQuery Panel and press ENTER or click on the START button. XPath provides an easy facility to query your documents in a navigational manner. It is the basic tool of all node-related operations that you encounter when using XQuery. We will start with a trivial example and extend it to our needs. Example: Find Countries
//country
tells BaseX to look for all country elements in the document. The query is introduced by two slashes //, which trigger the traversal of all document nodes. The queries //country andd /descendant::country will return the same results. Example: Find Cities in Switzerland The following query uses a predicate [...] to filter all country nodes which have a name child, the string value of which is "Switzerland":
//country[name = "Switzerland"]
To return all cities of the resulting element node, the query can be extended by a trailing //city path:
//country[name = "Switzerland"]//city Graphical User Interface 18
Visualizations The BaseX GUI offers various visualizations, which help you to explore your XML data instances from different perspectives:
Text View Map View
Text Map [4] Displays query results and other textual output. Query results This visualization represents all data in a TreeMap . All nodes of can be saved in a file. the XML document are represented as rectangles, filling the complete area. You can choose different layout algorithms in the Menu Options → Map Layout.
Folder View Tree View Folder Tree This visualization displays all nodes in an Explorer-like folder This visualization displays all XML nodes in a top down tree view. Nodes can be expanded or closed by clicking on the arrows. with edges and nodes. You can change some settings of the Tree in the Menu Options → Tree Options.
The Table View Scatterplot View
Table Plot This visualization comes in handy if your data is highly regular. It This visualization displays all nodes in a scatterplot, which is displays all nodes in a table with rows and columns. Different particularly helpful if you want to explore analyze your data. assignments can be chosen by clicking on the arrow in the right Three drop down menus allow custom axis assignments. upper corner. Graphical User Interface 19
Explorer View Info View
Explorer Info With this visualization you can explore the contents of your This view is helpful for analyzing the query plans of your XQuery database via drop-down menus, search fields and double expressions. It also displays information on the compilation and sliders. evaluation of queries.
What's Next? For more information on BaseX, XQuery and XPath, we invite you to... • check out more Documentation, and • have a look at the XQuery Tutorial at W3Schools [5].
References
[1] http:/ / basex. org/ products/ gui
[2] http:/ / www. youtube. com/ watch?v=xILHKGPGaJ4& hd=1
[3] http:/ / files. basex. org/ xml/ factbook. xml
[4] http:/ / en. wikipedia. org/ wiki/ Treemap
[5] http:/ / www. w3schools. com/ xquery/ Shortcuts 20 Shortcuts
This page is part of the Getting Started Section. It gives you an overview of the keyboard shortcuts available in the GUI of BaseX.
Global Shortcuts The following shortcuts are available from most GUI components:
Description Win/Linux Mac
Jump to input bar Ctrl L ⌘ L F6 ⌘ F6
Jump to next/previous panel Ctrl (Shift) Tab Ctrl (Shift) Tab
Increase/Decrease font size Ctrl +/- ⌘ +/-
Reset font size Ctrl 0 ⌘ 0
Description Win/Linux Mac
Browse back/forward Alt ←/→ ⌘ ←/→ Backspace
Browse one level up Alt ↑ ⌘ ↑
Browse to the root node Alt Home ⌘ Home
Editor Shortcuts The text editor can be used to create, edit and save XQuery expressions, XML documents and any other text-based files. It provides numerous shortcuts, which are listed below.
Editing
Description Win/Linux Mac
Execute query Ctrl Enter ⌘ Enter
(Un)comment selection/line Ctrl K ⌘ K
Undo recent changes Ctrl Z ⌘ Z
Redo recent changes Ctrl Y ⌘ Shift Z
Cut selection Ctrl X ⌘ X Ctrl Delete
Copy selection to clipboard Ctrl C ⌘ C Ctrl Insert
Paste from clipboard Ctrl V ⌘ V Shift Insert
Select All Ctrl A ⌘ A
Delete character left of cursor Backspace Backspace
Delete character right of cursor Delete Delete (fn Backspace)
Delete word left of cursor Ctrl Backspace Alt Backspace
Delete word right of cursor Ctrl Delete Alt Delete Shortcuts 21
Delete text left of cursor Ctrl Shift Backspace ⌘ Backspace
Delete text right of cursor Ctrl Shift Delete ⌘ Delete
Find
Description Win/Linux Mac
Find text Ctrl F ⌘ F
Find next instance of text Ctrl G ⌘ G F3 ⌘ F3
Find previous instance of text Ctrl Shift G ⌘ Shift G Shift F3 ⌘ Shift F3
Navigation
Description Win/Linux Mac
Move one character to the left/right ←/→ ←/→
Move one word to the left/right Ctrl ←/→ Alt ←/→
Move to beginning/end of line Home/End ⌘ ←/→
Move one line up/down ↑/↓ ↑/↓
Move one screen-full up/down Page ↑/↓ Page ↑/↓ (fn ↑/↓)
Move to top/bottom Ctrl Home/End ↖/↘ (⌘ ↑/↓)
Scroll one line up/down Ctrl ↑/↓ Alt ↑/↓
Menu Shortcuts The following commands and options are also linked from the main menu:
Database
Description Win/Linux Mac
Create new database Ctrl N ⌘ N
Open/manage existing databases Ctrl O ⌘ O
View/edit database properties Ctrl D ⌘ D
Close opened database Ctrl W ⌘ W
Exit application Ctrl Q ⌘ Q
Query Shortcuts 22
Description Win/Linux Mac
Toggle query/text editor Ctrl E ⌘ E
Toggle query info view Ctrl I ⌘ I
Create new text file Ctrl Shift N ⌘ Shift N
Open existing text file Ctrl R ⌘ R
Save text file Ctrl S ⌘ S
Save copy of text file Ctrl Shift S ⌘ Shift S
Close opened text file Ctrl Shift W ⌘ Shift W
Help
Description Win/Linux Mac
Show Help F1 F1
View
Description Win/Linux Mac
Toggle text view Ctrl 1 ⌘ 1
Toggle map view Ctrl 2 ⌘ 2
Toggle tree view Ctrl 3 ⌘ 3
Toggle folder view Ctrl 4 ⌘ 4
Toggle plot view Ctrl 5 ⌘ 5
Toggle table view Ctrl 5 ⌘ 5
Toggle explorer view Ctrl 7 ⌘ 7
Nodes
Description Win/Linux Mac
Copy path to current node Ctrl Shift C ⌘ Shift C
Options
Description Win/Linux Mac
Open preference dialog Ctrl P ⌘ P Database Server 23 Database Server
This step by step tutorial is part of the Getting Started Guide. It shows you how to run BaseX in client-server mode from a terminal. You can copy and paste all commands to get them running on your machine. After you finished this tutorial, you will be familiar with the basic administration of BaseX. Visit the commands section for a complete list of database commands.
Startup First of all, please launch a Server and Client instance of BaseX: double click on the BaseX Server/Client icons, or run the basexserver and basexclient scripts. Follow this link for more information (or check out the additional command-line options).
Create a database • To create a database you need an XML document, e.g. factbook.xml [3]. • Save this document to the directory you are working in. • In the client terminal, type in: > Commands#CREATE DATABASECREATE DB factbook factbook.xml factbook is the name of the database factbook.xml is the xml file, which is used to create the database If everything works you see the following lines:
Database 'factbook' created in 950.83 ms.
Where is the database stored? By default, databases are stored in the BaseXData directory, which is located in your home folder. Depending on your Configuration, the location of your home folder varies. For example, on a Mac it's /Users/John, if your name is John. If you have used the Windows Installer, the directory will be named data, and reside in the application directory.
Execute a query The XQUERY command lets you run a query. • For example, this query returns all country nodes in the currently opened database. > Commands#XQUERYXQUERY //country • You can also run queries in files: > Commands#RUNRUN /Users/John/query.xq Database Server 24
Create a new database Now we will create another database from the xmark.xml [1] document. • Create the new database, named 'xmark'. > Commands#CREATE DATABASECREATE DB xmark xmark.xml • Set the new database xmark as the context: > Commands#OPENOPEN xmark • Now you can easily execute queries on your new database: > Commands#XQUERYXQUERY //people/person/name
Switch the database • You can explicitly query the factbook database with the doc(...) funtion, no matter what the current context is. > Commands#XQUERYXQUERY doc("factbook")//country • Otherwise, to set factbook as the current context, execute the following: > Commands#OPENOPEN factbook • To list the current context, type: > Commands#SHOWSHOW DATABASES That yields the following lines:
1 opened database(s): - factbook (1x)
Close or delete a database • To close the current context database, please type: > Commands#CLOSECLOSE • Use the DROP command to delete the xmark database: > Commands#DROP DATABASEDROP DB xmark
Create a collection What is a collection? With BaseX you can group documents into one logical collection. A collection is a database that contains two or more documents. Collections accept any type of XML documents, regardless of their structure. Let's add the xmark.xml document to the factbook database to create a collection. The name of the original factbook database remains. • First make sure factbook is opened: > Commands#OPENOPEN factbook • Now add the xmark.xml document: > Commands#ADDADD xmark.xml Database Server 25
Delete a document • Deleting a document from a collection is easy: > Commands#DELETEDELETE xmark.xml Make sure that the collection, which contains the xmark.xml document, is opened.
Delete a collection Deleting a collection is the same as deleting a database. • To delete the collection factbook, type: > Commands#DROP DATABASEDROP DB factbook
Get server information Several commands help to explore the state of a server. For a complete list, please visit the Commands Section. • To see all databases on the server, type: > Commands#LISTLIST • To see which database is currently opened: > Commands#SHOW DATABASESSHOW DATABASES • To see the general information of the opened database, type: > Commands#INFOINFO • To see the users in BaseX, type: > Commands#SHOW USERSSHOW USERS
Backup and restore • To backup your database, type: > CREATE BACKUP factbook • To restore your database, type: > RESTORE factbook Where is the backup-file stored? The backup-file is stored in the database directory. The file is named factbook-timestamp.zip (db_name-timestamp.zip). To restore the database the file with the newest timestamp is taken.
References
[1] http:/ / files. basex. org/ xml/ xmark. xml Standalone Mode 26 Standalone Mode
This page is part of the Getting Started Section. BaseX offers a standalone (embedded) console mode from which all database commands can be executed. The article on the Database Server provides numerous examples for running commands in the console mode.
Startup First of all, please launch a standalone version of BaseX: double click on the BaseX icon, or run the basex script. Follow this link for more information (or check out the additional command-line options).
Working with the BaseX Console After the BaseX Console has been started, the HELP command can be used to to list all database commands. Multiple commands can be separated by semicolons. To evaluate commands without entering the console mode, you can use the -c option on the command line:
basex -Vc "CREATE DB input
Database 'input' created in 124.95 ms.
Query: /
Compiling:
Result: root()
Parsing: 0.42 ms Compiling: 9.3 ms Evaluating: 0.35 ms Printing: 5.53 ms Total Time: 15.62 ms
Hit(s): 1 Item Updated: 0 Items Printed: 10 Bytes
Query executed in 15.62 ms.
All available command-line options can be found here. Web Application 27 Web Application
BaseX provides access to stored database resources and to the XQuery engine via REST, RESTXQ and WebDAV services. This article describes different ways of deploying and configuring these services. The services can be deployed in 3 different ways: • as web servlets in a J2EE servlet container, • for development purposes, using maven, and • as a standalone application.
Servlet Container In order to deploy BaseX HTTP Services in a servlet container, you need to download the WAR distribution of BaseX from the download site [1]. The WAR file can then be deployed following the instructions of the corresponding servlet container (jetty [1], tomcat [2]).
Servlet Container Configuration Configuring port, context path, etc. can be done following the corresponding instructions of the used servlet
container. This is needed if you want to replace the default URL path (e.g. http:/ / localhost:8080/ rest) with a custom
one (e.g. http:/ / localhost:8080/ BaseX711/ rest).
Database Access There are two modes in which the BaseX web application can access databases: • local mode: the web application will access and store data on the local file system. • client mode: the application communicates with a separately started database server. The operation mode can be configured as explained further below. Note: if the web application stores data in the local file system of the servlet container, then by default it will use a separate directory as home directory. This is because, in many production environments, the servlet container runs as a dedicated user without a $HOME directory. However BaseX needs to store somewhere it's settings and data. This is why, even when running a servlet container with a normal user (i.e. one which has a $HOME directory), the web application will not use by the default the settings stored in $HOME/.basex and will have a different set (or empty set) of databases than the one in the case of the standalone HTTP server. However, this behavior can be changed by manually setting the BaseX home directory to $HOME, in which case the web application will use the same databases as in the case of the standalone server.
Configuring Available Services To enable or disable one of the provided services, the corresponding servlet entry in the web.xml file needs to be removed/commented. The default URL paths are listed in the following table: Web Application 28
Service URL usage
REST http://[host]:[port]/[servlet_context_path]/rest access XML database and its resources, see REST
RESTXQ {{Mono|http://[host]:[port]/[servlet_context_path]/restxq create XQuery Web Services, see RESTXQ
WebDAV http://[host]:[port]/[servlet_context_path]/webdav or access databases via the filesystem, see webdav://[host]:[port]/[servlet_context_path]/webdav (depending on WebDAV client)
Web http://[host]:[port]/[servlet_context_path] access your standard web files (e.g. Server HTML, JavaScript or CSS).
Configuring Database Access The following options are available to configure the way the databases are accessed. These can be set in the web.xml file or as Java system variables (e.g. using -Dorg.basex.mode=client from the command line).
Option Default Description
org.basex.mode local Operation mode. By default, the value is "local": the servlets will access and store data locally using org.basex.path. If "client" is specified, all operations are performed on a remote server instance (the login data of which is stored in the .basex configuration file).
org.basex.user - Database user. By default, no value is specified, and the credentials must be specified by the client. Note that it is a clear security risk to store user credentials in the web.xml file. The default user credentials can be found under Startup: BaseX Client.
org.basex.password - Database user password.
Additionally, all database main options, which are usually stored in the .basex configuration file (DBPATH, HTTPPATH, etc.), can be specified as well by prefixing the key with org.basex.. If an option references a relative path, it will be prefixed with the servlet root path. Some examples follow:
How to set these options in the web.xml of the BaseX web application is specific to the servlet container. For example, in Jetty it is done using an overriding web.xml [3]. Another option is to directly edit the WEB-INF/web.xml file in the WAR archive (WAR files are simple ZIP files). Web Application 29
Maven Checkout the sources of basex and basex-api as described under Integrate: Check Out. Execute mvn install in the basex project folder and then mvn install jetty:run in the basex-api project folder. This will start a Jetty instance in which the servlets will be deployed.
Configuration The same options as in the case of deployment in a servlet container apply. In this case, however, there is no WAR archive. Instead, Jetty uses the directory basex-api/src/main/webapp. For configuring various Jetty runtime options, such as port, context path, etc. refer to the Maven Jetty Plugin [4]. These should be entered in the pom.xml file of the basex-api project.
Standalone Application Detailed description how to start and setup the standalone BaseX HTTP server can found under Startup: BaseX HTTP Server.
Changelog
Version 7.2 • Web Application concept revised
References
[1] http:/ / docs. codehaus. org/ display/ JETTY/ WebAppDeployer
[2] http:/ / tomcat. apache. org/ tomcat-6. 0-doc/ deployer-howto. html
[3] http:/ / docs. codehaus. org/ display/ JETTY/ override+ web. xml
[4] http:/ / docs. codehaus. org/ display/ JETTY/ Maven+ Jetty+ Plugin 30
General Info
Databases
This page is part of the Getting Started Section. In BaseX, a single database contains an arbitrary number of resources, addressed by their unique database path. Since Version 7.0, resources can either be XML documents or raw files (binaries). Sets of XML documents are also called collections. Some information on binary data can be found on an extra page.
Create/Drop Database New databases can either be created in the GUI, on command line, or using any of our APIs. XML documents can be specified along with the create operation, which will be added to the database in a bulk operation: • Console: enter basex -c "CREATE DB dbname /path/to/resources" • GUI: Go to Database → New, press Browse to choose an initial file or directory, and press OK Various parsers can be chosen to influence the database creation, or to convert different formats to XML, Existing databases can eventually be dropped again: • Console: enter basex -c "DROP DB dbname". • GUI: Go to Database → Manage and choose the database to be dropped Database must follow the valid names constraints.
Manage Resources Once you have created a database, additional commands exist to modify its contents: • XML documents can be added with the ADD command. • Raw files are added with STORE. • Resource can be replaced with other ones with the REPLACE command. • Resources can be deleted via DELETE. The AUTOFLUSH option can be turned off before bulk operations (i.e. before a large number of new resources is added to the database). The following commands create an empty database, add two resources, explicitly flush data structures to disk, and finally delete all inserted data:
CREATE DB example SET AUTOFLUSH false ADD example.xml ADD ... STORE TO images/ 123.jpg FLUSH DELETE /
You may as well use the BaseX-specific XQuery Database Functions to add, replace and delete XML documents: for $file in file:list("/path/to/xml/documents") return db:add("database", $file) Databases 31
Last but not least, XML documents can also be added via the GUI and the Database menu.
Access Resources Stored resources and external documents can be accessed in different ways:
XML Documents Various XQuery functions exist to access the XML documents in databases and other locations: • db:open("dbname", "path/to/docs"): (only) returns documents that are found in the specified database. • collection("path/to/docs"): returns the documents that are either found in the database specified in the argument, or at the specified location (file path or URL). • doc("path/to/document.xml"): returns a single document found at the specified location (file path or URL). If a database already exists for the addressed resource, it is opened instead.
Raw Files • XQuery: db:retrieve("dbname", "path/to/docs") returns raw files in their Base64 representation. By choosing "method=raw" as Serialization Option, the data is returned in its original byte representation:
declare option output:method "raw"; db:retrieve('multimedia', 'sample.avi')
• Commands: RETRIEVE returns raw files without modifications.
HTTP Services • With REST and WebDAV, all database resources can be requested in a uniform way, no matter if they are well-formed XML documents or binary files.
Export Data All resources stored in a database can be exported, i.e., written back to disk. This can be done in several ways: • Commands: EXPORT writes all resources to the specified target directory • GUI: Go to Database → Export, choose the target directory and press OK • WebDAV: Locate the database directory (or a sub-directory of it) and copy all contents to another location Binary Data 32 Binary Data
This page is linked from the Database page. Since Version 7.0, the BaseX store has been extended to also support binary (raw) files. Each database may contain both XML documents and binary files. Both XML and binary data is handled in a uniform way: a unique database path serves as key, and the contents can be retrieved via database commands, XQuery, or the various APIs.
Storage XML documents are stored in a proprietary format to speed up XPath axis traversals and update operations, and raw data is stored in its original format in a dedicated sub-directory (called "raw"). Several reasons exist why we did not extend our existing storage to binary data: • Good Performance: the file system generally performs very well when it comes to the retrieval and update of binary files. • Key/Value Stores: we do not want to compete with existing key/value database solutions. Again, this is not what we are after. • Our Focus: our main focus is the efficient storage of hierarchical data structures and file formats such as XML or (more and more) JSON. The efficient storage of arbitrary binary resources would introduce many new challenges that would distract us from more pressing tasks. For some use cases, the chosen database design may bring along certain limitations: • Performance Limits: most file system are not capable of handling thousands or millions of binary resources in a single directory in an efficient way. The same problem happens if you have a large number of XML documents that need to imported in or exported from a BaseX database. The general solution to avoid this bottleneck is to distribute the relevant binaries in additional sub-directories. • Keys: if you want to use arbitrary keys for XML and binary resources, which are not supported by the underlying file system, you may either add an XML document in your database that contains all key/path mappings. In the latter case, a key/value store might be the better option anyway.
Usage More information on how to store, retrieve, update and export binary data is found in the general Database documentation. Parsers 33 Parsers
This article is part of the Getting Started Section. It presents different parsers for importing various data source into BaseX databases. For export see Serialization.
XML Parsers BaseX provides two parsers to import XML data: • By default, the internal, built-in XML parser is used, which is more fault-tolerant than Java’s XML parser. It supports standard HTML entities out-of-the-box, and is faster in most cases. In turn, it does not support all oddities specified by DTDs, and cannot resolve catalogs. • Java’s SAXParser [1] can also be selected for parsing XML documents. This parser is stricter than the built-in parser, but it refuses to process some large documents.
GUI Go to Menu Database → New, then choose the Parsing tab and (de)activate Use internal XML parser. The parsing of DTDs can be turned on/off by selecting the checkbox below.
Command Line To turn the internal XML parser and DTD parsing on/off, modfify the INTPARSE and DTD options:
SET INTPARSE true SET DTD true
XQuery The db:add() or db:replace() function can be used as well to add new XML documents to the database. The following example query uses the internal parser and adds all files to the database DB that are found in the directory 2Bimported:
declare option db:intparse "yes"; for $file in file:list("2Bimported") return db:add('DB', $file)
HTML Parser With TagSoup [2], HTML can be imported in BaseX without any problems. TagSoup ensures that only well-formed HTML arrives at the XML parser (correct opening and closing tags, etc.). Hence, if TagSoup is not available on a system, there will be a lot of cases where importing HTML fails, no matter whether you use the GUI or the standalone mode.
Installation If the TagSoup classes are accessible via the classpath, or if you run BaseX from the sources and use the Maven build manager, BaseX will automatically use TagSoup to prepare HTML input. TagSoup is also included in the complete BaseX distributions (BaseX.zip, BaseX.exe, etc.) or can be manually downloaded and embedded on the appropriate platforms. Using Debian, TagSoup will be automatically included after it has been installed via:
apt-get install libtagsoup-java Parsers 34
Options Introduced with Version 7.2: TagSoup offers a variety of options to customize the import of HTML. For the complete list please visit the TagSoup [2] website. BaseX supports most of these options with a few exceptions: • encoding: BaseX tries to guess the input encoding but this can be overwritten by the user if necessary. • files: Not supported as input documents are piped directly to the XML parser. • method: Set to 'xml' as default. If this is set to 'html' ending tags may be missing for instance. • version: Dismissed, as TagSoup always falls back to 'version 1.0', no matter what the input is. • standalone: Deactivated. • pyx, pyxin: Not supported as the XML parser can't handle this kind of input. • output-encoding: Not supported, BaseX already takes care of that. • reuse, help: Not supported.
GUI Go to Menu Database → New and select "HTML" in the input format combo box. There's an info in the "Parsing" tab about whether TagSoup is available or not. The same applies to the "Resources" tab in the "Database Properties" dialog. These two dialogs come with an input field 'Parameters' where TagSoup options can be entered.
Command Line Turn on the HTML Parser before parsing documents, and set a file filter:
SET PARSER html SET HTMLOPT method=xml,nons=true,ncdata=true,nodefaults=true,nobogons=true,nocolons=true,ignorable=true SET CREATEFILTER *.html
XQuery declare option db:parser "html"; declare option db:htmlopt "html=false"; doc("index.html")
JSON Parser BaseX can also import JSON documents:
GUI Go to Menu Database → New and select "JSON" in the input format combo box. You can set the following options for parsing JSON documents in the "Parsing" tab: • Encoding: Choose the appropriate encoding of the JSON file. • JsonML: Activate this option if the incoming file is a JsonML file. Parsers 35
Command Line Turn on the JSON Parser before parsing documents, and set some optional, parser-specific options and a file filter:
SET PARSER json SET PARSEROPT encoding=utf-8, jsonml=true SET CREATEFILTER *.json
CSV Parser BaseX can be used to import CSV documents. Different alternatives how to proceed are shown in the following:
GUI Go to Menu Database → New and select "CSV" in the input format combo box. You can set the following options for parsing CSV documents in the "Parsing" tab: • Encoding: Choose the appropriate encoding of the CSV file. • Separator: Choose the column separator of the CSV file (possible: comma, semicolon, tab). • XML format: Choose the XML format (possible: verbose, simple). • Header: Activate this option if the incoming CSV files have a header line.
Command Line Turn on the CSV Parser before parsing documents, and set some optional, parser-specific options and a file filter:
SET PARSER csv SET PARSEROPT encoding=utf-8, lines=true, format=verbose, header=false, separator=comma SET CREATEFILTER *.csv
XQuery The CSV parser can also be specified in the prolog of an XQuery expression. The db:add() or db:replace() function can be used to add the specified source files into the database. The following example query adds all CSV files to the database DB that are found in the directory 2Bimported, and interprets the first lines as column headers:
declare option db:parser "csv"; declare option db:parseropt "header=yes"; for $file in file:list("2Bimported", false(), "*.csv") return db:add('DB', $file)
Text Parser Plain text can be imported as well:
GUI Go to Menu Database → New and select "TEXT" in the input format combobox. You can set the following option for parsing text documents in the "Parsing" tab: • Encoding: Choose the appropriate encoding of the text file. • Lines: Activate this option to create a
Command Line Turn on the CSV Parser before parsing documents and set some optional, parser-specific options and a file filter:
SET PARSER text SET PARSEROPT lines=yes SET CREATEFILTER *
XQuery Again, the text parser can also be specified in the prolog of an XQuery expression, and the db:add() or db:replace() function can be used to add the specified source files into the database. The following example query adds all text files to the database DB that are found in the directory 2Bimported and its sub-directories:
declare option db:parser "text"; for $file in file:list("2Bimported", true(), "*.txt") return db:add('DB', $file)
Changelog
Version 7.2 • Enhanced support for TagSoup options.
References
[1] http:/ / download. oracle. com/ javase/ 6/ docs/ api/ javax/ xml/ parsers/ SAXParser. html
[2] http:/ / home. ccil. org/ ~cowan/ XML/ tagsoup/ Commands 37 Commands
This page is linked from the Getting Started Section. This page lists all commands that are supported by BaseX. Commands can be run from the Command Line, the Clients, REST, the input field in the GUI, or some other ways. If the GUI is used, all commands that are triggered by the GUI itself will show up in the Info View. The Permission fields indicate which rights are required by a user to perform a command in the client/server architecture. A shortcut exists for some of the command keywords. For example, you may replace the DATABASE keyword with DB.
Glob Syntax For some commands, the glob syntax can be used to address more than one database or user. Question marks and asterisks can be used to match one or more characters, and commas can be used to separate multiple patterns. Some examples: • AB? addresses all names with the characters AB and one more character. • *AB addresses all names ending with the characters AB. • X*,Y*,Z* addresses all names starting with the characters X, Y, or Z.
Valid Names Both database and user names must follow the same naming constraints. Valid names may contain letters, numbers, underscores and dashes. Names must have at least one character; they also should not be longer than 128 characters, although this is not enforced. A regular expression matching valid names is [-_a-zA-Z0-9]{1,128}.
Commands
ADD
Signature ADD (TO [path]) [input]
Permission WRITE
Summary Adds the files, directory or XML string specified by [input] to the currently opened database at the specified [path]. [input] may either be a single XML document, a directory, a remote URL or a plain XML string. If the path denotes a directory, it needs to be suffixed with a slash (/).
Errors The command fails if no database is opened, if one of the documents to be added is not well-formed, or if it could not be parsed for some other reason.
Examples • ADD input.xml adds the file input.xml to the database. • ADD TO temp/one.xml input.xml adds input.xml to the database and moves it to temp/one.xml. • ADD TO target/ xmldir adds all files from the xmldir directory to the database in the target path. Commands 38
ALTER DATABASE
Signature ALTER DATABASE [name] [newname]
Permission CREATE
Summary Renames the database specified by [name] to [newname]. [newname] must be a valid database name.
Errors The command fails if the target database already exists, if the source database does not exist or is currently locked, or if it could not be renamed for some other reason.
Examples • ALTER DATABASE db tempdb renames the database db into tempdb.
ALTER USER
Signature ALTER USER [name] ([password])
Permission ADMIN
Summary Alters the [password] of the user specified by [name]. The password must be a valid MD5 hash value. If no password is specified in the console mode, it is requested via standard input.
Errors The command fails if the specified user does not exist, or if the password is no valid MD5 hash value.
CHECK
Signature CHECK [input]
Permission CREATE
Summary Opens an existing database for the specified [input] or creates a new instance.
Errors The command fails if the database could beither be opened nor created.
CLOSE
Signature CLOSE
Permission NONE
Summary Closes the currently opened database.
Errors The command fails if the database files could not be closed for some unknown reason.
COPY Commands 39
Signature COPY [name] [newname]
Permission CREATE
Summary Creates a copy of the database specified by [name]. [newname] must be a valid database name.
Errors The command fails if the target database already exists, or if the source database does not exist.
CREATE BACKUP
Signature CREATE BACKUP [name]
Permission CREATE
Summary Creates a zipped backup of the database specified by [name]. The backup file will be suffixed with the current timestamp and stored in the database directory. The Glob syntax can be used to address more than one database.
Errors The command fails if the specified database does not exist, or if it could not be zipped for some other reason.
Examples • BACKUP db creates a zip archive of the database db (e.g. db-2011-04-01-12-27-28.zip) in your database directory.
CREATE DATABASE
Signature CREATE DATABASE [name] ([input])
Permission CREATE
Summary Creates the database [name] with an optional [input]. The input may either be a single XML document, a directory, a remote URL or a plain XML string. [name] must be a valid database name.
Errors The command fails if a database with the specified name is currently used by another process, or if one of the documents to be added is not well-formed or could not be parsed for some other reason.
Examples • CREATE DATABASE input creates an empty database input. • CREATE DATABASE xmark [1] creates the database input with the remote file xmark.xml as initial content. • CREATE DATABASE coll /path/to/input creates the database coll with all documents from the input directory as initial content. • SET INTPARSE false;CREATE DB input input.xml creates a database input, using Java's default XML parser.
CREATE INDEX Updated in Version 7.2: PATH removed as argument; path summary is now updated by OPTIMIZE command Commands 40
Signature CREATE INDEX [TEXT|ATTRIBUTE|FULLTEXT]
Permission WRITE
Summary Creates the specified database index.
Errors The command fails if no database is opened, if the specified index is unknown, or if indexing fails for some other reason.
CREATE EVENT
Signature CREATE EVENT [NAME]
Permission ADMIN
Summary Creates the specified event.
Errors The command fails if event already exists.
CREATE USER
Signature CREATE USER [name] ([password])
Permission ADMIN
Summary Creates a user with the specified [name] and [password]. [name] must be a valid user name. The password must be a valid MD5 hash value. If no password is specified in the console mode, it is requested via standard input.
Errors The command fails if the specified user already exists, or if the password is no valid MD5 hash value.
CS
Signature CS [query]
Permission depends on query
Summary Evaluates the specified [query] and sets the result as new context set.
Errors The command fails if no database is opened, if the specified query is invalid or if it does not return nodes of the currently opened database.
DELETE
Signature DELETE [path]
Permission WRITE
Summary Deletes all documents from the currently opened database that start with the specified [path].
Errors The command fails if no database is opened. Commands 41
DROP BACKUP
Signature DROP BACKUP [name]
Permission CREATE
Summary Drops all backups of the database with the specified [name]. The Glob syntax can be used to address more than one database.
Examples • DROP BACKUP abc* deletes the backups of all databases starting with the characters abc.
DROP DATABASE
Signature DROP DATABASE [name]
Permission CREATE
Summary Drops the database with the specified [name]. The Glob syntax can be used to address more than one database.
Errors The command fails if the specified database does not exist or is currently locked, or if the database could not be deleted for some other reason.
DROP EVENT
Signature DROP EVENT [NAME]
Permission ADMIN
Summary Drops the specified event.
Errors The command fails if the event doesn't exist.
DROP INDEX Updated in Version 7.2: PATH removed as argument; path summary is now always available
Signature DROP INDEX [TEXT|ATTRIBUTE|FULLTEXT]
Permission WRITE
Summary Drops the specified database index.
Errors The command fails if no database is opened, if the specified index is unknown, or if it could not be deleted for some other reason.
DROP USER Commands 42
Signature DROP USER [name] (ON [database]):
Permission ADMIN
Summary Drops the user with the specified [name]. If a [database] is specified, the user is only dropped locally. The Glob syntax can be used to address more than one database or user.
Errors The command fails if admin is specified as user name, if the specified user does not exist or is logged in, or if the optional database could not be opened for modification.
EXIT
Signature EXIT
Permission NONE
Summary Exits the console mode.
EXPORT
Signature EXPORT [path]
Permission CREATE
Summary Exports all documents in the database to the specified [path], using the serializer options specified by the EXPORTER option.
Errors The command fails if no database is opened, if the target path points to a file or is invalid, if the serialization parameters are invalid, or if the documents cannot be serialized for some other reason.
FIND
Signature FIND [keywords]
Permission READ
Summary Builds and runs a query for the specified [keywords]. Keywords can be enclosed in quotes to look for phrases. The following modifiers can be used to further limit search: = looks for exact text nodes ~ looks for approximate hits @= looks for exact attribute values @ looks for attributes
Errors The command fails if no database is opened.
FLUSH Commands 43
Signature FLUSH
Permission WRITE
Summary Explicitly flushes the buffers of the currently opened database to disk. This command is applied if the AUTOFLUSH option has been set to false.
Errors The command fails if no database is opened.
GET
Signature GET [option]
Permission READ
Summary Returns the current value of the Option specified via [key].
Errors The command fails if the specified option is unknown.
GRANT
Signature GRANT [NONE|READ|WRITE|CREATE|ADMIN] (ON [database]) TO [user]
Permission ADMIN
Summary Grants the specified permission to the specified [user]. If a [database] is specified, the permissions are only granted locally. The Glob syntax can be used to address more than one database or user.
Errors The command fails if admin is specified as user name, if the specified user does not exist, or if the optional database could not be opened for modification.
Examples • GRANT READ TO JoeWinson grants READ permission to the user JoeWinson. • GRANT WRITE ON Wiki TO editor* grants WRITE permissions on the Wiki database to all users starting with the characters editor*.
HELP
Signature HELP ([command])
Permission NONE
Summary If [command] is specified, information on the specific command is printed; otherwise, all commands are listed.
Errors The command fails if the specified command is unknown. Commands 44
INFO
Signature INFO
Permission READ
Summary Shows global information.
INFO DATABASE
Signature INFO DATABASE
Permission READ
Summary Shows information on the currently opened database.
Errors The command fails if no database is opened.
INFO INDEX
Signature INFO INDEX ([TEXT|ATTRIBUTE|FULLTEXT|PATH])
Permission READ
Summary Shows information on the existing index structures. The output can be optionally limited to the specified index.
Errors The command fails if no database is opened, or if the specified index is unknown.
INFO STORAGE
Signature INFO STORAGE [start end] | [query]
Permission READ
Summary Shows the internal main table of the currently opened database. An integer range or a query may be specified as argument.
Errors The command fails if no database is opened, or if one of the specified arguments is invalid.
KILL
Signature KILL [target]
Permission ADMIN
Summary Kills sessions of a user or an IP:port combination, specified by [target]. The Glob syntax can be used to address more than one user.
Errors The command fails if a user tried to kill his/her own session. Commands 45
LIST
Signature LIST ([path])
Permission NONE
Summary Lists all available databases, or the documents in a database. [path] is the name of the database, optionally followed by a path to the requested documents.
Errors The command fails if the optional database cannot be opened, or if the existing databases cannot be listed for some other reason.
OPEN
Signature OPEN [path]
Permission READ
Summary Opens the documents in a database. [path] is the name of the database, optionally followed by a path to the requested documents.
Errors The command fails if the specified database cannot be opened for some unknown reason.
OPTIMIZE
Signature OPTIMIZE (ALL)
Permission WRITE
Summary Optimizes the index structures, meta data and statistics of the currently opened database. If the ALL flag is specified, the internal database structures are completely rebuilt; this often leads to a reduction of the total database size.
Errors The command fails if no database is opened, or if the currently opened database is a main-memory instance.
PASSWORD
Signature PASSWORD ([password])
Permission NONE
Summary Changes the [password] of the current user. The password must be a valid MD5 hash value. If no password is specified in the console mode, it is requested via standard input.
Errors The command fails if the password is no valid MD5 hash value.
RENAME Commands 46
Signature RENAME [path] [newpath]
Permission WRITE
Summary Renames all document paths in the currently opened database that start with the specified [path]. The command may be used to either rename single documents or directories.
Errors The command fails if no database is opened, or if the target path is empty.
Examples • RENAME one.xml two.xml renames the document one.xml to two.xml. • RENAME / TOP moves all documents to a TOP root directory.
REPLACE
Signature REPLACE [path] [input]
Permission WRITE
Summary Replaces the documents in the currently opened database, addressed by [path], with the file or XML string specified by [input]. The original file name and path is preserved by the operation.
Errors The command fails if no database is opened, if the specified path points to a database directory, or if the input is not found.
Examples • REPLACE one.xml input.xml replaces the document one.xml with the contents of the file input.xml. • REPLACE top.xml
REPO DELETE
Signature REPO DELETE [name|dir]
Permission CREATE (before Version 7.2: ADMIN)
Summary Deletes the package with name [name] or with directory [dir].
Errors The command fails if the package to be deleted participates in a dependency.
REPO INSTALL
Signature REPO INSTALL [path]
Permission CREATE (before Version 7.2: ADMIN)
Summary Installs the package with path [path].
Errors The command fails in the following cases: • The package to be installed is not a xar file. • The package to be installed does not exist or is already installed. • The package descriptor is with invalid syntax. • The package to be installed depends on a package which is not installed. • The package is not supported by the current version of BaseX. • A component of the package is already installed as part of another package. Commands 47
REPO LIST
Signature REPO LIST
Permission READ (before Version 7.2: ADMIN)
Summary Lists all installed packages.
RESTORE
Signature RESTORE [name]
Permission CREATE
Summary Restores a database with the specified [name]. The name may include the timestamp of the backup file.
Errors The command fails if the specified backup does not exist, if the database to be restored is currently locked, or if it could not be restored for some other reason.
RETRIEVE
Signature RETRIEVE [path] [input]
Permission READ
Summary Retrieves raw data from the specified database [path].
Errors The command fails if no database is opened, if the source path is invalid or if the data cannot not be retrieved for some other reason.
RUN
Signature RUN [file]
Permission depends on query
Summary Runs the query contained in [file] and prints the result.
Errors The command fails if the specified file does not exist, or if the retrieved query is invalid.
SET
Signature SET [option] ([value])
Permission READ
Summary Sets the Option with the specified [key] to a new [value]. If no value is specified, and if the value is boolean, it will be inverted.
Errors The command fails if the specified option is unknown or if the specified value is invalid. Commands 48
SHOW BACKUPS
Signature SHOW BACKUPS
Permission CREATE
Summary Shows all database backups.
SHOW DATABASES
Signature SHOW DATABASES
Permission ADMIN
Summary Shows all databases that are opened in the current server instance.
SHOW SESSIONS
Signature SHOW SESSIONS
Permission ADMIN
Summary Shows all sessions that are connected to the current server instance.
SHOW EVENTS
Signature SHOW EVENTS
Permission ADMIN
Summary Shows all events that have been registered in the database.
SHOW USERS
Signature SHOW USERS (ON [database])
Permission ADMIN
Summary Shows all users that are registered in the database. If a [database] is specified, local users are shown.
Errors The command fails if the optional database could not be opened.
STORE Commands 49
Signature STORE (TO [path]) [input]
Permission WRITE
Summary Stores raw data to the specified [path]. [input] may either be a file reference, a remote URL, or a plain string. If the path denotes a directory, it needs to be suffixed with a slash (/).
Errors The command fails if no database is opened, if the specified resource is not found, if the target path is invalid or if the data cannot not be written for some other reason.
XQUERY
Signature XQUERY [query]
Permission depends on query
Summary Runs the specified [query] and prints the result.
Errors The command fails if the specified query is invalid.
Examples • XQUERY 1 to 10 returns the sequence (1, 2, 3, 4, 5, 6, 7, 8, 9, 10). • SET RUNS 10;XQUERY 1 to 10 runs the query 10 times, returns the result and prints the average execution time. • SET XMLPLAN true;XQUERY 1 to 10 returns the result and prints the query plan as XML.
Changelog
Version 7.2 • Updated: CREATE INDEX, DROP INDEX (PATH argument removed. Path summary is always available now and updated with OPTIMIZE) • Updated: permissions for REPO DELETE, REPO INSTALL and REPO LIST
Version 7.1 • Updated: KILL (killing sessions by specifying IP:port)
Version 7.0 • Added: FLUSH, RETRIEVE, STORE • Updated: ADD: simplified arguments Options 50 Options
This page is linked from the Getting Started Section. The options listed on this page can be requested with the GET command and changed with the SET command. Three data types exist: strings, numbers, and booleans, which can be turned ON and OFF. If options are internally changed by the GUI of BaseX, they will be listed in the Info View.
Main Options The main options are only available from the Standalone Mode and Database Server instances of BaseX, i.e., they cannot be changed by database clients. They are stored in the .basex config file, which is opened by every new BaseX instance:
DBPATH
Signature DBPATH [path]
Default {home}/BaseXData or {home}/data
Summary Points to the directory in which all databases are located. Note: this option can only be changed if no database is currently opened. If the option is changed, existing databases will not be moved to the new location.
REPOPATH
Signature REPOPATH [path]
Default {home}/BaseXRepo
Summary Points to the repository directory, in which all XQuery Packages are located. Note: if the option is changed, BaseX needs to be restarted in order to activate existing packages and avoid side effects.
DEBUG
Signature DEBUG
Default false
Summary Sends internal debug info to STDERR. This option can be turned on to get additional information for development and debugging purposes.
LANG Options 51
Signature LANG [language]
Default English
Summary Specifies the interface language. Currently, seven languages are available: 'English', 'German', 'French', 'Dutch', 'Italian', 'Japanese', and 'Vietnamese'. BaseX needs to be restarted in order to activate the new language.
LANGKEY
Signature LANGKEY
Default false
Summary Prefixes all texts with the internal language keys. This option is helpful if BaseX is translated into another language, and if you want to see where particular texts are displayed. BaseX needs to be restarted in order to activate this option.
Client/Server Architecture
HOST
Signature HOST [host]
Default localhost
Summary This host name is used by the client when connecting to a server.
PORT
Signature PORT [port]
Default 1984
Summary This port is used by the client when connecting to a server.
SERVERPORT
Signature SERVERPORT [port]
Default 1984
Summary This is the port the database server will be listening to.
SERVERHOST Options 52
Signature SERVERHOST [host|ip]
Default empty (wildcard)
Summary This is the host name or ip address the server is bound to. The server will be open to all clients if the option is set to an empty string.
EVENTPORT
Signature EVENTPORT [port]
Default 1985
Summary This port is used by the client to listen for server events. This port will only be bound if a client attaches itself to a database event.
HTTPPORT
Signature HTTPPORT [port]
Default 8984
Summary This is the port the HTTP Server will be listening to.
STOPPORT
Signature STOPPORT [port]
Default 8985
Summary This is the port on which the HTTP Server can be locally closed.
HTTPPATH
Signature HTTPPATH [path]
Default {home}/BaseXHTTP
Summary Points to the HTTP root directory, in which HTML files may be stored, and query files that will be evaluated by the REST service.
PROXYHOST Introduced with Version 7.2:
Signature PROXYHOST [host]
Default
Summary This is the host name of a proxy server. Options 53
PROXYPORT Introduced with Version 7.2:
Signature PROXYPORT [port]
Default 80
Summary This is the port number of a proxy server.
NONPROXYHOSTS Introduced with Version 7.2:
Signature NONPROXYHOSTS [hosts]
Default
Summary This is a list of hosts that should be directly accessed.
PARALLEL
Signature PARALLEL [number]
Default 8
Summary Denotes the maximum allowed number of parallel read transactions.
TIMEOUT
Signature TIMEOUT [seconds]
Default 0 (no timeout)
Summary Specifies the maximum time a read-only transaction may take. If an operation takes longer than the specified timeout, it will be aborted. Write operations will not be affected by this timeout, as this would corrupt the integrity of the database. The timeout is deactivated if the timeout is set to 0. Since Version 7.2, it is ignored for ADMIN operations.
KEEPALIVE
Signature KEEPALIVE [seconds]
Default 0 (no timeout)
Summary Specifies the maximum time a client will be remembered by the server. If there has been no interaction with a client for a longer time than specified by this timeout, it will be disconnected. Running operations will not be affected by this option. The keepalive check is deactivated if the value is set to 0. Options 54
Create Options
CHOP
Signature CHOP
Default true
Summary Chops all leading and trailing whitespaces from text nodes while building a database, and discards empty text nodes. This option often reduces the database size by up to 50%.
INTPARSE
Signature INTPARSE
Default true
Summary Uses the internal XML parser instead of the standard Java XML parser. The internal parser is faster, more fault tolerant and supports common HTML entities out-of-the-box, but it does not support all features needed for parsing DTDs.
DTD
Signature DTD
Default false
Summary Parses referenced DTDs and resolves XML entities. By default, this option is switched to false, as many DTDs are located externally, which may completely block the process of creating new databases. The CATFILE option can be changed to locally resolve DTDs.
CATFILE
Signature CATFILE [path]
Default empty
Summary Specifies a catalog file to locally resolve DTDs; see the entry on Catalog Resolvers for more details.
CREATEFILTER
Signature CREATEFILTER [filter]
Default *.xml
Summary File filter in the Glob Syntax, which is applied whenever new databases are created, or resources are added to a database.
ADDARCHIVES Options 55
Signature ADDARCHIVES
Default true
Summary If this option is set to true, files within archives (ZIP, GZIP, DOCX, etc.) are parsed whenever new database are created or resources are added to a database.
SKIPCORRUPT
Signature SKIPCORRUPT
Default false
Summary Skips corrupt (i.e., not well-formed) files while creating a database or adding new documents. If this option is activated, document updates are slowed down, as all files will be parsed twice. Next, main memory consumption will be higher as parsed files will be cached in main memory.
ADDRAW
Signature ADDRAW
Default false
Summary If this option is activated, and if new resources are added to a database, all files that are not filtered by the CREATEFILTER option will be added as raw files (i.e., in their binary representation).
PARSER
Signature PARSER [type]
Default XML
Summary Defines a parser for importing new files to the database. Currently, 'XML', 'JSON', 'CSV', 'TEXT', 'HTML' are available as parsers. [2] HTML will be parsed as normal XML files if Tagsoup is not found in the classpath.
PARSEROPT
Signature PARSEROPT [options]
Default empty
Summary Defines parser-specific options; see Parsers for more information.
HTMLOPT Introduced with Version 7.2: Options 56
Signature HTMLOPT [options]
Default empty
Summary Allows to specify TagSoup options for HTML parsing; see HTML Parser for more information.
Database Options
MAINMEM
Signature MAINMEM
Default false
Summary If this option is turned on, new databases will be exclusively created in main memory. Most queries will be evaluated faster in main memory mode, but all data is lost if BaseX is shut down. The value of this option will be assigned once to a new database, and cannot be changed after that.
PATHINDEX
Signature PATHINDEX
Default true
Summary Creates a path index whenever a new database is created. A path index helps to optimize location paths; see Indexes for more details.
TEXTINDEX
Signature TEXTINDEX
Default true
Summary Creates a text index whenever a new database is created. A text index speeds up queries with equality comparisons on text nodes; see Indexes for more details.
ATTRINDEX
Signature ATTRINDEX
Default true
Summary Creates an attribute index whenever a new database is created. An attribute index speeds up queries with equality comparisons on attribute values; see Indexes for more details.
FTINDEX Options 57
Signature FTINDEX
Default false
Summary Creates a full-text index whenever a new database is created. A full-text index speeds up queries with full-text expressions; see Indexes for more details.
MAXLEN
Signature MAXLEN
Default 96
Summary Specifies the maximum length of strings that are to be indexed by the name, path, value, and full-text index structures. The value of this option will be assigned once to a new database, and cannot be changed after that.
MAXCATS
Signature MAXCATS
Default 100
Summary Specifies the maximum number of distinct values (categories) that will be remembered for a particular tag/attribute name or unique path. The value of this option will be assigned once to a new database, and cannot be changed after that.
UPDINDEX
Signature UPDINDEX
Default false
Summary If turned on, incremental indexing will be activated: all update operations will also update the value index structures (texts and attribute values). The value of this option will be assigned once to a new database, and cannot be changed after that. The advantage of incremental indexes is that the value index structures will always be up-to-date. The downside is that updates will take a little bit longer.
WRITEBACK
Signature WRITEBACK
Default false
Summary Updates on XML nodes are written back to the input files. Note that no backups of your original files will be created if this option is turned on.
AUTOFLUSH Options 58
Signature AUTOFLUSH
Default true
Summary Flushes database buffers to disk after each update. If this option is set to false, bulk operations (multiple single updates) will be evaluated faster. As a drawback, the chance of data loss increases if the database is not explicitly flushed via the FLUSH command.
MAXSTAT
Signature MAXSTAT [num]
Default 30
Summary Specifies the maximum number of index occurrences printed by the INFO INDEX command.
Full-Text Options
WILDCARDS
Signature WILDCARDS
Default false
Summary If a new full-text index is created, it will be particularly optimized for wildcards expressions. See the page on Full-Texts for more information on XQuery Full Text.
STEMMING
Signature STEMMING
Default false
Summary A new full-text index will stem all tokens and speed up queries on stemmed tokens. The same stemming normalization will be applied to all query tokens that are checked against tokens in this index.
CASESENS
Signature CASESENS
Default false
Summary A new full-text index will preserve the case of all tokens. The same case normalization will be applied to all query tokens that are checked against tokens in this index.
DIACRITICS Options 59
Signature DIACRITICS
Default false
Summary A new full-text index will preserve the diacritics of all tokens. The same diacritics normalization will be applied to all query tokens that are checked against tokens in this index.
LANGUAGE
Signature LANGUAGE [lang]
Default en
Summary A new full-text index will use the given language to normalize all tokens. This option is mainly important if tokens are to be stemmed, or if the tokenization of a language differs from Western languages.
SCORING
Signature SCORING [mode]
Default 0
Summary A new full-text index will pre-calculate full-text scores. This option enables TF/IDF/based scores in full-text queries and increases main memory consumption while indexing. See the Scoring for more information on different scoring types.
STOPWORDS
Signature STOPWORDS [path]
Default empty
Summary A new full-text index will drop tokens that are listed in the specified stopword list. A stopword list may decrease the size of the full text index. A standard stopword list for English texts is provided in the directory etc/stopwords.txt in the official releases.
LSERROR
Signature LSERROR [error]
Default 0
Summary This option specifies the maximum Levenshtein error for the BaseX-specific fuzzy match option. See the page on Full-Texts for more information on fuzzy querying. Options 60
Query Options
QUERYINFO
Signature QUERYINFO
Default false
Summary Prints more information on internal query rewritings, optimizations, and performance.
XQUERY3
Signature XQUERY3
Default true
Summary Enables all XQuery 3.0 features supported by BaseX. If this option is set to false, the XQuery parser will only accept expressions of the XQuery 1.0 specification.
SERIALIZE
Signature SERIALIZE
Default true
Summary Results of XQuery expressions will be serialized if this option is turned on. For debugging purposes and performance measurements, this option can be set to false.
BINDINGS
Signature BINDINGS [vars]
Default empty
Summary Contains external variables to be bound to a query. Variable names and values are separated by equality signs, and multiple variables are delimited by commas. Variables may optionally be introduced with a leading dollar sign. Commas that occur in the value itself are encoded by duplication. If a variable uses a namespace different to the default namespace, it can be specified with the Clark Notation [1] [2] or Expanded QName Notation .
Examples $a=1,$b=2 binds the values 1 and 2 to the variables $a and $b a=1,,2 binds the value 1,2 to the variable $a {URI}a=x or 'URI':a=x binds the value x to the variable $a with the namespace URI.
SERIALIZER Options 61
Signature SERIALIZER [params]
Default empty
Summary Contains parameters for serializing queries; see Serialization for more details. Keys and values are separated by equality signs, and multiple parameters are delimited by commas.
Example encoding=US-ASCII,omit-xml-declaration=no : sets the encoding to US-ASCII and prints the XML declaration.
EXPORTER
Signature EXPORTER [params]
Default empty
Summary Contains parameters for exporting all resources of a database; see Serialization for more details. Keys and values are separated by equality signs, multiple parameters are delimited by commas.
QUERYPATH
Signature QUERYPATH [path]
Default empty
Summary Contains the path (base URI) to the executed query (default: empty). This directory will be used to resolve relative paths to documents, query modules, and other resources addressed in a query.
CACHEQUERY
Signature CACHEQUERY
Default false
Summary Caches the query results before returning them to the client. This option may be set to true if the whole result is needed for further operations (such as is e.g. the case in the GUI of BaseX).
FORCECREATE
Signature FORCECREATE
Default false
Summary By activating this option, the XQuery doc() and collection() functions will create database instances for the addressed input files. Options 62
RUNS
Signature RUNS [num]
Default 1
Summary Specify number of runs a query is executed. Results are printed a single time and evaluation times are averages of all runs.
Serialization Options
XMLPLAN
Signature XMLPLAN
Default false
Summary Prints the execution plan of an XQuery expression in its XML representation.
COMPPLAN
Signature COMPPLAN
Default true
Summary Creates the query plan before or after the compilation step. Query plans might change due to optimizations.
DOTPLAN
Signature DOTPLAN
Default false
[1] Summary Visualizes the execution plan of an XQuery expression with dotty and saves its dot file in the query directory.
DOTCOMPACT
Signature DOTCOMPACT
Default false
Summary Chooses a compact dot representation.
DOTDISPLAY Options 63
Signature DOTDISPLAY
Default true
Summary Visualizes the dot representation after the query execution.
DOTTY
Signature DOTTY [path]
Default dotty
Summary Location of the dotty executable.
Changelog
Version 7.2 • Added: PROXYHOST, PROXYPORT, NONPROXYHOSTS, HTMLOPT • Updated: TIMEOUT: ignore timeout for admin users
Version 7.1 • Added: ADDRAW, MAXLEN, MAXCATS, UPDINDEX • Updated: BINDINGS
Version 7.0 • Added: SERVERHOST, KEEPALIVE, AUTOFLUSH, QUERYPATH
References
[1] http:/ / www. graphviz. org 64
Integration
Integrating oXygen
This tutorial is part of the Getting Started Section. It describes how to access BaseX from the oXygen XML Editor [1]. Currently, there are two variants how to use BaseX in oXygen: • Resources in databases can be opened and modified. • XPath/XQuery expressions can be run by the query processor of BaseX.
Access Database Resources • Start the WebDAV service first, which will allow you to access all resources via the client/server architecture. • Choose File → Open URL....
• Enter the corresponding user name and password (if needed), the URL of the BaseX WebDAV Server, and then click "Browse". Integrating oXygen 65
Perform Queries
Preparations
1. Download a BaseX distribution with libraries included (ZIP, EXE, WAR, DMG): http:/ / basex. org/ download 2. Start oXygen and go to Options → Preferences → Data Sources.
Data Source 1. Add a new Data Source with the New button. 2. Enter "BaseX" as name and choose XQuery API for Java (XQJ) as type. 3. Add the following three JAR files above with the Add Button: basex.jar, basex-api.jar, and xqj-api.jar. The JAR files might include version names. 4. Now press OK, and your Data Source is ready for use.
Connection 1. Now press New in the Connection Panel below. 2. Enter Name "BaseX" and select "BaseX" in the Data Source box. 3. Now press OK, and your connection is ready.
Usage The query execution works as follows: 1. Configure a new transformation scenario in Window → Show View → Transformation Scenarios. 2. Choose the XQuery Transformation tree entry. 3. Press the plus sign to add a new scenario. 4. Enter a Name and an optional XML and XQuery URL (e.g. your query document/file). Integrating oXygen 66
5. Choose "BaseX" as Transformer from the combo box. 6. Press OK, and your scenario is ready. Now you can start the transformation, e.g. by clicking on the red Play button. 7. The results should immediately occur in the result panel.
References
[1] http:/ / www. oxygenxml. com
Integrating Eclipse
This tutorial is part of the Getting Started Section. It demonstates how to perform XPath/XQuery expressions and access databases from the Eclipse IDE [1].
Required Software
1. BaseX Java Archive: http:/ / basex. org/ download/
2. Eclipse 3.6 or higher: http:/ / www. eclipse. org
3. XQuery Development Tools Plugin: http:/ / www. xqdt. org/
Update Site: http:/ / download. eclipse. org/ webtools/ incubator/ repository/ xquery/ milestones/
Setting up You can set up the XQuery interpreter as standalone or client version.
Setting up as Standalone 1. Start Eclipse and go to Preferences → XQuery → Interpreters. 2. Add a new Interpreter with the "Add" button. 3. Enter "BaseX" as name and choose "Java XQuery Engine" as Interpreter type. 4. Point "Interpreter JAR/WAR" to the BaseX JAR archive 5. Choose "org.basex.BaseX" as "Main class"
Setting up as Client 1. Start Eclipse and go to Preferences → XQuery → Interpreters. 2. Add a new Interpreter with the "Add" button. 3. Enter "BaseX" as name and choose "Java XQuery Engine" as Interpreter type. 4. Point "Interpreter JAR/WAR" to the BaseX JAR archive 5. Choose "org.basex.BaseXClient" as "Main class" 6. Set interpreter arguments for your server, port, username and password, e.g. -Uadmin -Padmin -nlocalhost -p1984. Integrating Eclipse 67
Usage The query execution works as follows: 1. Create a new XQuery Project with File → New → XQuery Project. 2. Add a new XQuery Module with File → New → XQuery Module. 3. Edit your XQuery Module and execute it with Run. 4. The results are displayed in the Console window of Eclipse.
References
[1] http:/ / www. eclipse. org 68
Query Features
Querying
Welcome to the Query Portal, which is one of the Main Sections of this documentation. BaseX provides an implementation of the W3 XPath [1] and XQuery [2] languages, which are tightly coupled with the underlying database store. High conformance with the official specifications is one of our main objectives, as the results of the XQuery Test Suite [3] demonstrate. This section contains general information on the query processor and its numerous extensions.
Features • XQuery 3.0: supported features of the upcoming XQuery 3.0 [4] Recommendation • Full-Text: XPath/XQuery Full Text extends the language with powerful retrieval features. • Updates: databases can be modified via the XQuery Update extension • Java Bindings: how to access and call Java code from XQuery • Packaging: embedding of external function modules, based on the EXPath Packaging System [5] • Errors: errors raised by XQuery expressions • Serialization: serialization parameters supported by BaseX
Modules Beside the standard XQuery Functions [6], BaseX offers additional function modules, which are listed in the following table. All modules are statically bound, which means that they need not (but may) be explicitly declared in the query prolog.
Module Description Prefix Namespace URI
Cryptography Cryptographic functions, based on the EXPath crypto http://expath.org/ns/crypto [7] Cryptograhic module.
Database Functions for accessing and updating databases. db http://basex.org/modules/db
File File handling, based on the latest draft of the EXPath file http://expath.org/ns/file [8] File module.
Full-Text Functions for performing full-text operations. ft http://basex.org/modules/ft
HTTP Sending HTTP requests, based on the EXPath HTTP http http://expath.org/ns/http-client [9] module.
Higher-Order Additional higher-order functions that are not in the hof http://basex.org/modules/hof standard libraries.
Index Functions for requesting details on database indexes. index http://basex.org/modules/index Version 7.1
[10] JSON Parsing and serializing JSON documents . json http://basex.org/modules/json
Map Functions for handling maps (key/value pairs). map http://www.w3.org/2005/xpath-functions/map
Math Mathematical operations, extending the W3C Working math http://www.w3.org/2005/xpath-functions/math [6] Draft . Querying 69
Repository Installing, deleting and listing packages. Version 7.1 repo http://basex.org/modules/repo
SQL JDBC bridge to access relational databases. sql http://basex.org/modules/sql
Utility Utility functions, used for data conversions, profiling util http://basex.org/modules/util and dynamic evaluation.
XSLT Stylesheet transformations, based on Java’s and xslt http://basex.org/modules/xslt Saxon’s XSLT processor.
[11] ZIP ZIP functionality, based on the EXPath ZIP zip http://expath.org/ns/zip module.
References
[1] http:/ / www. w3. org/ TR/ xpath-30/
[2] http:/ / www. w3. org/ TR/ xquery-30
[3] http:/ / dev. w3. org/ 2006/ xquery-test-suite/ PublicPagesStagingArea/ XQTSReportSimple_XQTS_1_0_2. html
[4] http:/ / www. w3. org/ TR/ xquery-30/
[5] http:/ / expath. org/ modules/ pkg/
[6] http:/ / www. w3. org/ TR/ xpath-functions-30/
[7] http:/ / expath. org/ spec/ crypto
[8] http:/ / expath. org/ spec/ file
[9] http:/ / expath. org/ spec/ http-client
[10] http:/ / www. json. org
[11] http:/ / expath. org/ spec/ zip
XQuery 3.0
This article is part of the Query Portal. It summarizes features of the upcoming XQuery 3.0 [4] and XPath 3.0 [1] Recommendations that have already been implemented in BaseX.
Group By FLWOR expressions have been extended to include the group by [1] clause, which is well-established among relational database systems. group by can be used to apply value-based partitioning to query results: Example:
for $ppl in doc('xmark')//people/person let $ic := $ppl/profile/@income let $income := if($ic < 30000) then "challenge" else if($ic >= 30000 and $ic < 100000) then "standard" else if($ic >= 100000) then "preferred" else "na" group by $income order by $income return element { $income } { count($ppl) } XQuery 3.0 70
This query is a rewrite of Query #20 [2] contained in the XMark Benchmark Suite [3] to use group by. The query partitions the customers based on their income. Result:
In contrast to the relational GROUP BY statement, the XQuery counterpart concatenates the values of all non-grouping variables that belong to a specific group. In the context of our example, all nodes in //people/person that belong to the "preferred" partition are concatenated in $ppl after grouping has finished. You can see this effect by changing the return statement to:
... return element { $income } { $ppl }
Result:
Try/Catch The try/catch [4] construct can be used to handle errors at runtime: Example:
try { 1 + '2' } catch XPTY0004 { 'Typing error: ' || $err:description } catch * { 'Error [' || $err:code || ']: ' || $err:description }
Result: Typing error: '+' operator: number expected, xs:string found. XQuery 3.0 71
Switch The switch [5] statement is available in many other programming languages. It chooses one of several expressions to evaluate based on its input value. Example:
for $fruit in ("Apple", "Pear", "Peach") return switch ($fruit) case "Apple" return "red" case "Pear" return "green" case "Peach" return "pink" default return "unknown"
Result: red green pink
Function Items One of the most distinguishing features added in XQuery 3.0 are function items, also known as lambdas or lambda functions. They make it possible to abstract over functions and thus writing more modular code. Examples: Function items can be obtained in three different ways: • Declaring a new inline function:
let $f := function($x, $y) { $x + $y } return $f(17, 25)
Result: 42 • Getting the function item of an existing (built-in oder user-defined) XQuery function. The arity (number of arguments) has to be specified as there can be more than one function with the same name:
let $f := math:pow#2 return $f(5, 2)
Result: 25 • Partially applying another function or function item. This is done by supplying only some of the required arguments, writing the placeholder ? in the positions of the arguments left out. The produced function item has one argument for every placeholder.
let $f := fn:substring(?, 1, 3) return ( $f('foo123'), $f('bar456') )
Result: foo bar Function items can also be passed as arguments to and returned as results from functions. These so-called Higher-Order Functions like fn:map and fn:fold-left are discussed in more depth on their own Wiki page. XQuery 3.0 72
Expanded QNames Updated with Version 7.2: A QName can now be directly prefixed with the letter "Q" and a namespace URI in the Clark Notation [1]. Examples: • Q{http://www.w3.org/2005/xpath-functions/math}pi() returns the number π • Q{java:java.io.FileOutputStream}new("output.txt") creates a new Java file output stream Before Version 7.2, and in older versions of the XQuery 3.0 specification, the prefixed namespace URI was quoted: • "http://www.w3.org/2005/xpath-functions/math":pi() • "java:java.io.FileOutputStream":new("output")
Namespace Constructors New namespaces can now be created via so-called 'Computed Namespace Constructors'.
element node { namespace pref { 'http://url.org/' } }
String Concatenations Two vertical bars || (also names pipe characters) can be used to concatenate strings. This operator is a shortcut for the ft:contains() function.
'Hello' || ' ' || 'Universe'
External Variables Default values can now be attached to external variable declarations. This way, an expression can also be evaluated if its external variables have not been bound to a new value.
declare variable $user external := "admin"; "User:", $user
Serialization Serialization parameters can now be defined within XQuery expressions. Parameters are placed in the query prolog and need to be specified as option declarations, using the output prefix. Example:
declare option output:omit-xml-declaration "no"; declare option output:method "xhtml";
Result: XQuery 3.0 73
Context Item The context item can now be specified in the prolog of an XQuery expressions: Example:
declare context item := document {
for $t in .//text() return string-length($t)
Result: 5 5
Annotations Introduced with Version 7.2: XQuery 3.0 introduces annotations to declare properties associated with functions and variables. For instance, a function may be declared %public, %private, or %updating. Example:
declare %private function local:max($x1, $x2) { if($x1 > $x2) then $x1 else $x2 };
local:max(2, 3)
Functions BaseX supports all functions that have been added in Version 3.0 of the XQuery Functions and Operators [6] Working Draft. The new functions are listed below: • math:pi(), math:sin(), and many others (see Math Module) • fn:analyze-string() • fn:available-environment-variables() • fn:element-with-id() • fn:environment-variable() • fn:filter() • fn:fold-left() • fn:fold-right() • fn:format-date() • fn:format-dateTime() • fn:format-integer() • fn:format-number() • fn:format-time() • fn:function-arity() • fn:function-lookup() • fn:function-name() XQuery 3.0 74
• fn:generate-id() • fn:has-children() • fn:head() • fn:innermost() • fn:map() • fn:map-pairs() • fn:outermost() • fn:parse-xml() • fn:path() • fn:serialize() • fn:tail() • fn:unparsed-text() • fn:unparsed-text-available() • fn:unparsed-text-lines() • fn:uri-collection() New signatures have been added for the following functions: • fn:document-uri() with 0 arguments • fn:string-join() with 1 argument • fn:node-name() with 0 arguments • fn:round() with 2 arguments • fn:data() with 0 arguments
Changelog
Version 7.2 • Added: Annotations • Updated: EQName syntax
Version 7.1 • Added: Expanded QNames, Computed Namespace Constructor
Version 7.0 • String Concatenator
References
[1] http:/ / www. w3. org/ TR/ xquery-30/ #id-group-by
[2] http:/ / www. ins. cwi. nl/ projects/ xmark/ Assets/ xmlquery. txt
[3] http:/ / www. ins. cwi. nl/ projects/ xmark
[4] http:/ / www. w3. org/ TR/ xquery-30/ #id-try-catch
[5] http:/ / www. w3. org/ TR/ xquery-30/ #id-switch Higher-Order Functions 75 Higher-Order Functions
This page talks about higher-order functions introduced with XQuery 3.0. The BaseX-specific hof module containing some more very usful functions can be found at Higher-Order Functions Module.
Function Items Probably the most important new feature in XQuery 3.0 are function items, i. e. items that act as functions, but can also be passed to and from other functions and expressions, making functions first-class citizens of the language. The XQuery 3.0 page goes into details on how function items can be obtained.
Function Types Like every XQuery item, function items have a sequence type. It can be used to specify the arity (number of arguments the function takes) and the argument and result types. The most general function type is function(*). It's the type of all function items. The following query for example goes through a list of XQuery items and, if it is a function item, prints its arity:
for $item in (1, 'foo', fn:concat#3, function($a) { 42 * $a }) where $item instance of function(*) return fn:function-arity($item)
Result: 3 1 The notation for specifying argument and return types is quite intuitive, as it closely resembles the function declaration. The XQuery function
declare function local:char-at( $str as xs:string, $pos as xs:integer ) as xs:string { fn:substring($str, $pos, 1) };
for example has the type function(xs:string, xs:integer) as xs:string. It isn't possible to specify only the argument and not the result type or the other way round. A good place-holder to use when no restriction is wanted is item()*, as it matches any XQuery value. Function types can also be nested. As an example we take local:on-sequences, which takes a function defined on single items and makes it work on sequences as well:
declare function local:on-sequences( $f as function(item()) as item()* ) as function(item()*) as item()* { fn:map($f, ?) };
We'll see later how fn:map(...) works. The type of local:on-sequences(...) on the other hand is easily constructed, if a bit long: function(function(item()) as item()*) as function(item()*) as item()*. Higher-Order Functions 76
Higher-Order Functions A higher-order function is a function that takes other functions as arguments and/or returns them as results. fn:map and local:on-sequences from the last chapter are nice examples. With the help of higher-order functions, one can extract common patterns of behaviour and abstract them into a library function.
Higher-Order Functions on Sequences Some usage patterns on sequences are so common that the higher-order functions describing them are in the XQuery standard libraries. They are listed here, together with their possible XQuery implementation and some motivating examples.
fn:map($f, $seq)
Signatures fn:map($f as function(item()) as item()*, $seq as item()*) as item()*
Summary Applies the function item $f to every element of the sequence $seq and returns all of the results as a sequence.
Examples • Squaring all numbers from 1 to 10:
fn:map(math:pow(?, 2), 1 to 10)
Result: 1 4 9 16 25 36 49 64 81 100 • Applying a list of functions to a string:
let $fs := ( fn:upper-case#1, fn:substring(?, 4), fn:string-length#1 ) return fn:map(function($f) { $f('foobar') }, $fs)
Result: FOOBAR bar 6
XQuery 1.0 declare function local:map( $f as function(item()) as item()*, $seq as item()* ) as item()* { for $x in $seq return $f($seq) };
fn:filter($pred, $seq) Higher-Order Functions 77
Signatures fn:filter($pred as function(item()) as xs:boolean, $seq as item()*) as item()*
Summary Applies the boolean predicate $pred to all elements of the sequence $seq, returning those for which it returns true().
Examples • All even integers until 10:
fn:filter(function($x) { $x mod 2 eq 0 }, 1 to 10)
Result: 2 4 6 8 10 • Strings that start with an upper-case letter:
let $first-upper := function($str) { let $first := fn:substring($str, 1, 1) return $first eq fn:upper-case($first) } return fn:filter($first-upper, ('FooBar', 'foo', 'BAR'))
Result: FooBar BAR • Inefficient prime number generator:
let $is-prime := function($x) { $x gt 1 and (every $y in 2 to ($x - 1) satisfies $x mod $y ne 0) } return filter($is-prime, 1 to 20)
Result: 2 3 5 7 11 13 17 19
Note fn:filter can be easily implemented with fn:map:
declare function local:filter($pred, $seq) { map( function($x) { if($pred($x)) then $x else () }, $seq ) };
XQuery 1.0 declare function local:filter( $pred as function(item()) as xs:boolean, $seq as item()* ) as item()* { $seq[$pred(.)] };
fn:map-pairs($f, $seq1, $seq2)
Signatures fn:map-pairs($f as function(item(), item()) as item()*, $seq1 as item()*, $seq2 as item()*) as item()*
Summary zips the elements from the two sequences $seq1 and $seq2 together with the function $f. It stops after the shorter sequence ends. Higher-Order Functions 78
Examples • Adding one to the numbers at odd positions:
fn:map-pairs( function($a, $b) { $a + $b }, fn:map(function($x) { $x mod 2 }, 1 to 10), (1, 1, 1, 1, 1) )
Result: 2 1 2 1 2 • Line numbering:
let $number-lines := function($str) { fn:string-join( fn:map-pairs( concat(?, ': ', ?), 1 to 1000, tokenize($str, '\r?\n|\r') ), ' ' ) } return $number-lines( 'hello world, how are you?' )
Result:
1: hello world, 2: how are you?
• Checking if a sequence is sorted:
let $is-sorted := function($seq) { every $b in fn:map-pairs( function($a, $b) { $a le $b }, $seq, fn:tail($seq) ) satisfies $b } return ( $is-sorted(1 to 10), $is-sorted((1, 2, 42, 4, 5)) )
Result: true false
XQuery declare function local:map-pairs( 1.0 $f as function(item(), item()) as item()*, $seq1 as item()*, $seq2 as item()* ) as item()* { for $pos in 1 to min(length($seq1), length($seq2)) return $f($seq1[$pos], $seq2[$pos]) }; Higher-Order Functions 79
Folds A fold, also called reduce or accumulate in other languages, is a very basic higher-order function on sequences. It starts from a seed value and incrementally builds up a result, consuming one element from the sequence at a time and combining it with the aggregate with a user-defined function. Folds are one solution to the problem of not having state in functional programs. Solving a problem in imperative programming languages often means repeatedly updating the value of variables, which isn't allowed in functional languages. Calculating the product of a sequence of integers for example is easy in Java:
public int product(int[] seq) { int result = 1; for(int i : seq) { result = result * i; } return result; }
Nice and efficient implementations using folds will be given below. The linear folds on sequences come in two flavours. They differ in the direction in which they traverse the sequence:
fn:fold-left($f, $seed, $seq)
Signatures fn:fold-left($f as function(item()*, item()) as item()*, $seed as item()*, $seq as item()*) as item()*
Summary The left fold traverses the sequence from the left. The query fn:fold-left($f, 0, 1 to 5) for example would be evaluated as:
$f($f($f($f($f(0, 1), 2), 3), 4), 5) Higher-Order Functions 80
Examples • Product of a sequence of integers:
let $product := fn:fold-left( function($result, $i) { $result * $i }, 1, ? ) return $product(1 to 5)
Result: 120 • Illustrating the evaluation order:
fn:fold-left( concat('$f(', ?, ', ', ?, ')'), '$seed', 1 to 5 )
Result: $f($f($f($f($f($seed, 1), 2), 3), 4), 5) • Building a decimal number from digits:
let $from-digits := fold-left( function($n, $d) { 10 * $n + $d }, 0, ? ) return ( $from-digits(1 to 5), $from-digits((4, 2)) )
Result: 12345 42
XQuery As folds are more general than FLWOR expressions, the implementation isn't as concise as the former ones: 1.0 declare function local:fold-left( $f as function(item()*, item()) as item()*, $seed as item()*, $seq as item()* ) as item()* { if(empty($seq)) then $seed else local:fold-left( $f, $f($seed, fn:head($seq)), fn:tail($seq) ) };
fn:fold-right($f, $seed, $seq) Higher-Order Functions 81
Signatures fn:fold-right($f as function(item(), item()*) as item()*, $seed as item()*, $seq as item()*) as item()*
Summary The right fold fn:fold-right($f, $seed, $seq) traverses the from the right. The query fn:fold-right($f, 0, 1 to 5) for example would be evaluated as:
$f(1, $f(2, $f(3, $f(4, $f(5, 0)))))
Examples • Product of a sequence of integers:
let $product := fn:fold-right( function($i, $result) { $result * $i }, 1, ? ) return $product(1 to 5)
Result: 120 • Illustrating the evaluation order:
fn:fold-right( concat('$f(', ?, ', ', ?, ')'), '$seed', 1 to 5 )
Result: $f(1, $f(2, $f(3, $f(4, $f(5, $seed))))) • Reversing a sequence of items:
let $reverse := fn:fold-right( function($item, $rev) { $rev, $item }, (), ? ) return $reverse(1 to 10)
Result: 10 9 8 7 6 5 4 3 2 1
XQuery declare function local:fold-right( 1.0 $f as function(item(), item()*) as item()*, $seed as item()*, $seq as item()* ) as item()* { if(empty($seq)) then $seed else $f( fn:head($seq), local:fold-right($f, $seed, tail($seq)) ) };
Note that the order of the arguments of $f are inverted compared to that in fn:fold-left(...). Full-Text 82 Full-Text
This article is part of the Query Portal. It summarizes the Full-Text features of BaseX. Full-text retrieval is an essential query feature for working with XML documents, and BaseX was the first query processor that fully supported the W3C XQuery Full Text 1.0 [1] Recommendation. This page lists some singularities and extensions of the BaseX implementation.
Query Evaluation BaseX offers different evaluation strategies for XQFT queries, the choice of which depends on the input data and the existence of a full text index. The query compiler tries to optimize and speed up queries by applying a full text index structure whenever possible and useful. Three evaluation strategies are available: the standard sequential database scan, a full-text index based evaluation and a hybrid one, combining both strategies (see "XQuery Full Text implementation in BaseX" [2]). Query optimization and selection of the most efficient evaluation strategy is done in a full-fledged automatic manner. The output of the query optimizer indicates which evaluation plan is chosen for a specific query. It can be inspected by activating verbose querying (Command: SET VERBOSE ON) or opening the Query Info in the GUI. The message Applying full-text index suggests that the full-text index is applied to speed up query evaluation. A second message Removing path with no index results indicates that the index does not yield any results for the specified term and is thus skipped. If index optimizations are missing, it sometimes helps to give the compiler a second chance and try different rewritings of the same query.
Options The available full-text index can handle various combinations of the match options defined in the XQuery Full Text Recommendation. By default, most options are disabled. The GUI dialogs for creating new databases or displaying the database properties contain a tab for choosing between all available options. On the command-line, the SET command can be used to activate full-text indexing or creating a full-text index for existing databases: • SET FTINDEX true; CREATE DB input.xml • CREATE INDEX fulltext The following indexing options are available: • Language: see below for more details (SET LANGUAGE EN) • Support Wildcards: a trie-based index can be applied to support wildcard searches (SET WILDCARDS true) • Stemming: tokens are stemmed with the Porter Stemmer before being indexed (SET STEMMING true) • Case Sensitive: tokens are indexed in case-sensitive mode (SET CASESENS true) • Diacritics: diacritics are indexed as well (SET DIACRITICS true) • TF/IDF Scoring: TF/IDF-based scoring values are calculated and stored in the index (SET SCORING 0/1/2; details see below) • Stopword List: a stop word list can be defined to reduce the number of indexed tokens (SET STOPWORDS [filename]) Full-Text 83
Languages The chosen language determines how the input text will be tokenized and stemmed. The basic code base and jar file of BaseX comes with built-in support for English and German. More languages are supported if the following libraries are found in the classpath (Version 7.0): • lucene-stemmers-3.4.0.jar [3]: includes Snowball and Lucene stemmers and extends language support to the following languages: Arabic, Bulgarian, Catalan, Czech, Danish, Dutch, Finnish, French, Hindi, Hungarian, Italian, Latvian, Lithuanian, Norwegian, Portuguese, Romanian, Russian, Spanish, Swedish, Turkish. • igo-0.4.3.jar [4]: An additional article explains how Igo can be integrated, and how Japanese texts are tokenized and stemmed. The JAR files can also be found in the zip and exe distribution files of BaseX. The following two queries, which both return true, demonstrate that stemming depends on the selected language:
"Indexing" contains text "index" using stemming, "häuser" contains text "haus" using stemming using language "de"
Scoring The XQuery Full Text Recommendation allows for the usage of scoring models and values within queries, with scoring being completely implementation defined. BaseX offers an efficient internal scoring model which can be easily extended to different application scenarios. Additionally, BaseX allows to store scoring values within the full-text index structure (demanding additional time and memory). Three scoring types are currently available, which can be adjusted with the SCORING property (Default: SET SCORING 0): • 0: This algorithm yields the best results for general-purpose use cases. It calculates the scoring value out of the length of a term and its frequency in a single text node. This algorithm is also applied if no index exists, or if the index cannot be applied in a query. • 1: Standard TF/IDF algorithm, which treats document nodes as document units. • 2: Each text node is treated as a document unit in the TF/IDF algorithm. This variant is an alternative for type 1, if the database contains large, few XML files.
Querying Using Thesaurus BaseX supports full-text queries using thesauri, but it does not provide a default thesaurus. This is why query such as
'computers' contains text 'hardware' using thesaurus default
will return false. However, if the thesaurus is specified, then the result will be true
'computers' contains text 'hardware' using thesaurus at 'XQFTTS_1_0_4/TestSources/usability2.xml'
The format of the thesaurus files must be the same as the format of the thesauri provided by the XQuery and XPath Full Text 1.0 Test Suite [5]. It is an XML with structure defined by an XSD Schema [6]. Full-Text 84
Fuzzy Querying In addition to the official recommendation, BaseX supports fuzzy querying. The XQFT grammar was enhanced by the FTMatchOption using fuzzy to allow for approximate searches in full texts. By default, the standard full-text index already supports the efficient execution of fuzzy searches. Document 'doc.xml':
Command: CREATE DB doc.xml; CREATE INDEX fullext Query:
//a[text() contains text 'house' using fuzzy]
Result:
Fuzzy search is based on the Levenshtein distance. The maximum number of allowed errors is calculated by dividing the token length of a specified query term by 4, preserving a minimum of 1 errors. A static error distance can be set by adjusting the LSERROR property (default: SET LSERROR 0). The query above yields two results as there is no error between the query term "foo" and the text node "foo bar", and one error between "foo" and "foa bar".
Functions Some additional Full-Text Functions have been added to BaseX to extend the official language recommendation with useful features, such as explicitly requesting the score value of an item, marking the hits of a full-text request, or directly accessing the full-text index with the default index options.
Error Messages Along with the Update Facility, a number of new error codes and messages have been added to the specification and BaseX. All errors are listed in the XQuery Errors overview.
References
[1] http:/ / www. w3. org/ TR/ xpath-full-text-10/
[2] http:/ / www. inf. uni-konstanz. de/ gk/ pubsys/ publishedFiles/ GrGaHo09. pdf
[3] http:/ / files. basex. org/ maven/ org/ apache/ lucene-stemmers/ 3. 4. 0/ lucene-stemmers-3. 4. 0. jar
[4] http:/ / en. sourceforge. jp/ projects/ igo/ releases/
[5] http:/ / dev. w3. org/ 2007/ xpath-full-text-10-test-suite
[6] http:/ / dev. w3. org/ cvsweb/ ~checkout~/ 2007/ xpath-full-text-10-test-suite/ TestSuiteStagingArea/ TestSources/ thesaurus. xsd?rev=1. 3;content-type=application%2Fxml Full-Text/Japanese 85 Full-Text/Japanese
This article is linked from the Full-Text page. It gives some insight into the implementation of the full-text features for Japanese text corpora. The Japanese version is also available as PDF [1]. Thank you to Toshio HIRAI [2] for integrating the lexer in BaseX!
Introduction The lexical analysis of Japanese documents is performed by Igo [3]. Igo is a morphological analyser, and some of the advantages and reasons for using Igo are: • compatible with the results of a prominent morphological analyzer "MeCab" • it can use the dictionary distributed by the Project MeCab • the morphological analyzer is implemented in Java and is relatively fast Japanese tokenization will be activated in BaseX if Igo is found in the classpath. igo-0.4.3.jar [4] of Igo is currently included in all distributions of BaseX. In addition to the library, one of the following dictionary files must either be unzipped into the current directory, or into the etc sub-directory of the project’s Home Directory:
• IPA Dictionary: http:/ / files. basex. org/ etc/ ipadic. zip
• NAIST Dictionary: http:/ / files. basex. org/ etc/ naistdic. zip
Lexical Analysis The example sentence "私は本を書きました。(I wrote a book.)" is analyzed as follows.
私は本を書きました。
私 名 詞,代 名 詞,一 般,*,*,*,私,ワタシ,ワタシ
は 助 詞,係 助 詞,*,*,*,*,は,ハ,ワ
本 名 詞,一 般,*,*,*,*,本,ホン,ホン
を 助 詞,格 助 詞,一 般,*,*,*,を,ヲ,ヲ
書き 動 詞,自 立,*,*,五 段・カ行イ音 便,連 用 形,書く,カキ,カキ
まし 助 動 詞,*,*,*,特 殊・マス,連 用 形,ます,マシ,マシ
た 助 動 詞,*,*,*,特 殊・タ,基 本 形,た,タ,タ
。 記 号,句 点,*,*,*,*,。,。,。
The element of the decomposed part is called "Surface", the content analysis is called "Morpheme". The Morpheme component is built as follows:
品 詞,品 詞 細 分 類1,品 詞 細 分 類2,品 詞 細 分 類3,活 用 形,活 用 型,原 形,読み,発 音
(POS, subtyping POS 1, subtyping POS 2, subtyping POS 3, inflections, use type, prototype, reading, pronunciation)
Of these, the surface is used as a token. Also, The contents of analysis of a morpheme are used in indexing and stemming. Full-Text/Japanese 86
Parsing During indexing and parsing, the input strings are split into single tokens. In order to reduce the index size and speed up search, the following word classes have been intentionally excluded: • Mark • Filler • Postpositional particle • Auxiliary verb Thus, in the example above, the "私", "本", "書き" will be passed to the indexer for each token.
Token Processing "Fullwidth" and "Halfwidth" (which is defined by East Asian Width Properties [4]) are not distinguished (this is the so-called ZENKAKU/HANKAKU problem). For example, ＸＭＬ and XML will be treated as the same word. If documents are hybrid, i.e. written in multiple languages, this is also helpful for some other options of the XQuery Full Text Specification, such as the Case [5] or the Diacritics [6] Option.
Stemming Stemming in Japanese means to analyze the results of morphological analysis ("verbs" and "adjectives") that are processed using the "prototype". If the stemming option is enabled, for example, the two statements "私は本を書いた (I wrote the book)" and "私は本を書く (I write the book)" can be led back to the same prototype by analyzing their verb:
書く 動 詞,自 立,*,*,五 段・カ行イ音 便,基 本 形,[書く],カク,カク
書い 動 詞,自 立,*,*,五 段・カ行イ音 便,連 用タ接 続,[書く],カイ,カイ
た 助 動 詞,*,*,*,特 殊・タ,基 本 形,た,タ,タ
Because the "auxiliary verb" is always excluded from the tokens, there is no need to consider its use. Therefore, the same result (true) is returned for the following two types of queries:
'私は本を書いた' contains text '書く' using stemming using language 'ja' '私は本を書く' contains text '書いた' using stemming using language 'ja'
Wildcards
The Wildcard option in XQuery Full-Text is available for Japanese as well. The following example is based on '芥
川 龍 之 介(AKUTAGAWA, Ryunosuke)', a prominent Japanese writer, the first name of whom is often spelled as
"竜 之 介". The following two queries both return true:
'芥 川 龍 之 介' contains text '.之 介' using wildcards using language 'ja'
'芥 川 竜 之 介' contains text '.之 介' using wildcards using language 'ja'
However, there is a special case that requires attention. The following query will yield false:
'芥 川 龍 之 介' contains text '芥 川.之 介' using wildcards using language 'ja'
This is because the next word boundary metacharacters cannot be determined in the query. In this case, you may insert an additional whitespaces as word boundary:
'芥 川 龍 之 介' contains text '芥 川 .之 介' using wildcards using language 'ja' Full-Text/Japanese 87
As an alternative, you may modify the query as follows:
'芥 川 龍 之 介' contains text '芥 川' ftand '.之 介' using wildcards using language 'ja'
References
[1] http:/ / files. basex. org/ etc/ ja-ft. pdf
[2] http:/ / blog. infinite. jp
[3] http:/ / igo. sourceforge. jp/
[4] http:/ / unicode. org/ Public/ UNIDATA/ EastAsianWidth. txt
[5] http:/ / www. w3. org/ TR/ xpath-full-text-10/ #ftcaseoption
[6] http:/ / www. w3. org/ TR/ xpath-full-text-10/ #ftdiacriticsoption
XQuery Update
This article is part of the Query Portal. It summarizes the update features of BaseX. BaseX offers a complete implementation of the XQuery Update Facility (XQUF) [1]. This article aims to provide a very quick and basic introduction to the XQUF. First, some examples for update expressions are given. After that, a few problems are addressed that frequently arise due to the nature of the language. These are stated in the Concepts paragraph.
New Functionality
Updating Expressions There are five new expressions to modify data. While insert, delete, rename and replace basically explain themselves, the transform expression is different. Modified nodes are copied in advance and the original databases remain untouched. An expression consists of a target node (the node we want to alter) and additional information like insertion nodes, a QName, etc. which depends on the type of expression. Optional modifiers are available for some of them. You can find a few examples and additional information below.
insert insert node (attribute { 'a' } { 5 }, 'text',
Insert enables you to insert a sequence of nodes into a single target node. Several modifiers are available to specify the exact insert location: insert into as first/as last, insert before/after and insert into. Note: in most cases, as last and after will be evaluated faster than as first and before!
delete delete node //node
The example query deletes all
The target element is replaced by the DOM node . You can also replace the value of a node or its descendants by using the modifier value of.
replace value of node /n with 'newValue'
All descendants of /n are deleted and the given text is inserted as the only child. Note that the result of the insert sequence is either a single text node or an empty sequence. If the insert sequence is empty, all descendants of the target are deleted. Consequently, replacing the value of a node leaves the target with either a single text node or no descendants at all.
rename for $n in //node return rename node $n as 'renamedNode'
All node elements are renamed. An iterative approach helps to modify multiple nodes within a single statement. Nodes on the descendant- or attribute-axis of the target are not affected. This has to be done explicitly as well.
Non-Updating Expressions
transform copy $c := doc('example.xml')//node[@id = 1] modify rename node $c as 'copyOfNode' return $c
The node element with @id=1 is copied and subsequently assigned a new QName using the rename expression. Note that the transform expression is the only expression which returns an actual XDM instance as a result. You can therefore use it to modify results and especially DOM nodes. This is an issue beginners are often confronted with. More on this topic can be found in the XQUF Concepts section. The following example demonstrates a common use case: Query:
copy $c :=
Result:
The
copy $c := (db:open('example')//entry)[1] ...
In this case, the original database node remains untouched as well, as all updates are performed on the node copy.
Functions
fn:put() FN:put() is also part of the XQUF and enables the user to serialize XDM instances to secondary storage. It is executed at the end of a snapshot. Serialized documents therefore reflect all changes made effective during a query.
XQUF Concepts There are a few specialties around XQuery Update that you should know about. In addition to the simple expression, the XQUF adds the updating expression as a new type of expression. An updating expression returns only a Pending Update List (PUL) as a result which is subsequently applied to addressed databases and DOM nodes. A simple expression cannot perform any permanent changes and returns an empty or non-empty sequence.
Pending Update List The most important thing to keep in mind when using XQuery Update is the Pending Update List (PUL). Updating statements are not executed immediately, but are first collected as update primitives within a set-like structure, the PUL. At the end of a query, all update primitives on this list are applied in a strict order after some compatibility tests. If a conflict exists, an error message is returned and all accessed databases remain untouched (atomicity). For the user this means updates are only visible after the end of a snapshot. If we have the document:
... and perform the following query:
insert node into /doc, for $n in /doc/child::node() return rename node $n as 'justRenamed'
The document looks like this:
Despite explicitly renaming all child nodes of
Returning Results It is not possible to mix different types of expressions in a query result. The outermost expression of a query must either be a collection of updating or non-updating expressions. Generally there is no way to perform any updating queries and return a result at the same time, as you cannot access your own changes during a single query. Regarding database nodes, you can update your nodes within the first query and access modifications in subsequent queries. But trying to modify and return a DOM node within the same snapshot is another story. As changes on DOM nodes are non-persistent, you cannot access them in a subsequent query. This is where the transform expression comes into play.
Function Declaration To use updating expressions within a function, the 'updating' flag has to be added to the function declaration. A correct declaration of a function that contains updating expressions (or one that calls updating functions) looks like this:
declare updating function { ... }
Effects on your documents In BaseX, all updates are performed on database nodes. Update operations thus never affect the original input file. You can, however, use the EXPORT command or the fn:put() function to create an updated XML file. If the database option WRITEBACK is turned on, changes in your database are propagated back to the original input file. Make sure you back up your data in advance, as this approach modifies the underlying XML file.
Indexes As BaseX mainly aims for efficiency, the maintenance of indexes is left to the user. This requires the user to call the OPTIMIZE command after all update operations have been executed: multiple update operations can be performed much faster this way, and the database meta data is only updated and regenerated once in the updating process. Since Version 7.1, incremental index updates are supported for text nodes and attribute values. The UPDINDEX database option can be turned on for a particular database to trigger index updates.
Error Messages Along with the Update Facility, a number of new error codes and messages have been added to the specification and BaseX. All errors are listed in the XQuery Errors overview.
References
[1] http:/ / www. w3. org/ TR/ xquery-update-10/ Java Bindings 91 Java Bindings
This article is part of the Query Portal. It shows how to call Java code from XQuery. The Java Binding query feature is an extensibility mechanism which enables developers to directly access Java variables and execute code from XQuery. Java classes are identified by namespaces; the namespace URI must be of the form java:fully.qualified.ClassName. The following example uses Java’s Math class and returns the cosine of an angle. The cos() method can be directly called, as it is a static method:
declare namespace math = "java:java.lang.Math"; math:cos(xs:double(0))
The next example writes 256 bytes to the file output.txt. First, a new FileWriter instance is created: by calling the new() function, the class constructor is invoked. Instance methods are called by passing on the resulting Java object as first argument:
declare namespace fw = "java:java.io.FileWriter"; let $file := fw:new('output.txt') return ( for $i in 0 to 255 return fw:write($file, xs:int($i)), fw:close($file) )
In general, we recommend everyone to use XQuery expressions and functions whenever possible, as Java code cannot be pre-compiled, and will often be evaluated slower than optimized XQuery code. Next, Java code can only be executed with admin permissions. Packaging 92 Packaging
This article is part of the Query Portal. It shows how to add external packages to BaseX, using the EXPath Packaging API [5].
Introduction The functionality of an XQuery processor can be extended with a variety of libraries. This, however, 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 packages. BaseX offers an implementation of this mechanism based on the specification [5] created by EXPath [1]. A package is a .xar archive encapsulating one or more extension libraries. The implementation of BaseX currently supports extensions with XQuery libraries and java libraries packed as .jar files.
Package Repository Unzipped packages are stored in the package repository. This is a directory named BaseXRepo, which is located in your home folder. Depending on your Configuration, the name and location of your repository might vary. BaseX provides three commands for interaction with the package repository – REPO INSTALL, REPO DELETE and REPO LIST. The syntax of these commands is described in Commands. Since Version 7.1, a Repository Module exists, which can be used to install new packages via XQuery. Here we give 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 REPO INSTALL command. The path to the package has to be given as a parameter. An example:
REPO INSTALL http:/ / files. basex. org/ xar/ functx-1. 0. xar
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:
import module namespace functx="http://www.functx.com";
At "seeing" this statement BaseX will check if the namespace "http:/ / www. functx. com" is used in some of the installed packages and if yes, it will load their modules. After that you can call the functions from a module in the standard way, e.g:
functx:capitalize-first("test")
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. Packaging 93
Deleting a Package A package can be deleted either by its name or by the name of its directory. This can be done with the command REPO DELETE. e.g.
REPO DELETE http:/ / www. functx. com or REPO DELETE functx-1.0
Listing installed packages All currently installed packages can be listed using the REPO LIST command. It will list the names of all packages which currently reside in the repository along with their versions:
URI Version Directory ------http://www.functx.com 1.0 http-www.functx.com-1.0
1 package(s).
Structure The EXPath specification [2] defines how the structure of a .xar archive shall look like. The package contains at its root a package descriptor named expath-pkg.xml. This descriptor presents some meta data about the package as well as the libraries which it contains and their dependencies on other libraries or processors. Apart from the package descriptor a .xar archive contains a directory which includes the actual XQuery libraries. For example the FunctX XQuery Library [3] is packaged as follows:
expath-pkg.xml functx/ 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 expath-pkg.xml 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 basex.xml and has to have the following structure:
• 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: Suppose we have a simple class Printer having just one public method print(): Packaging 94
package test;
public final class Printer { public String print(final String s) { return new Writer(s).write(); } }
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 print method of our class. This can be done in the following way:
import module namespace j="http://basex.org/lib/testJar";
declare namespace p="java:test.Printer";
declare function j:print($str as xs:string) as xs:string { let $printer := p:new() return p:print($printer, $str) };
As it can be seen, the class Printer is declared with its binary name as a namespace prefixed with "java" and the XQuery function is implemented using the Java Bindings [4] offered by BaseX. Here [5] 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.
References
[1] http:/ / expath. org/
[2] http:/ / expath. org/ spec/ pkg
[3] http:/ / www. functx. com/
[4] http:/ / docs. basex. org/ wiki/ Java_Bindings
[5] http:/ / files. basex. org/ xar/ XQuery Errors 95 XQuery Errors
This article is part of the Query Portal. It summarizes all error codes that may be thrown by the BaseX XQuery processor. As the original specifications are rather bulky and meticulous, we tried our best to make this overview comprehensible to a wider range of readers. The following tables list the error codes that are known to BaseX, a short description, and examples of queries raising that errors. Original definitions of the error codes are found in the XQuery 3.0 [4], XQuery 3.0 Functions [6], XQuery 1.0 Update [1], XQuery 1.0 Full Text [1], and EXPath HTTP [1] Specifications.
BaseX Errors Error Codes: BASX
Code Description Examples
BASX0001 The specified index type is unknown, or not available. db:info("unknown")
BASX0002 The specified node is not stored in a database.
BASX0003 The specified database was not found or could not be opened. db:open('unknown')
BASX0004 The database node referenced by a function is out of range. db:open-pre('database', -1)
BASX0005 The current user has no permissions to execute an expression. file:delete('file.txt'): Admin rights needed.
BASX0006 The query was timed out. The TIMEOUT option can be modified in the client/server architecture. This error is only raised by the internal BaseX Java function QueryProcess.next(Item).
BASX0007 Nodes were expected as query result. This error is only raised by the internal BaseX Java function QueryProcessor.queryNodes().
BASX0008 A database addressed with the doc() function contains more than one doc('collection') document.
BASX0009 The specified event is unknown. db:event('unknown', 'event')
BASX0010 The specified database option is unknown. declare option db:xyz "no"; 1
BASX0011 The specified XSLT parameter XSLT parameter is unknown. xslt:transform('doc.xml', 'input.xslt', '
BASX0011 The specified XSLT parameter XSLT parameter is unknown. xslt:transform('doc.xml', 'input.xslt', '
BASX0012 A single document is expected as replace target. db:replace('db', 'unknown.xml', '')
BASX0013 An empty rename sting was specified. db:rename('db', 'old.xml', )
BASX0014 An error occurred while optimizing the database. db:optimize('db')
BASX0015 The specified input text cannot be parsed as JSON. json:parse()
BASX0016 The specified input text cannot be serialized to a JSON document. json:serialize(
BASX0017 Invalid values were used for fn:partial-apply().
BASX0018 Bytes could not be converted to a string. XQuery Errors 96
Static Errors Error Codes: XPST, XQST
Code Description Examples
XPST0003 An error occurred while parsing the query string (i.e., before the query could be 1+for i in //* return $i compiled and executed). This error is the most common one, and may be accompanied by a variety of different error messages.
XPST0005 An expression will never results, no matter what input will be processed. doc('input')/..
XPST0008 A variable or type name is used that has not been defined in the current scope. $a---element(*, x)
XPST0017 • The specified function is unknown, or unknown()count(1,2,3) • it uses the wrong number of arguments.
XPST0051 An unknown QName is used in a sequence type (e.g. in the target type of the cast 1 instance of expression). x"test" cast as xs:itr
XPST0080 xs:NOTATION or xs:anyAtomicType is used as target type of cast or 1 castable as xs:NOTATION castable.
XPST0081 • A QName uses a prefix that has not been bound to any namespace, or unknown:x(# pragma #) { 1 } • a pragma or option declaration has not been prefixed.
XQST0009 The query imports a schema (schema import is not supported by BaseX). import schema "x"; ()
XQST0022 Namespace values must be constant strings.
XQST0031 The specified XQuery version is not specified. xquery version "9.9"; ()
XQST0032 The base URI was declared more than once. declare base-uri ...
XQST0033 A namespace prefix was declared more than once. declare namespace a="a"; declare namespace a="b"; ()
XQST0034 A function was declared more than once. declare function local:a() { 1 }; declare function local:a() { 2 }; local:a()
XQST0038 The default collation was declared more than once. declare default collation ...
XQST0039 Two or more parameters in a user-defined function have the same name. declare function local:fun($a, $a) { $a * $a }; local:fun(1,2)
XQDY0040 Two or more attributes in an element have the same node name.
XQDY0045 A user-defined function uses a reserved namespace. declare function fn:fun() { 1 }; ()
XQST0047 A module was defined more than once. import module ...
XQST0048 A module declaration does not match the namespace of the specified module. import module namespace invalid="uri"; 1
XQST0049 A global variable was declared more than once. declare variable $a := 1; declare variable $a := 1; $a
XQST0054 A global variable depends on itself. This may be triggered by a circular variable declare variable $a := definition. local:a(); declare function local:a() { $a }; $a
XQST0055 The mode for copying namespaces was declared more than once. declare copy-namespaces ...
XQST0057 The namespace of a schema import may not be empty. import schema ""; ()
XQST0059 The schema or module with the specified namespace cannot be found or processed. import module "unknown"; () XQuery Errors 97
XQST0060 A user-defined function has no namespace. declare default function namespace ""; declare function x() { 1 }; 1
XQST0065 The ordering mode was declared more than once. declare ordering ...
XQST0065 The default namespace mode for elements or functions was declared more than once. declare default element namespace ...
XQST0067 The construction mode was declared more than once. declare construction ...
XQST0068 The mode for handling boundary spaces was declared more than once. declare boundary-space ...
XQST0069 The default order for empty sequences was declared more than once. declare default order empty ...
XQST0070 A namespace declaration overwrites a reserved namespace. declare namespace xml=""; ()
XQST0071 A namespace is declared more than once in an element constructor.
XQST0075 The query contains a validate expression (validation is not supported by BaseX). validate strict { () }
XQST0076 A group by or order by clause specifies an unknown collation. for $i in 1 to 10 order by $i collation "unknown" return $i
XQST0079 A pragma was specified without the expression that is to be evaluated. (# xml:a #) {}
XQST0085 An empty namespace URI was specified.
XQST0087 An unknown encoding was specified. Note that the encoding declaration is currently xquery version "1.0" encoding ignored in BaseX. "a b"; ()
XQST0088 An empty module namespace was specified. import module ""; ()
XQST0089 Two variables in a for or let clause have the same name. for $a at $a in 1 return $i
XQST0090 A character reference specifies an invalid character. " "
XQST0093 A module depends on itself. This may be triggered by a circular module definition. import module ...
XQST0094 group by references a variable that has not been declared before. for $a in 1 group by $b return $a
XQST0097 A decimal-format property is invalid. declare default decimal-format digit = "xxx"; 1
XQST0098 A single decimal-format character was assigned to multiple properties. declare default decimal-format digit = "%"; 1
XQST0099 The context item was declared more than once. declare context item ...
XQST0107 The initializer of the context item depends on itself. declare context item := .; ()
XQST0108 Output declarations may only be specified in the main module. Module: declare output ...
XQST0109 The specified serialization parameter is unknown. declare option output:unknown "..."; 1
XQST0110 A serialization parameter was specified more than once in the output declarations. declare option output:indent "no"; declare option output:indent "no"; 1
XQST0111 A decimal format was declared more than once. declare decimal-format ...
XQST0113 Context item values may only be in the main module. Module: declare context item := 1;
XQST0114 A decimal-format property has been specified more than once. declare decimal-format EN NaN="!" NaN="?"; () XQuery Errors 98
Type Errors Error Codes: XPTY, XQTY
Code Description Examples
XPTY0004 This error is raised if an expression has the wrong type, or cannot be cast into the 1 + "A"abs("a")1 cast as specified type. It may be raised both statically (during query compilation) or xs:gYear dynamically (at runtime).
XPTY0018 The result of the last step in a path expression contains both nodes and atomic values. doc('input.xml')/(*, 1)
XPTY0019 The result of a step (other than the last step) in a path expression contains an atomic (1 to 10)/* values.
XQTY0024 An attribute node cannot be bound to its parent element, as other nodes of a different
Dynamic Errors Error Codes: XPDY, XQDY
Code Description Examples
XPDY0002 • No value has been defined for an external variable, or declare variable $x external; • no context item has been set before the query was executed. $xdescendant::*
XPDY0050 • The operand type of a treat expression does not match the "string" treat as xs:int"string"[/] type of the argument, or • the root of the context item must be a document node.
XQDY0025 Two or more attributes in a constructed element have the same element x { attribute a { "" } attribute a node name. { "" } }
XQDY0026 The content of a computed processing instruction contains "?>". processing-instruction pi { "?>" }
XQDY0041 The name of a processing instruction is invalid. processing-instruction { "1" } { "" }
XQDY0043 The node name of an attribute uses reserved prefixes or attribute xmlns { "etc" } namespaces.
XQDY0064 The name of a processing instruction equals "XML" (case processing-instruction xml { "etc" } insensitive).
XQDY0072 The content of a computed comment contains "--" or ends with "-". comment { "one -- two" }
XQDY0074 The name of a computed attribute or element is invalid, or uses an element { "x y" } { "" } unbound prefix.
XQDY0095 A sequence with more than one item was bound to a group by let $a := (1,2) group by $a return $a clause.
XQDY0096 The node name of an element uses reserved prefixes or element { QName("uri", "xml:n") } {} namespaces. XQuery Errors 99
Functions Errors Error Codes: FOAR, FOCA, FOCH, FODC, FODF, FODT, FOER, FOFD, FONS, FORG, FORX, FOTY, FOUT
Code Description Examples
FOAR0001 A value was divided by zero. 1 div 0
FOAR0002 A numeric declaration or operation causes an over- or 12345678901234567890xs:double("-INF") idiv 1 underflow.
FOCA0002 • A float number cannot be converted to a decimal or xs:int(xs:double("INF"))QName("", "el em") integer value, or • a function argument cannot be converted to a valid QName.
FOCA0003 A value is too large to be represented as integer. xs:integer(99e100)
FOCA0005 "NaN" is supplied to duration operations. xs:yearMonthDuration("P1Y") * xs:double("NaN")
FOCH0001 A codepoint was specified that does not represent a valid codepoints-to-string(0) XML character.
FOCH0002 A unsupported collation was specified in a function. compare('a', 'a', 'unknown')
FOCH0003 A unsupported normalization form was specified in a normalize-unicode('a', 'unknown') function.
FODC0001 The argument specified in fn:id() or id("id0",
FODC0002 The specified document resource cannot be retrieved. doc("unknown.xml")
FODC0004 The specified collection cannot be retrieved. collection("unknown")
FODC0005 The specified URI to a document resource is invalid. doc("
FODC0006 The string passed to fn:parse-xml() is not parse-xml(" FODC0007 The base URI passed to fn:parse-xml() is invalid. parse-xml(" FODF1280 The name of the decimal format passed to format-number(1, "0", "invalid") fn:format-number() is invalid. FODF1310 The picture string passed to fn:format-number() format-number(1, "invalid") is invalid. FODT0002 A duration declaration or operation causes an over- or implicit-timezone() div 0 underflow. FODT0003 An invalid timezone was specified. adjust-time-to-timezone(xs:time("01:01:01"), xs:dayTimeDuration("PT20H")) FOER0000 Error triggered by the fn:error() function. error() FOFD1340 The picture string passed to fn:format-date(), format-date(current-date(), "[]") fn:format-time() or fn:format-dateTime() is invalid. FOFD1350 The picture string passed to fn:format-date(), format-time(current-time(), "[Y2]") fn:format-time() or fn:format-dateTime() specifies an non-available component. XQuery Errors 100 FONS0004 A function has a QName as argument that specifies an resolve-QName("x:e", FORG0001 A value cannot be cast to the required target type. xs:integer("A")1 + FORG0002 The URI passed to fn:resolve-URI() is invalid. resolve-URI(":") FORG0003 fn:zero-or-one() was called with more than one zero-or-one((1, 2)) item. FORG0004 fn:one-or-more() was called with zero items. one-or-more(()) FORG0005 fn:exactly-one() was called with zero or more exactly-one((1, 2)) than one item. FORG0006 A wrong argument type was specified in a function call. sum((1, "string")) FORG0008 The arguments passed to fn:dateTime() have dateTime(xs:date("2001-01-01+01:01"), different timezones. current-time()) FORX0001 A function specifies an invalid regular expression flag. matches('input', 'query', 'invalid') FORX0002 A function specifies an invalid regular expression. matches('input', '[') FORX0003 A regular expression matches an empty string. tokenize('input', '.?') FORX0004 The replacement string of a regular expression is invalid. replace("input", "match", "\") FOTY0012 An item has no typed value. FOTY0013 Functions items cannot be atomized, have no defined equality, and have no string representation. FOTY0014 Function items have no string representation. FOTY0015 Function items cannot be compared. FOUT1170 Function argument cannot be used to retrieve a text resource. FOUT1170 Encoding to retrieve a text resource is invalid or not unparsed-text('file.txt', 'InvalidEncoding') supported. ....to be added: FOTY0012-0015 Serialization Errors Error Codes: SEPM, SERE, SESU Code Description Examples SESU0007 The specified encoding is not supported. declare option output:encoding "xyz"; 1 SEPM0009 omit-xml-declaration is set to yes, and standalone has a value other than omit. SEPM0010 method is set to xml, undeclare-prefixes is set to yes, and version is set to 1.0. SERE0014 method is set to html, and an invalid HTML character is found. SERE0015 method is set to html, and a closing bracket (>) appears inside a processing instruction. SEPM0016 A specified parameter is unknown or has an invalid value. declare option output:indent "nope"; 1 XQuery Errors 101 SEPM0017 The definition of serialization parameter is invalid. Update Errors Error Codes: FOUP, XUDY, XUST, XUTY Code Description Examples FOUP0001 The first argument of fn:put() must be a fn:put(text { 1 }, 'file.txt') document node or element. FOUP0002 The second argument of fn:put() is not a fn:put(, '//') valid URI. XUDY0009 The target node of a replace expression needs a replace node XUDY0014 The expression updated by the modify clause let $a := doc('a') return copy $b := $a modify delete was not created by the copy clause. node $a/* return $b XUDY0015 In a rename expression, a target is renamed let $a := XUDY0016 In a replace expression, a target is replaced let $a := XUDY0017 In a replace value of expression, a target let $a := XUDY0021 The resulting update expression contains copy $c := XUDY0023 The resulting update expression conflicts with rename node XUDY0024 New namespaces conflict with each other. copy $n := XUDY0027 Target of an update expression is an empty insert node XUDY0029 The target of an update expression has no parent insert node XUDY0030 Attributes cannot be inserted before or after the insert node XUDY0031 Multiple calls to fn:put() address the same for $i in 1 to 3 return put(, 'file.txt') URI. XUST0001 No updating expression is allowed here. delete node /, "finished." XUST0002 An updating expression is expected in the copy $a := XUST0003 The revalidation mode was declared more than declare revalidation ... once. XUST0026 The query contains a revalidate expression declare revalidation ... (revalidation is not supported by BaseX). XUST0028 no return type may be specified in an updating declare updating function local:x() as item() { () }; function. () XQuery Errors 102 XUTY0004 New attributes to be inserted must directly insert node (, attribute a {""}) into follow the root node. XUTY0005 A single element or document node is expected insert node XUTY0006 A single element, text, comment or processing insert node XUTY0007 Only nodes can be deleted. delete node "string" XUTY0008 A single element, text, attribute, comment or replace node document { } with processing instruction is expected as target of a replace expression. XUTY0010 In a replace expression, in which no replace node /b with attribute size { 1 } attributes are targeted, the replacing nodes must not be attributes as well. XUTY0011 In the replace expression, in which attributes replace node XUTY0012 In a rename expression, the target nodes must rename node text { 1 } as XUTY0013 An expression in the copy clause must return a copy $c := (, ) modify () return $c single node. XUTY0022 An attribute must not be inserted into a insert node Full-Text Errors Error Codes: FTDY, FTST Code Description Examples FTDY0016 The specified weight value is out of range. 'a' contains text 'a' weight { 1001 } FTDY0017 The not in operator contains a string exclude. 'a' contains text 'a' not in (ftnot 'a') FTDY0020 The search term uses an invalid wildcard syntax. 'a' contains text '.{}' using wildcards FTST0000 BaseX specific: Either wildcard or the fuzzy option can be chosen at the 'a' contains text 'a' using wildcards same time. using fuzzy FTST0007 The full-text expression contains an ignore option (the ignore 'a' contains text 'a' without content option is not supported by BaseX). 'x' FTST0008 The specified stop word file could not be opened or processed. 'a' contains text 'a' using stop words at 'unknown.txt' FTST0009 The specified language is not supported. 'a' contains text 'a' using language 'aaa' FTST0018 The specified thesaurus file could not be opened or processed. 'a' contains text 'a' using thesaurus at 'aaa' FTST0019 A match option was defined more than once. 'a' contains text 'a' using stemming using stemming XQuery Errors 103 ZIP Module Errors Error Codes: FOZP Code Description Examples FOZP0001 The specified path does not exist. zip:entries('unknown.zip') FOZP0002 Entries in the description of a ZIP archive are unknown, missing, or zip:zip-file( FOZP0003 ZIP file extraction or creation fails for some other reason (e.g.: new ZIP file contains no entries, or duplicates). Cryptographic Module Errors Error Codes: FOCX Code Description Examples FOCX0001 Canonicalization algorithm is not supported. FOCX0002 Digest algorithm is not supported. FOCX0003 Signature algorithm is not supported. FOCX0004 XPath expression is invalid. FOCX0005 Invalid name for $digital-certificate root. FOCX0006 Invalid child element of $digital-certificate. FOCX0007 Key store is null. FOCX0008 I/O error while reading keystore. FOCX0009 Permission denied to read keystore. FOCX0010 Keystore URL is invalid. FOCX0011 Keystore type is not supported. FOCX0012 Cannot find key for alias in given keystore. FOCX0013 Hashing algorithm is not supported. FOCX0014 Encoding method is not supported. FOCX0015 Cannot find signature element. FOCX0016 No such padding. FOCX0017 Incorrect padding. FOCX0018 Encryption type is not supported. FOCX0019 Secret key is invalid. FOCX0020 Illegal block size. FOCX0021 Algorithm is not supported. FOCX0022 Decryption type is not supported. FOCX9999 Signature type is not supported. FOCX9998 Not (yet) supported. FOCX9997 Algorithm not compatible with encryption type. FOCX9996 IO Exception. FOCX9995 Keystore exception. XQuery Errors 104 FOCX9994 Signature exception. FOCX9993 Invalid algorithm. FOCX9992 Invalid certificate alias. File Module Errors Error Codes: FOFL Code Description Examples FOFL0001 The specified path does not exist. file:size('unknown.txt') FOFL0002 The specified path does already exist. file:create-directory('existing-directory') FOFL0003 The specified path does not point to a directory. file:list('file.txt') FOFL0004 The specified path points to a directory. file:read('directory') FOFL0005 The specified encoding is not supported. file:read('file.txt', 'UTF99') FOFL9999 A file operation fails for any other reason. HTTP Module Errors Error Codes: FOHC Code Description Examples FOHC0001 The specified URL is invalid. FOHC0002 The requested method is not valid for HTTP. FOHC0004 The request element is not valid. FOHC0005 An HTTP error occurred. FOHC0006 The provided credentials are invalid. FOHC0007 The HTML input could not be parsed. Packaging Errors Error Codes: PACK Code Description Examples PACK0001 The specified package does not exist. PACK0002 The specified package is already installed. PACK0003 A required package is not installed. PACK0004 Invalid package descriptor found. PACK0005 A module is already installed within another package. PACK0006 The current package could not be parsed. PACK0007 A package cannot be deleted. PACK0008 A package depends on another package. PACK0009 The addressed package version is not supported. PACK0010 Invalid JAR descriptor found. XQuery Errors 105 PACK0011 The JAR descriptor could not be read. SQL Module Errors Error Codes: FOSQ Code Description Examples FOSQ0001 An SQL exception occurred. FOSQ0002 No opened connection with the specified id found. FOSQ0003 Number of parameters differs from number of placeholders. FOSQ0004 No parameter type specified. FOSQ0005 An unexpected attribute was found. FOSQ0006 The specified format is illegal. FOSQ0007 The JDBC driver cannot be initialized. References [1] http:/ / www. expath. org/ spec/ http-client Serialization This page is part of the Query Portal. Serialization parameters define how XQuery items and XML nodes are textually output, i.e., serialized. (For input see Parsers.) They have been formalized in the W3C XQuery Serialization 3.0 [1] document. In BaseX, they can be specified in several ways: • by including them in the prolog of the XQuery expression, • by specifying them in the XQuery functions file:write() or fn:serialize(), • by using the -s flag of the BaseX command-line clients, • by setting the SERIALIZER option before running a query, • by setting the EXPORTER option before exporting a database, or • by setting them as REST query parameters Parameters The following table gives a brief summary of all serialization parameters recognized by BaseX. For details, please refer to official specification. Serialization 106 Parameter Description Allowed Default Examples method Specifies the serialization method: xml, xhtml, xml method=xml html, text, • xml, xhtml, html, and text are adopted from the html5, official specification. json, • html5 is specific to BaseX and can be used to output [2] jsonml, query results as HTML5 . raw • json and jsonml are specific to BaseX and can be used to output XML nodes in the JSON format (see the JSON Module for more details). • raw is BaseX-specific as well: Binary data types are output in their raw form, i.e., without modifications. For all other types, the items’ string values are returned. No indentation takes place, and and no characters are encoded via entities. version Specifies the version of the serializer. xml/xhtml: 1.0 version=1.0 1.0, 1.1 html: 4.0, 4.01 encoding Encoding to be used for outputting the data. all encodings UTF-8 encoding=US-ASCII supported by Java indent Adjusts whitespaces to make the output better readable. yes, no yes indent=no cdata-section-elements List of elements to be output as CDATA, separated by cdata-section-elements=text whitespaces. Example: BaseX provides some additional, implementation-specific serialization parameters: Parameter Description Allowed Default Examples format Turns output formatting on/off, including the conversion of yes, no yes format=no special characters to entities and insertion of item separators. This flag can be turned off to simplify the handling of plain-text results. tabulator Uses tab characters (\t) for indenting elements. yes, no no tabulator=yes indents Specifies the number of characters to be indented. positive 2 indents=1, tabulator=yes number wrap-prefix, Specifies a prefix and/or URI for wrapping the query results. wrap-prefix=rest, wrap-uri wrap-uri=http:/ / basex. org/ rest newline Specifies the type of newline to be used as end-of-line marker. \n, \r\n, system newline=\r\n \r dependent separator Determines the string to be used as item separator. Introduced arbitrary single space separator=\n with Version 7.2 strings Changelog Version 7.2 • Added: separator parameter Version 7.1 • Added: newline parameter Version 7.0 • Added: Serialization parameters added to REST API; JSON/JsonML/raw methods References [1] http:/ / www. w3. org/ TR/ xslt-xquery-serialization-30 [2] http:/ / en. wikipedia. org/ wiki/ Html5 [3] http:/ / www. w3. org/ TR/ html4/ strict. dtd 108 XQuery Modules Cryptographic Module This module contains XQuery functions to perform cryptographic operations in XQuery. The cryptographic module is based on an early draft of the EXPath Cryptographic Module [7] and provides the following functionality: 1. Creation of message authentication codes (HMAC) 2. Encryption and decryption 3. Creation and validation of an XML Digital Signature All functions are introduced with the crypto: prefix, which is linked to the statically declared http:/ / expath. org/ ns/ crypto namespace. Message Authentication Code crypto:hmac Signatures crypto:hmac($message as xs:string(), $secret-key as xs:string(), algorithm as xs:string()) as xs:string() crypto:hmac($message as xs:string(), $secret-key as xs:string(), algorithm as xs:string(), $encoding as xs:string()) as xs:string() Summary Creates a message authentication code via a cryptographic hash function and a secret key. $encoding must either be hex, base64 or the empty string and specifies the encoding of the returned authentication code. Default is base64. $algorithm describes the hash algorithm which is used for encryption. Currently supported are md5, sha1, sha256, sha384, sha512. Default is md5. Errors FOCX0013 is raised if the specified hashing algorithm is not supported. FOCX0014 is raised if the specified encoding method is not supported. FOCX0019 is raised if the specified secret key is invalid. Example Returns the message authentication code (MAC) for a given string. Query: crypto:hmac('message','secretkey','md5','base64') Result: 34D1E3818B347252A75A4F6D747B21C2 Cryptographic Module 109 Encryption & Decryption The encryption and decryption functions underlie several limitations: • Cryptographic algorithms are currently limited to symmetric algorithms only. This means that the same secret key is used for encryption and decryption. • Available algorithms are DES and AES. • Padding is fixed to PKCS5Padding. • The result of an encryption using the same message, algorithm and key looks different each time it is executed. This is due to a random initialization vector (IV) which is appended to the message and simply increases security. • As the IV has to be passed along with the encrypted message somehow, data which has been encrypted by the crypto:encrypt function in BaseX can only be decrypted by calling the crypto:decrypt function. crypto:encrypt Signatures crypto:encrypt($input as xs:string(), $encryption-type as xs:string(), $secret-key as xs:string(), $cryptographic-algorithm as xs:string()) as xs:string() Summary Encrypts the given input string. $encryption-type must be symmetric, as asymmetric encryption is not supported so far. Default is symmetric. $secret-key is the secret key which is used for both encryption and decryption of input data. Its length is fixed and depends on the chosen algorithm: 8 bytes for DES, 16 bytes for AES. $cryptographic-algorithm must either be DES or AES. Other algorithms are not supported so far, but, of course, can be added on demand. Default is DES. Errors FOCX0016 is raised if padding problems arise. FOCX0017 is raised if padding is incorrect. FOCX0018 is raised if the encryption type is not supported. FOCX0019 is raised if the secret key is invalid. FOCX0020 is raised if the block size is incorrect. FOCX0021 is raised if the specified encryption algorithm is not supported. Example Encrypts input data. Query: crypto:encrypt('message', 'symmetric','keykeyke','DES') crypto:decrypt Signatures crypto:decrypt($input as xs:string(), $decryption-type as xs:string(), $secret-key as xs:string(), $cryptographic-algorithm as xs:string()) as xs:string() Summary Decrypts the encrypted $input. $decryption-type must be symmetric. An option for asymmetric encryption will most likely be added with another version of BaseX. Default is symmetric. $secret-key is the secret key which is used for both encryption and decryption of input data. Its length is fixed and depends on the chosen algorithm: 8 bytes for DES, 16 bytes for AES. $cryptographic-algorithm must either be DES or AES. Other algorithms are not supported so far, but, of course, can be added on demand. Default is DES. Errors FOCX0016 is raised if padding problems arise. FOCX0017 is raised if padding is incorrect. FOCX0018 is raised if the encryption type is not supported. FOCX0019 is raised if the secret key is invalid. FOCX0020 is raised if the block size is incorrect. FOCX0021 is raised if the specified encryption algorithm is not supported. Cryptographic Module 110 Example Decrypts input data and returns the original string. Query: let $encrypted := crypto:encrypt('message', 'symmetric','keykeyke','DES') return crypto:decrypt($encrypted, 'symmetric','keykeyke','DES') Result: message XML Signature XML Signatures [1] are used to sign data. In our case, the data which is signed is an XQuery node. The following example shows the basic structure of an XML signature. XML Signature • SignedInfo contains or references the signed data and lists algorithm information • Reference references the signed node • Transforms contains transformations (i.e. XPath expressions) that are applied to the input node in order to sign a subset • DigestValue holds digest value of the transformed references • SignatureValue contains the Base64 encoded value of the encrypted digest of the SignedInfo element • KeyInfo provides information on the key that is used to validate the signature • Object contains the node which is signed if the signature is of type enveloping Signature Types Depending on the signature type, the signature element is either placed as a child of the signed node (enveloped type), or directly contains the signed node (enveloping type). Detached signatures are so far not supported. Digital Certificate The generate-signature function allows to pass a digital certificate. This certificate holds parameters that allow to access key information stored in a Java key store which is then used to sign the input document. Passing a digital certificate simply helps re-using the same key pair to sign and validate data. The digital certificate is passed as a node and has the following form: Cryptographic Module 111 crypto:generate-signature Signatures crypto:generate-signature($input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string()) as node() crypto:generate-signature($input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string(), $xpath-expression as xs:string()) as node() crypto:generate-signature($input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string(), $digital-certificate as node()) as node() crypto:generate-signature($input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string(), $xpath-expression as xs:string(), $digital-certificate as node()) as node() Summary $canonicalization-algorithm must either be inclusive-with-comments, inclusive, exclusive-with-comments or exclusive. Default is inclusive-with-comments. $digest-algorithm must be one of the following: SHA1, SHA256 or SHA512. Default is SHA1. $signature-algorithm must either be RSA_SHA1 or DSA_SHA1. Default is RSA_SHA1. $signature-namespace-prefix may be empty and prefixes the Signature element accordingly. $signature-type must either be enveloped or enveloping. Detached signatures are so far not supported. Default is enveloped. $xpath-expression is an arbitrary XPath expression which specifies a subset of the document that is to be signed. $digital-certificate is the digitial certificate used to sign the input document. Errors FOCX0001 is raised if the canonicalization algorithm is not supported. FOCX0002 is raised if the digest algorithm is not supported. FOCX0003 is raised if the signature algorithm is not supported. FOCX0004 is raised if the $xpath-expression is invalid. FOCX0005 is raised if the root name of $digital-certificate is not 'digital-certificate. FOCX0007 is raised if the key store is null. FOCX0012 is raised if the key cannot be found in the specified key store. FOCX9992 is raised if the certificate alias is invalid. FOCX9993 is raised if an invalid algorithm is specified. FOCX9994 is raised if an exception occurs while the signing the document. FOCX9995 is raised if an exception occurs during key store initialization. FOCX9996 is raised if an IO exception occurs. FOCX9999 is raised if the signature type is not supported. [1] Example Generates an XML Signature . Query: crypto:generate-signature(, '', '', '', '', '') Cryptographic Module 112 Result: crypto:validate-signature Signatures crypto:validate-signature($input-doc as node()) as xs:boolean() Summary Checks if the given node contains a Signature element and whether the signature is valid. In this case true is returned. If the signature is invalid the function returns false. Errors FOCX0015 is raised if the signature element cannot be found. FOCX9994 is raised if an unspecified problem occurs during validation. FOCX9996 is raised if an IO exception occurs during validation. [1] Example Validates an XML Signature . Query: let $sig := crypto:generate-signature(, '', '', '', '', '') return crypto:validate-signature($sig) Result: true Cryptographic Module 113 Changelog The Module was introduced with Version 7.0. References [1] http:/ / www. w3. org/ TR/ xmldsig-core/ Database Module This module contains XQuery functions for handling databases from within XQuery. Existing databases can be opened and listed, index structures can be directly accessed, documents can be added to and removed from collections, etc. All functions are introduced with the db: prefix, which is linked to the statically declared http:/ / basex. org/ modules/ db namespace. Commonalities Many functions share $db as argument, which may either reference a string, denoting the name of the addressed database, or a node from an already opened database. The following errors may be raised by these functions: • BASX0002 is raised if $db references a node that is not stored in a database (i.e., references a main-memory XML fragment). • BASX0003 is raised if the addressed database cannot be opened. General Functions db:info Signatures db:info($db as item()) as element(Database) Summary Returns meta information on the specified database. db:list Signatures db:list() as xs:string* db:list($db as item()) as xs:string* db:list($db as item(), $path as xs:string) as xs:string* Summary Returns an xs:string sequence with the names of all databases. If $db is specified, all documents and raw files of the specified database are returned. The list of resources can be further restricted by the $path argument. Examples • db:list("docs") returns the names of all documents from the database named docs. Database Module 114 db:list-details Signatures db:list-details() as element(database)* db:list-details($db as item()) as element(resource)* db:list-details($db as item(), $path as xs:string) as element(resource)* Summary Returns an element sequence with the names of all databases together with their database path, the number of stored resources and the date of modification. If $db is specified, all documents and raw files of the specified database together with their content-type, the modification date and the resource type are returned. The list of resources can be further restricted by the $path argument. Examples • db:list-details("docs") returns the names plus additional data of all documents from the database named docs. db:open Signatures db:open($db as item()) as document-node()* db:open($db as item(), $path as xs:string) as document-node()* Summary Returns a sequence with all document nodes contained in the database specified by $db. The document nodes to be returned can be restricted by the $path argument. Examples • db:open("docs") returns all documents from the database named docs. • db:open("docs", "one") returns all documents from the database named docs in the subpath one. db:open-id Signatures db:open-id($db as item(), $id as xs:integer) as node() Summary Opens the database specified by $db and returns the node with the specified $id value. Each database node has a persistent id, which remains valid after update operations. If no updates are performed, the pre value can be requested, which provides access to database nodes in constant time. db:open-pre Signatures db:open-pre($db as item(), $pre as xs:integer) as node() Summary Opens the database specified by $db and returns the node with the specified $pre value. The pre value provides access to a database node in constant time, but it is transient, i.e., it may change when database updates are performed. Errors BASX0004 is raised if the specified $pre value does not exist in the database. Examples • db:open-pre("docs", 0) returns the first database node from the database named docs. Database Module 115 db:system Signatures db:system() as element(system) Summary Returns information on the database system, such as the database path and current database settings. Read Operations db:attribute Signatures db:attribute($db as item(), $string as item()) as attribute()* db:attribute($db as item(), $string as item(), $attname as xs:string) as attribute()* Summary Returns all attribute nodes that have $string as their string value. If $attname is specified, the resulting attribute nodes are filtered by their attribute name. Examples • db:attribute("DB", "QUERY", "id")/.. returns the parents of all id attribute nodes of the database DB that have QUERY as string value. db:fulltext Signatures db:fulltext($db as item(), $text as item()) as text()* Summary Returns all text nodes from the full-text index that contain the string $text. The index full-text options will be applied here: if the index terms have been stemmed, the search string will be stemmed as well. Errors BASX0001 is raised if the index is not available. Examples • db:fulltext("DB", "QUERY") returns all text nodes of the database DB that contain the string QUERY. db:node-id Signatures db:node-id($nodes as node()*) as xs:integer* Summary Returns the id values of all database nodes specified by $nodes. Each database node has a persistent id, which remains valid after update operations. If no updates are performed, the pre value can be requested, which provides access to database nodes in constant time. db:node-pre Database Module 116 Signatures db:node-pre($nodes as node()*) as xs:integer* Summary Returns the pre values of all database nodes specified by $nodes. The pre value provides access to a database node in constant time, but it is transient, i.e., it may change when database updates are performed. Examples • db:node-pre(doc("input")) returns 0 if the database input contains a single document. db:retrieve Signatures db:retrieve($db as item(), $path as xs:string) as xs:base64Binary Summary Returns a binary database resource addressed by $db and $path. Errors FODC0002 is raised if the addressed resource is not found or cannot be retrieved. Examples • declare option output:method 'raw'; db:retrieve("DB", "music/01.mp3") returns the specified audio file as raw data. db:text Signatures db:text($db as item(), $string as item()) as text()* Summary Returns all text nodes that have $string as their string value. Examples • db:text("DB", "QUERY")/.. returns the parents of all text nodes of the database DB that match the string QUERY. Updates All functions in this section are treated as updating: they are not immediately executed, but queued on the pending update list, which is processed after the actual query has been evaluated. The XQuery Update page gives more insight into the relevant concepts. db:add Signatures db:add($db as item(), $input as item()) as empty-sequence() db:add($db as item(), $input as item(), $path as xs:string) as empty-sequence() Summary Adds documents specified by $input to the database $db and the specified $path. Errors FODC0002 is raised if $input is a string representing a path, which cannot be read. FOUP0001 is raised if $input is not a string and not a document node. Examples • db:add("DB", "/home/dir/doc.xml") adds the file /home/dir/doc.xml to the database DB. • db:add("DB", "", "doc.xml") adds a document with content to the database DB under the name doc.xml. • db:add("DB", document { }, "doc.xml") adds the document node to the database DB under the name doc.xml. • db:add("DB", "/home/dir", "docs/dir") adds all documents in /home/dir to the database DB under the path docs/dir. Database Module 117 db:delete Signatures db:delete($db as item(), $path as xs:string) as empty-sequence() Summary Deletes document(s), specified by $path, from the database $db. Examples • db:delete("DB", "docs/dir/doc.xml") deletes the document docs/dir/doc.xml in the database DB. • db:delete("DB", "docs/dir") deletes all documents with paths beginning with docs/dir in the database DB. db:optimize Signatures db:optimize($db as item()) as empty-sequence() db:optimize($db as item(), $all as xs:boolean) as empty-sequence() Summary Optimizes the meta data and indexes of the database $db. If $all is set to true(), the complete database will be rebuilt. Errors BASX0014 is raised if an error occurs during optimizing the data structures. BASX0015 is raised if the $all flag is set to true(), but the database is an in-memory database. BASX0016 is raised if the database $db is in use by other user(s). Examples • db:optimize("DB") optimizes the database structures of the database DB. • db:optimize("DB", true()) optimizes all database structures of the database DB. db:rename Signatures db:rename($db as item(), $path as xs:string, $newpath as xs:string) as empty-sequence() Summary Renames document(s), specified by $path to $newpath in the database $db. Errors BASX0013 is raised if new document name(s) will be empty. Examples • db:rename("DB", "docs/dir/doc.xml", "docs/dir/newdoc.xml") renames the document docs/dir/doc.xml to docs/dir/newdoc.xml in the database DB. • db:rename("DB", "docs/dir", "docs/newdir") renames all documents with paths beginning with docs/dir to paths beginning with docs/newdir in the database DB. db:replace Signatures db:replace($db as item(), $path as xs:string, $input as item()) as empty-sequence() Summary Replaces a document, specified by $path, in the database $db with the content of $input. Errors BASX0012 is raised if $path is not a single document path. FODC0002 is raised if $input is a string representing a path, which cannot be read. FOUP0001 is raised if $input is not a string and not a document node. Examples • db:replace("DB", "docs/dir/doc.xml", "/home/dir/doc.xml") replaces the content of the document docs/dir/doc.xml in the database DB with the content of the file /home/dir/doc.xml. • db:replace("DB", "docs/dir/doc.xml", "") replaces the content of the document docs/dir/doc.xml in the database DB with . • db:replace("DB", "docs/dir/doc.xml", document { }) replaces the content of the document docs/dir/doc.xml in the database DB with the specified document node. Database Module 118 db:store Signatures db:store($db as item(), $path as xs:string, $data as item()) as empty-sequence() Summary Stores a binary resource specified by $data at the location specified by $path. Errors FOUP0002 is raised if the resource cannot be stored at the specified location. Examples • db:store("DB", "video/sample.mov", file:read-binary('video.mov')) stores the addressed video file at the specified location. Helper Functions db:exists Signatures db:exists($db as item()) as xs:boolean db:exists($db as item(), $path as xs:string) as xs:boolean Summary Checks if the specified database or resource exists. false is returned if a database directory is specified. Examples • db:exists("DB") returns true if the database DB exists. • db:exists("DB", "resource") returns true if resource is an XML document or a raw file. db:is-raw Signatures db:is-raw($db as item(), $path as xs:string) as xs:boolean Summary Checks if the specified resource exists and if it is a raw file. Examples • db:is-raw("DB", "music/01.mp3") returns true. db:is-xml Signatures db:is-xml($db as item(), $path as xs:string) as xs:boolean Summary Checks if the specified resource exists and if it is an XML document. Examples • db:is-xml("DB", "dir/doc.xml") returns true. db:content-type Database Module 119 Signatures db:content-type($db as item(), $path as xs:string) as xs:string Summary Retrieves the content type of the resource specified by $path. The file extension is used to recognize the content-type of a resource stored in the database. Content-type application/xml will be returned for any XML document stored in the database, regardless of its file name extension. Errors FODC0002 is raised if the addressed resource is not found or cannot be retrieved. Examples • db:content-type("DB", "docs/doc01.pdf") returns application/pdf. • db:content-type("DB", "docs/doc01.xml") returns application/xml. • db:content-type("DB", "docs/doc01") returns application/xml, if db:is-xml("DB", "docs/doc01") returns true. db:event Signatures db:event($name as xs:string, $query as item()) as empty-sequence() Summary Executes a $query and sends the resulting value to all clients watching the Event with the specified $name. The query may also perform updates; no event will be sent to the client that fired the event. Errors BASX0009 is raised if the specified event is unknown. SEPM0016 is raised if serialization errors occurred while sending the value. Changelog Version 7.1 • Added: db:list-details(), db:content-type() • Updated: db:info(), db:system(), db:retrieve() Version 7.0 • Added: db:retrieve(), db:store(), db:exists(), db:is-raw(), db:is-xml() • Updated: db:list(), db:open(), db:add() File Module 120 File Module This module contains XQuery functions and variables related to file system operations, such as listing, reading, or writing files. All functions are preceded by the file: prefix, which is linked to the statically declared http://expath.org/ns/file namespace. This module has been aligned with the latest EXPath File Module [8] draft from 2011 (expected to be online soon). $file:directory-separator Signatures $file:directory-separator as xs:string Summary This variable returns the directory separator used by the operating system, such as "/" or "\". $file:path-separator Signatures $file:path-separator as xs:string Summary This variable returns the path separator used by the operating system, such as ";" or ":". file:exists Signatures file:exists($path as xs:string) as xs:boolean Summary Returns an xs:boolean indicating whether a file or directory specified by $path exists in the file system. file:is-directory Signatures file:is-directory($path as xs:string) as xs:boolean Summary Returns an xs:boolean indicating whether the argument $path points to an existing directory. file:is-file Signatures file:is-file($path as xs:string) as xs:boolean Summary Returns an xs:boolean indicating whether the argument $path points to an existing file. File Module 121 file:last-modified Signatures file:last-modified($path as xs:string) as xs:dateTime Summary Retrieves the timestamp of the last modification of the file or directory specified by $path. Errors FOFL0001 is raised if the specified path does not exist. file:size Signatures file:size($file as xs:string) as xs:integer Summary Returns the size, in bytes, of the file specified by $path. Errors FOFL0001 is raised if the specified file does not exist. FOFL0004 is raised if the specified file points to a directory. file:base-name Signatures file:base-name($path as xs:string) as xs:string file:base-name($path as xs:string, $suffix as xs:string) as xs:string Summary Returns the base-name of the path specified by $path, which is the component after the last directory separator. If $suffix is specified, it will be trimmed from the end of the result. file:dir-name Signatures file:dir-name($path as xs:string) as xs:string Summary Returns the parent directory of the path specified by $path, which is the component before the last directory separator. file:path-to-native Signatures file:path-to-native($path as xs:string) as xs:string Summary Transforms the $path argument to its native representation on the operating system. Errors FOFL0000 is raised if the specified path cannot be transformed to its native representation. file:resolve-path Signatures file:resolve-path($path as xs:string) as xs:string Summary Transforms the $path argument to an absolute operating system path. file:path-to-uri Signatures file:path-to-uri($path as xs:string) as xs:string Summary Transforms the path specified by $path into a URI with the file:// scheme. File Module 122 file:list Signatures file:list($directory as xs:string) as xs:string* file:list($directory as xs:string, $recursive as xs:boolean) as xs:string* file:list($directory as xs:string, $recursive as xs:boolean, $pattern as xs:string) as xs:string* Summary Lists all files and directories found in the specified $directory. The returned paths are relative to the provided path. The optional parameter $recursive specifies whether the sub-directories are to be recursed as well. [1] The optional parameter $pattern defines a file name pattern in the glob syntax . If present, only those files and directories are returned that correspond to the pattern. Several patterns can be separated with a comma (,). Errors FOFL0003 is raised if the specified path does not point to a directory. FOFL0000 is raised if the operation fails for some other reason. file:create-directory Signatures file:create-directory($directory as xs:string) as empty-sequence() Summary Recursively creates the directories specified by $directory. Errors FOFL0002 is raised if a file with the same path already exists. FOFL0000 is raised if the operation fails for some other reason. file:delete Signatures file:delete($path as xs:string) as empty-sequence() Summary Recursively deletes a file or directory specified by $path. Errors FOFL0001 is raised if the specified path does not exist. FOFL0000 is raised if the operation fails for some other reason. file:read-text Signatures file:read-text($path as xs:string) as xs:string file:read-text($path as xs:string, $encoding as xs:string) as xs:string Summary Reads the textual contents of the file specified by $path and returns it as a xs:string. The optional parameter $encoding defines the encoding of the file. Errors FOFL0001 is raised if the specified file does not exist. FOFL0004 is raised if the specified path is a directory. FOFL0005 is raised if the specified encoding is not supported, or unknown. FOFL0000 is raised if the operation fails for some other reason. file:read-text-lines File Module 123 Signatures file:read-text-lines($path as xs:string) as xs:string file:read-text-lines($path as xs:string, $encoding as xs:string) as xs:string* Summary Reads the textual contents of the file specified by $path and returns it as a sequence of xs:string items. The optional parameter $encoding defines the encoding of the file. Errors FOFL0001 is raised if the specified file does not exist. FOFL0004 is raised if the specified path is a directory. FOFL0005 is raised if the specified encoding is not supported, or unknown. FOFL0000 is raised if the operation fails for some other reason. file:read-binary Signatures file:read-binary($path as xs:string) as xs:base64Binary Summary Reads the binary content of the file specified by $path and returns as a xs:base64Binary. Errors FOFL0001 is raised if the specified file does not exist. FOFL0004 is raised if the specified path is a directory. FOFL0000 is raised if the operation fails for some other reason. file:write Signatures file:write($path as xs:string, $items as item()*) as empty-sequence() file:write($path as xs:string, $items as item()*, $params as xs:node()*) as empty-sequence() Summary Writes a sequence of $items to a file specified by $path. If the specified file already exists, it will be overwritten. The optional argument $params is used to set the serialization parameters (see Serialization for more details).It can be specified as • element(serialization-parameters): Errors FOFL0004 is raised if the specified path is a directory. FOFL0000 is raised if the operation fails for some other reason. file:write-binary File Module 124 Signatures file:write-binary($path as xs:string, $items as xs:base64Binary*) as empty-sequence() Summary Writes a sequence of xs:basex64Binary $items to a file specified by $path. If the specified file already exists, it will be overwritten. Errors FOFL0004 is raised if the specified path is a directory. FOFL0000 is raised if the operation fails for some other reason. file:append Signatures file:append($path as xs:string, $items as item()*) as empty-sequence() file:append($path as xs:string, $items as item()*, $params as xs:node()*) as empty-sequence() Summary Appends a sequence of $items to a file specified by $path. If the specified file does not exists, a new file is created. Errors FOFL0004 is raised if the specified path is a directory. FOFL0000 is raised if the operation fails for some other reason. file:append-binary Signatures file:append-binary($path as xs:string, $items as xs:base64Binary*) as empty-sequence() Summary Appends a sequence of xs:basex64Binary $items to a file specified by $path. If the specified file does not exists, a new file is created. Errors FOFL0004 is raised if the specified path is a directory. FOFL0000 is raised if the operation fails for some other reason. file:copy Signatures file:copy($source as xs:string, $target as xs:string) as empty-sequence() Summary Copies a file specified by $source to the file or directory specified by $target. If the target represents an existing file, it will be overwritten. No operation will be performed if the source and target path are equal. Errors FOFL0001 is raised if the specified source does not exist. FOFL0002 is raised if the specified source is a directory and the target is a file. FOFL0003 is raised if the parent of the specified target is no directory. FOFL0000 is raised if the operation fails for some other reason. file:move File Module 125 Signatures file:move($source as xs:string, $target as xs:string) as empty-sequence() Summary Moves or renames the file or directory specified by $source to the path specified by $target. No operation will be performed if the source and target path are equal. Errors FOFL0001 is raised if the specified source does not exist. FOFL0002 is raised if the specified source is a directory and the target is a file. FOFL0003 is raised if the parent of the specified target is no directory. FOFL0000 is raised if the operation fails for some other reason. References [1] http:/ / en. wikipedia. org/ wiki/ Glob_(programming) [2] http:/ / www. w3. org/ 2010/ xslt-xquery-serialization Full-Text Module This module extends the W3C Full Text Recommendation [1] with some useful XQuery functions: The index can be directly accessed, full-text results can be marked with additional elements, or the relevant parts can be extracted. Moreover, the score value, which is generated by the contains text expression, can be explicitly requested from items. All functions are introduced with the ft: prefix, which is linked to the statically declared http:/ / basex. org/ modules/ ft namespace. Functions ft:search Signatures ft:search($node as node(), $text as xs:string) as text() Summary Performs a full-text index request on the specified XML node and returns all text nodes that contain the string $text. The index full-text options are used for searching, i.e., if the index terms were stemmed, the search string will be stemmed as well. Errors BASX0001 is raised if the full-text index is not available. BASX0002 is raised if a referenced node is not stored in a database (i.e., references a main-memory XML fragment). Examples • ft:search(., "QUERY") returns all text nodes of the currently opened database that contain the string "QUERY". ft:mark Full-Text Module 126 Signatures ft:mark($nodes as node()*) as node()* ft:mark($nodes as node()*, $tag as xs:string) as node()* Summary Puts a marker element around the resulting $nodes of a full-text index request. The default tag name of the marker element is mark. An alternative tag name can be chosen via the optional $tag argument. Note that the XML node to be transformed must be an internal "database" node. The transform expression can be used to apply the method to a main-memory fragment (see example). Errors BASX0002 is raised if a referenced node is not stored in a database (i.e., references a main-memory XML fragment). FOCA0002 is raised if $name is no valid QName. Examples • The following query returns ft:mark(db:open('DB')//*[text() contains text 'hello']) • The following expression returns word
copy $p :=
word
modify () return ft:mark($p[text() contains text 'word'], 'b')ft:extract
Signatures ft:extract($nodes as node()*) as node()* ft:extract($nodes as node()*, $tag as xs:string) as node()* ft:extract($nodes as node()*, $tag as xs:string, $length as xs:integer) as node()*
Summary Extracts and returns relevant parts of full-text results. It puts a marker element around the resulting $nodes of a full-text index request and chops irrelevant sections of the result. The default tag name of the marker element is mark. An alternative tag name can be chosen via the optional $tag argument. The default length of the returned text is 150 characters. An alternative length can be specified via the optional $length argument. Note that the effective text length may differ from the specified text due to formatting and readibility issues.
Errors BASX0002 is raised if a referenced node is not stored in a database (i.e., references a main-memory XML fragment). FOCA0002 is raised if $name is no valid QName.
Examples • The following query may return
ft:extract(db:open('DB')//*[text() contains text 'hello'], 'b', 1)
ft:count
Signatures ft:count($nodes as node()*) as xs:integer
Summary Returns the number of occurrences of the search terms specified in a full-text expression.
Errors BASX0002 is raised if a referenced node is not stored in a database (i.e., references a main-memory XML fragment).
Examples • ft:count(//*[text() contains text 'QUERY']) returns the xs:integer value 2 if a document contains two occurrences of the string "QUERY". Full-Text Module 127
ft:score
Signatures ft:score($item as item()*) as xs:double*
Summary Returns the score values (0.0 - 1.0) that have been attached to the specified items. 0 is returned a value if no score was attached.
Examples • ft:score('a' contains text 'a') returns the xs:double value 1.
ft:tokens
Signatures ft:tokens($db as item()) as element(value)* ft:tokens($db as item(), $prefix as xs:string) as element(value)*
Summary Returns all full-text tokens stored in the index, along with their numbers of occurrences. $db may either be an xs:string, denoting the database name, or a node stored in the database. If $prefix is specified, the returned nodes will be refined to the strings starting with that prefix. The prefix will be tokenized according to the full-text used for creating the index.
Errors BASX0001 is raised if the full-text index is not available. BASX0002 is raised if $db references a node that is not stored in a database (i.e., references a main-memory XML fragment). BASX0003 is raised if the addressed database cannot be opened.
ft:tokenize
Signatures ft:tokenize($input as xs:string) as xs:string*
Summary Tokenizes the given $input string, using the current default full-text options.
Examples • ft:tokenize("No Doubt") returns the two strings no and doubt. • declare ft-option using stemming; ft:tokenize("GIFTS") returns a single string gift.
Changelog
Version 7.1 • Added: ft:tokens(), ft:tokenize()
References
[1] http:/ / www. w3. org/ TR/ xpath-full-text-10 HTTP Module 128 HTTP Module
This module contains an XQuery function to send HTTP requests and handle HTTP responses. The function send-request, which is introduced with the http: prefix, is linked to the statically declared http://expath.org/ns/http-client namespace and based on the EXPath HTTP Client Module [9]:
http:send-request
Signatures http:send-request($request as element(http:request)?, $href as xs:string?, $bodies as item()*) as item()+ http:send-request($request as element(http:request)) as item()+ http:send-request($request as element(http:request)?, $href as xs:string?) as item()+
Summary Sends an HTTP request and interprets the corresponding response. $request contains the parameters of the HTTP request such as HTTP method and headers. In addition to this it can also contain the URI to which the request will be sent and the body of the HTTP method. If the URI is not given with the parameter $href, its value in $request is used instead. The structure of [9] http:request element follows the EXPath specification.
Notes The attribute auth-method of $request is not considered in our implementation because we are handling only basic authentication.
Examples
Status Only Simple GET request. As the attribute status-only is set to true, only the response element is returned. Query:
http:send-request(
Result:
Google Homepage Retrieve Google search home page. TagSoup [2] must be referenced in the class path in order to parse html. Query:
http:send-request(
Result:
SVG Data Content-type ending with +xml, e.g. image/svg+xml. Query:
http:send-request(
Result:
...
POST Request POST request to the BaseX REST Service, specifying a username and password. Query:
let $request :=
Result:
This module adds some useful higher-order XQuery functions, additional to the Higher-Order Functions provided by the official specification. All functions are introduced with the hof: prefix, which is linked to the statically
declared http:/ / basex. org/ modules/ hof namespace.
Functions
hof:id
Signatures hof:id($expr as item()*) as item()*
Summary Returns its argument unchanged. This function isn't useful on its own, but can be used as argument to other higher-order functions.
Examples 5 4 3 2 1
hof:const
Signatures hof:const($expr as item()*, $ignored as item()*) as item()*
Summary Returns its first argument unchanged and irgores the second. This function isn't useful on its own, but can be used as argument to other higher-order functions, e.g. when a function combining two values is expected and one only wants to retain the left one.
Examples • hof:const(42, 1337) returns 42. • With higher-order functions:
let $zip-sum := function($f, $seq1, $seq2) { sum(map-pairs($f, $seq1, $seq2)) } let $sum-all := $zip-sum(function($a, $b) { $a + $b }, ?, ?), $sum-left := $zip-sum(hof:const#2, ?, ?) return ( $sum-all((1, 1, 1, 1, 1), 1 to 5), $sum-left((1, 1, 1, 1, 1), 1 to 5) )
• Another use-case: When inserting a key into a map, $f descides how to combine the new value with a possibly existing old one. hof:const here means ignoring the old value, so that's normal insertion.
let $insert-with := function($f, $map, $k, $v) { let $old := $map($k), $new := if($old) then $f($v, $old) else $v return map:new(($map, map{ $k := $new })) } let $map := map{ 'foo' := 1 } let $add := $insert-with(function($a, $b) {$a + $b}, ?, ?, ?), $insert := $insert-with(hof:const#2, ?, ?, ?) return ( $add($map, 'foo', 2)('foo'), $insert($map, 'foo', 42)('foo') )
returns 3 42 Higher-Order Functions Module 132
hof:fold-left1
Signatures hof:fold-left1($f as function(item()*, item()) as item()*, $seq as item()+) as item()*
Summary Works the same as fn:fold-left($f, $seed, $seq), but doesn't need a seed, because the sequence must be non-empty.
Errors XPTY0004 if $seq is empty
Examples • hof:fold-left1(function($a, $b) { $a + $b }, 1 to 10) returns 55. • hof:fold-left1(function($a, $b) { $a + $b }, ()) throws XPTY0004, because $seq has to be non-empty.
hof:until
Signatures hof:until($pred as function(item()*) as xs:boolean, $f as function(item()*) as item()*, $start as item()*) as item()*
Summary Applies the function $f to the initial value $start until the predicate $pred applied to the result returns true().
Examples • hof:until(function($x) { $x ge 1000 }, function($y) { 2 * $y }, 1) returns 1024. • Calculating the square-root of a number by iteratively improving an initial guess:
let $sqrt := function($x as xs:double) as xs:double { hof:until( function($res) { abs($res * $res - $x) < 0.00001 }, function($guess) { ($guess + $x div $guess) div 2 }, $x ) } return $sqrt(25)
returns 5.000000000053722.
hof:top-k-by Introduced with Version 7.2:
Signatures hof:top-k-by($seq as item()*, $sort-key as function(item()) as item(), $k as xs:integer) as item()*
Summary Returns the $k items in $seq that are greatest when sorted by the result of $f applied to the item. The function is a much more efficient implementation of the following scheme:
( for $x in $seq order by $sort-key($x) descending return $x )[position() <= $k]
Errors XPTY0004 if $sort-key doesn't return exactly one item
Examples • hof:top-k-by(1 to 1000, hof:id#1, 5) returns 1000 999 998 997 996 • hof:top-k-by(1 to 1000, function($x) { -$x }, 3) returns 1 2 3 • hof:top-k-by(
hof:top-k-with Introduced with Version 7.2:
Signatures hof:top-k-with($seq as item()*, $lt as function(item(), item()) as xs:boolean, $k as xs:integer) as item()*
Summary Returns the $k items in $seq that are greatest when sorted in the order of the less-than predicate $lt. The function is a general version of hof:top-k-by($seq, $sort-key, $k).
Examples • hof:top-k-with(1 to 1000, function($a, $b) { $a lt $b }, 5) returns 1000 999 998 997 996 • hof:top-k-with(-5 to 5, function($a, $b) { abs($a) gt abs($b) }, 5) returns 0 1 -1 2 -2
Changelog
Version 7.2 • Added: hof:top-k-by, hof:hof:top-k-with • Removed: hof:iterate()
Version 7.0 • module added
Index Module
This module provides XQuery functions for displaying information stored in the database index structures. All
functions are introduced with the index: prefix, which is linked to the statically declared http:/ / basex. org/
modules/ index namespace.
Commonalities All functions share $db as argument, which may either reference a string, denoting the name of the addressed database, or a node from an already opened database. The following errors may be raised by all functions: • BASX0001 is raised if the index required by a function is not available. • BASX0002 is raised if $db references a node that is not stored in a database (i.e., references a main-memory XML fragment). • BASX0003 is raised if the addressed database cannot be opened.
Functions
index:facets Index Module 134
Signatures index:facets($db as item()) as xs:string index:facets($db as item(), $type as xs:string) as xs:string
Summary Returns information about possible facets and facet values on a database in document structure format. If $type is specified as flat, the function returns this information in a flat summarized version.
Examples • index:facets("DB") returns information about facets and facet values on the database DB in document structure. • index:facets("DB", "flat") returns information about facets and facet values on the database DB in a summarized flat structure.
index:texts
Signatures index:texts($db as item()) as element(value)* index:texts($db as item(), $prefix as xs:string) as element(value)*
Summary Returns all strings stored in the text index, along with their number of occurrences. If $prefix is specified, the returned nodes will be refined to the strings starting with that prefix.
index:attributes
Signatures index:attributes($db as item()) as element(value)* index:attributes($db as item(), $prefix as xs:string) as element(value)*
Summary Returns all strings stored in the attribute index, along with their number of occurrences. If $prefix is specified, the returned nodes will be refined to the strings starting with that prefix.
index:element-names
Signatures index:element-names($db as item()) as element(value)*
Summary Returns all element names stored in the index, along with their number of occurrences.
index:attribute-names
Signatures index:attribute-names($db as item()) as element(value)*
Summary Returns all attribute names stored in the index, along with their number of occurrences.
Changelog The module was introduced with Version 7.1. JSON Module 135 JSON Module
This module contains XQuery functions to parse and serialize JSON documents. All functions are preceded by the
json: prefix, which is linked to the statically declared http:/ / basex. org/ modules/ json namespace. JSON (JavaScript Object Notation) [1] is a popular data exchange format for applications written in JavaScript. As there are notable differences between JSON and XML, no mapping exists that guarantees a lossless, bidirectional conversion between JSON and XML. For this reason, we offer two sets of functions in this module:
JSON Functions json:parse and json:serialize facilitate a lossless conversion from JSON to XML and back. The transformation is based on the following rules: 1. The resulting document has a
json:parse
Signatures json:parse($input as xs:string()) as element(json)
Summary Converts the JSON document specified by $input to XML, and returns the result as element(json) instance. The converted XML document is both well readable and lossless, i.e., the converted document can be serialized back to the original JSON representation.
Errors BASX0015 is raised if the specified input cannot be parsed as JSON document.
json:serialize JSON Module 136
Signatures json:serialize($input as node()) as xs:string()
Summary Serializes the node specified by $input as JSON, and returns the result as xs:string instance. The serialized node must conform to the syntax specified by the json:parse() function. XML documents can also be serialized as JSON if the Serialization Option "method" is set to "json".
Errors BASX0016 is raised if the specified node cannot be serialized as JSON document.
Examples Example 1: Adds all JSON documents in a directory to a database Query:
let $database := "database" for $name in file:list('.', false(), '*.json') let $file := file:read-text($name) let $json := json:parse($file) return db:add($database, document { $json }, $name)
Example 2: Converts a simple JSON string to XML Query:
json:parse('{}')
Result:
Example 3: Converts a JSON string with simple objects and arrays Query:
json:parse('{ "title": "Talk On Travel Pool", "link": "http://www.flickr.com/groups/talkontravel/pool/", "description": "Travel and vacation photos from around the world.", "modified": "2009-02-02T11:10:27Z", "generator": "http://www.flickr.com/" }')
Result:
Example 4: Converts a JSON string with different data types Query: JSON Module 137
json:parse('{ "first_name": "John", "last_name": "Smith", "age": 25, "address": { "street": "21 2nd Street", "city": "New York", "code": 10021 }, "phone": [ { "type": "home", "number": "212 555-1234" }, { "type": "mobile", "number": "001327724623" } ] }')
Result:
10021
JsonML Functions json:serialize-ml and json:parse-ml are used to transform XML to JSON and back, using the JsonML [2] dialect. JsonML can be used to transform arbitrary XML documents, but namespaces, comments and processing instructions will be discarded in the transformation process. More details are found in the official JsonML documentation [3].
json:serialize-ml
Signatures json:serialize-ml($input as node()) as xs:string()
Summary Serializes the node specified by $input and returns the result as xs:string instance. XML documents can also be output in the JsonML format by setting the Serialization Option "method" to "jsonml".
Errors BASX0016 is raised if the specified value cannot be serialized.
json:parse-ml
Signatures json:parse-ml($input as xs:string()) as element()
[2] Summary Converts the JsonML document specified by $input to XML, and returns the result as element() instance. The JSON input must conform to the JsonML specification to be successfully converted.
Errors BASX0015 is raised if the specified input cannot be parsed as JsonML instance.
Examples Example 1: Converts all XML documents in a database to JsonML and writes them to disk Query:
for $doc in collection('json') let $name := document-uri($doc) let $json := json:serialize($doc) return file:write($name, $json)
Example 2: Converts a simple XML fragment to the JsonML format Query:
json:serialize-ml(
Result:
["xml"]
Example 3: Converts an XML document with elements and text Query:
json:serialize-ml(doc('flickr.xml'))
flickr.xml:
Result:
["flickr", ["title", "Talk On Travel Pool"], ["link", "http:\/\/www.flickr.com\/groups\/talkontravel\/pool\/"], ["description", "Travel and vacation photos from around the world."], ["modified", "2009-02-02T11:10:27Z"], ["generator", "http:\/\/www.flickr.com\/"]]
Example 4: Converts a document with nested elements and attributes Query:
json:serialize-ml(doc('input.xml'))
input.xml:
10021 Result:
["address", {"id":"1"}, ["last_name", "Smith"], ["age", "25"], ["address", ["street", "21 2nd Street"], ["city", "New York"], ["code", "10021"]], JSON Module 140
["phone", {"type":"home"}, "212 555-1234"]]
Changelog The module was introduced with Version 7.0.
References
[1] http:/ / www. json. org/
[2] http:/ / jsonml. org
[3] http:/ / jsonml. org/ XML
Map Module
This module contains XQuery functions for manipulating maps. All functions are preceded by the map: prefix, which is linked to the statically declared http://www.w3.org/2005/xpath-functions/map namespace. The following documentation is derived from an XQuery 3.0 Functions and Operators [6] working draft proposal written by Michael H. Kay [1], and is not part of the official standard yet. A map is an additional kind of item. It comprises a collation and a set of entries. Each entry comprises a key which is an arbitrary atomic value, and an arbitrary sequence called the associated value. Within a map, no two entries have the same key, when compared using the eq operator under the map's collation. It is not necessary that all the keys should be mutually comparable (for example, they can include a mixture of integers and strings). Key values will never be of type xs:untypedAtomic, and they will never be the xs:float or xs:double value NaN. The function call map:get($map, $key) can be used to retrieve the value associated with a given key. A map can also be viewed as a function from keys to associated values. To achieve this, a map is also a function item. The function corresponding to the map has the signature function($key as xs:anyAtomicType) as item()*. Calling the function has the same effect as calling the get function: the expression $map($key) returns the same result as map:get($map, $key). For example, if $books-by-isbn is a map whose keys are ISBNs and whose associated values are book elements, then the expression $books-by-isbn("0470192747") returns the book element with the given ISBN. The fact that a map is a function item allows it to be passed as an argument to higher-order functions that expect a function item as one of their arguments. As an example, the following query uses the higher-order function fn:map($f, $seq) to extract all bound values from a map:
let $map := map { 'foo' := 42, 'bar' := 'baz', 123 := 456 } return fn:map($map, map:keys($map))
This returns some permutation of (42, 'baz', 456). Like all other values, maps are immutable. For example, the map:remove function creates a new map by removing an entry from an existing map, but the existing map is not changed by the operation. Like sequences, maps have no identity. It is meaningful to compare the contents of two maps, but there is no way of asking whether they are "the same map": two maps with the same content are indistinguishable. Because a map is a function item, functions that apply to functions also apply to maps. A map is an anonymous function, so fn:function-name returns the empty sequence; fn:function-arity always returns 1. Maps may be compared using the fn:deep-equal function. The semantics for this function are extended so that when two items are compared, at any level of recursion, the items compare equal if they are both maps, if both use Map Module 141
the same collation, if both contain the same set of keys (compared using the eq operator), without regard to ordering, and if for each key that is present in both maps, the associated values are deep-equal. When comparing maps, the maps' collation is used rather than the collation supplied as an argument to the fn:deep-equal function. There is no operation to atomize a map or convert it to a string. The following XQuery snippet shows how the contents of a map can be serialized:
let $map := map { 1:='a', 2:='b' } return string-join( for $m in map:keys($map) return concat($m, ':=', $map($m)), ', ' )
Some examples use the map $week defined as:
declare variable $week as map(*) := map { 0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag" };
map:collation
Signatures map:collation($map as map(*)) as xs:string
Summary Returns the collation URI of the map supplied as $map.
map:contains
Signatures map:contains($map as map(*), $key as item()) as xs:boolean
Summary Returns true if the map supplied as $map contains an entry with a key equal to the supplied value of $key; otherwise it returns false. The equality comparison uses the map's collation; no error occurs if the map contains keys that are not comparable with the supplied $key. If the supplied key is xs:untypedAtomic, it is converted to xs:string. If the supplied key is the xs:float or xs:double value NaN, the function returns false.
Examples • map:contains($week, 2) returns true(). • map:contains($week, 9) returns false(). • map:contains(map{}, "xyz") returns false(). • map:contains(map{ "xyz":=23 }, "xyz") returns true(). Map Module 142
map:entry
Signatures map:entry($key as item(), $value as item()*) as map(*)
Summary Creates a new map containing a single entry. The collation of the new map is the default collation from the static context. The key of the entry in the new map is $key, and its associated value is $value. If the supplied key is xs:untypedAtomic, it is converted to xs:string. If the supplied key is the xs:float or xs:double value NaN, the supplied $map is returned unchanged. The function map:entry is intended primarily for use in conjunction with the function map:new. For example, a map containing seven entries may be constructed like this:
map:new(( map:entry("Su", "Sunday"), map:entry("Mo", "Monday"), map:entry("Tu", "Tuesday"), map:entry("We", "Wednesday"), map:entry("Th", "Thursday"), map:entry("Fr", "Friday"), map:entry("Sa", "Saturday") ))
Unlike the map{ ... } expression, this technique can be used to construct a map with a variable number of entries, for example:
map:new(for $b in //book return map:entry($b/isbn, $b))
Examples • map:entry("M", "Monday") creates a map with the values { "M":="Monday" }.
map:get
Signatures map:get($map as map(*), $key as item()) as item()*
Summary Returns the value associated with a supplied key in a given map. This function attempts to find an entry within the map supplied as $map that has a key equal to the supplied value of $key. If there is such an entry, it returns the associated value; otherwise it returns an empty sequence. The equality comparison uses the map's collation; no error occurs if the map contains keys that are not comparable with the supplied $key. If the supplied key is xs:untypedAtomic, it is converted to xs:string. If the supplied key is the xs:float or xs:double value NaN, the function returns an empty sequence. A return value of () from map:get could indicate that the key is present in the map with an associated value of (), or it could indicate that the key is not present in the map. The two cases can be distinguished by calling map:contains. Invoking the map as a function item has the same effect as calling get: that is, when $map is a map, the expression $map($K) is equivalent to get($map, $K). Similarly, the expression get(get(get($map, 'employee'), 'name'), 'first') can be written as $map('employee')('name')('first').
Examples • map:get($week, 4) returns "Donnerstag". • map:get($week, 9) returns (). (When the key is not present, the function returns an empty sequence.). • map:get(map:entry(7,())), 7) returns (). (An empty sequence as the result can also signify that the key is present and the associated value is an empty sequence.).
map:keys Map Module 143
Signatures map:keys($map as map(*)) as xs:anyAtomicType*
Summary Returns a sequence containing all the key values present in a map. The function takes any map as its $map argument and returns the keys that are present in the map as a sequence of atomic values, in implementation-dependent order.
Examples • map:keys(map{ 1:="yes", 2:="no" }) returns some permutation of (1,2) (the result is in implementation-dependent order).
map:new
Signatures map:new() as map(*) map:new($maps as map(*)*) as map(*) map:new($maps as map(*)*, $coll as xs:string) as map(*)
Summary Constructs and returns a new map. The zero-argument form of the function returns an empty map whose collation is the default collation in the static context. It is equivalent to calling the one-argument form of the function with an empty sequence as the value of the first argument. The one-argument form of the function returns a map that is formed by combining the contents of the maps supplied in the $maps argument. It is equivalent to calling the two-argument form of the function with the default collation from the static context as the second argument. The two-argument form of the function returns a map that is formed by combining the contents of the maps supplied in the $maps argument. The collation of the new map is the value of the $coll argument. The supplied maps are combined as follows: 1. There is one entry in the new map for each distinct key value present in the union of the input maps, where keys are considered distinct according to the rules of the distinct-values function with $coll as the collation. 2. The associated value for each such key is taken from the last map in the input sequence $maps that contains an entry with this key. If this map contains more than one entry with this key (which can happen if its collation is different from that of the new map) then it is implementation-dependent which of them is selected.
There is no requirement that the supplied input maps should have the same or compatible types. The type of a map (for example map(xs:integer, xs:string)) is descriptive of the entries it currently contains, but is not a constraint on how the map may be combined with other maps.
Examples • map:new() creates an empty map. • map:new(()) creates an empty map. • map:new(map:entry(0, "no"), map:entry(1, "yes")) creates a map with the values { 0:="no", 1:="yes" }. • map:new(($week, map{ 7:="Unbekannt" })) creates a map with the values { 0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag", 7:="Unbekannt" }. • map:new(($week, map{ 6:="Sonnabend" })) creates a map with the values { 0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Sonnabend" }.
map:remove Map Module 144
Signatures map:remove($map as map(*), $key as item()) as map(*)
Summary Constructs a new map by removing an entry from an existing map. The collation of the new map is the same as the collation of the map supplied as $map. The entries in the new map correspond to the entries of $map, excluding any entry whose key is equal to $key. No failure occurs if the input map contains no entry with the supplied key; the input map is returned unchanged
Examples • map:remove($week, 4) creates a map with the values { 0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 5:="Freitag", 6:="Samstag" }. • map:remove($week, 23) creates a map with the values { 0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag" }.
map:size
Signatures map:size($map as map(*)) as xs:integer
Summary Returns a the number of entries in the supplied map. The function takes any map as its $map argument and returns the number of entries that are present in the map.
Examples • map:size(map:new()) returns 0. • map:size(map{ "true":=1, "false":=0 }) returns 2.
References
[1] http:/ / en. wikipedia. org/ wiki/ Michael_Kay_(software_engineer)
Math Module
The math module defines XQuery functions to perform mathematical operations, such as pi, asin and acos. All functions are preceded by the math: prefix, which is linked to the statically declared http://www.w3.org/2005/xpath-functions/math namespace. Some of the functions have also been specified in the Functions and Operators Specification [6] of the upcoming XQuery 3.0 Recommendation.
math:pi
Signatures math:pi() as xs:double
Summary Returns the xs:double value of the mathematical constant π whose lexical representation is 3.141592653589793.
Examples • 2*math:pi() returns 6.283185307179586e0. • 60 * (math:pi() div 180) converts an angle of 60 degrees to radians. Math Module 145
math:e
Signatures math:e() as xs:double
Summary Returns the xs:double value of the mathematical constant e whose lexical representation is 2.718281828459045.
Examples • 5*math:e() returns 13.591409142295225.
math:sqrt
Signatures math:sqrt($arg as xs:double?) as xs:double?
Summary Returns the square root of $arg. If $arg is the empty sequence, the empty sequence is returned. Otherwise the result is the xs:double value of the mathematical square root of $arg.
math:sin
Signatures math:sin($arg as xs:double?) as xs:double?
Summary Returns the sine of the $arg, expressed in radians. If $arg is the empty sequence, the empty sequence is returned. Otherwise the result is the sine of $arg, treated as an angle in radians.
math:cos
Signatures math:cos($arg as xs:double?) as xs:double?
Summary Returns the cosine of $arg, expressed in radians. If $arg is the empty sequence, the empty sequence is returned. Otherwise the result is the cosine of $arg, treated as an angle in radians.
math:tan
Signatures math:tan($ as xs:double?) as xs:double?
Summary Returns the tangent of $arg, expressed in radians. If $arg is the empty sequence, the empty sequence is returned. Otherwise the result is the tangent of $arg, treated as an angle in radians. Math Module 146
math:asin
Signatures math:asin($arg as xs:double?) as xs:double?
Summary Returns the arc sine of $arg. If $arg is the empty sequence, the empty sequence is returned. Otherwise the result is the arc sine of $arg, returned as an angle in radians in the range -π/2 to +π/2.
math:acos
Signatures math:acos($arg as xs:double?) as xs:double?
Summary Returns the arc cosine of $arg. If $arg is the empty sequence, the empty sequence is returned. Otherwise the result is the arc cosine of $arg, returned as an angle in radians in the range 0 to +π.
math:atan
Signatures math:atan($arg as xs:double?) as xs:double?
Summary Returns the arc tangent of $arg. If $arg is the empty sequence, the empty sequence is returned. Otherwise the result is the arc tangent of $arg, returned as an angle in radians in the range -π/2 to +π/2.
math:atan2
Signatures math:atan2($arg1 as xs:double?, $arg2 as xs:double) as xs:double?
Summary Returns the arc tangent of $arg1 divided by $arg2, the result being in the range -π/2 to +π/2 radians. If $arg1 is the empty sequence, the empty sequence is returned. Otherwise the result is the arc tangent of $arg1 divided by $arg2, returned as an angle in radians in the range -π to +π.
math:pow
Signatures math:pow($arg1 as xs:double?, $arg2 as xs:double) as xs:double?
Summary Returns $arg1 raised to the power of $arg2. If $arg1 is the empty sequence, the empty sequence is returned. Otherwise the result is the $arg1 raised to the power of $arg2.
Examples • math:pow(2, 3) returns 8.
math:exp Math Module 147
Signatures math:exp($arg as xs:double?) as xs:double?
Summary Returns e raised to the power of $arg. If $arg is the empty sequence, the empty sequence is returned. Otherwise the result is the value of e raised to the power of $arg.
Examples • math:exp(1) returns e.
math:log
Signatures math:log($arg as xs:double?) as xs:double?
Summary Returns the natural logarithm of $arg. If $arg is the empty sequence, the empty sequence is returned. Otherwise the result is the natural logarithm (base e) of $arg.
Examples • math:log(math:e()) returns 1.
math:log10
Signatures math:log10($arg as xs:double?) as xs:double?
Summary Returns the base 10 logarithm of $arg. If $arg is the empty sequence, the empty sequence is returned. Otherwise the result is the base 10 logarithm of $arg.
Examples • math:log(100) returns 2.
math:random
Signatures math:random() as xs:double?
Summary Returns a random xs:double value between 0.0 and 1.0.
math:sinh
Signatures math:sinh($arg as xs:double?) as xs:double?
Summary Returns the hyperbolic sine of $arg. If $arg is the empty sequence, the empty sequence is returned. Otherwise the result is the hyperbolic sine of $arg.
Examples • math:sinh(0) returns 0. Math Module 148
math:cosh
Signatures math:cosh($arg as xs:double?) as xs:double?
Summary Returns the hyperbolic cosine of $arg. If $arg is the empty sequence, the empty sequence is returned. Otherwise the result is the hyperbolic cosine of $arg.
Examples • math:cosh(0) returns 1.
math:tanh
Signatures math:tanh($arg as xs:double?) as xs:double?
Summary Returns the hyperbolic tangent of $arg. If $arg is the empty sequence, the empty sequence is returned. Otherwise the result is the hyperbolic tangent of $arg.
Examples • math:tanh(100) returns 1.
Repository Module
This module contains XQuery functions for managing EXPath packages [5]. All functions are preceded by the repo: prefix which is linked to the namespace http://basex.org/modules/repo. You can read more about BaseX implementation of the EXPath Packaging API here.
Functions
repo:install
Signatures repo:install($path as xs:string) as empty-sequence()
Summary Installs a package. The parameter $path indicates the path to the package.
Errors PACK0001 is raised if the package does not exist. PACK0002 is raised if the package is already installed. PACK0003 is raised if the package to be installed requires a package which is still not installed. PACK0004 is raised if the package descriptor is invalid. PACK0005 is raised if the module contained in the package to be installed is already installed as part of another package. PACK0006 is raised if the package cannot be parsed. PACK0009 is raised if the package version is not supported. PACK0010 is raised if the package contains an invalid JAR descriptor. PACK0011 is raised if the package contains a JAR descriptor but it cannot be read. Repository Module 149
repo:delete
Signatures repo:delete($pkg as xs:string) as empty-sequence()
Summary Deletes a package. The parameter $pkg indicates either the package name as specified in the package descriptor or the name of the directory where the package is installed.
Errors PACK0007 is raised if the package cannot be deleted. PACK0008 is raised if another package depends on the package to be deleted.
repo:list Updated in Version 7.2:
Signatures repo:list() as element(package)*
Summary Lists the names and versions of all currently installed packages.
Changelog
Version 7.2 • Updated: repo:list() now returns nodes The module was introduced with Version 7.1.
SQL Module
The SQL Module contains XQuery functions to access relational databases from XQuery using SQL. With this module, you can execute query, update and prepared statements, and the result sets are returned as sequences of XML elements representing tuples. Each element has children representing the columns returned by the SQL statement. All functions dealing with access to relational databases use the sql prefix, which is linked to the
statically declared http:/ / basex. org/ modules/ sql namespace.
Functions
sql:init SQL Module 150
Signatures sql:init($class as xs:string) as empty-sequence()
Summary This function initializes a JDBC driver specified via $class. This step might be superfluous if the SQL database is not embedded.
Errors FOSQ0007 is raised if the specified driver class is not found.
sql:connect
Signatures sql:connect($url as xs:string) as xs:integer sql:connect($url as xs:string, $user as xs:string, $password as xs:string) as xs:integer sql:connect($url as xs:string, $user as xs:string, $password as xs:string, $options as item()) as xs:integer
Summary This function establishes a connection to a relational database. As a result a connection handle is returned. The parameter $url is the URL of the database and shall be of the form: jdbc:
Errors FOSQ0001 is raised if an SQL exception occurs, e.g. missing JDBC driver or not existing relation.
sql:execute Once a connection is established, the returned connection handle can be used to execute queries on the database. Our SQL module supports both direct queries and prepared statements.
Signatures sql:execute($connection as xs:integer, $item as item()) as element()*
Summary This function executes a query, update or prepared statement. The parameter $id specifies either a connection handle or a prepared statement handle. The parameter $item is either a string representing an SQL statement or an element
element sql:parameters { element sql:parameter { attribute type { "int"|"string"|"boolean"|"date"|"double"|"float"|"short"|"time"|"timestamp" }, attribute null { "true"|"false" }?, text }+ }?
Errors FOSQ0001 is raised if an SQL exception occurs, e.g. not existing relation is retrieved. FOSQ0002 is raised if a wrong connection handle or prepared statement handle is passed. FOSQ0003 is raised if the number of
sql:prepare
Signatures sql:prepare($connection as xs:integer, $statement as xs:string) as xs:integer
Summary This function prepares a statement and returns a handle to it. The parameter $connection indicates the connection handle to be used. The parameter $statement is a string representing an SQL statement with one or more '?' placeholders. If the value of a field has to be set to NULL, then the attribute null of the element
Errors FOSQ0001 is raised if an SQL exception occurs. FOSQ0002 is raised if a wrong connection handle is passed.
sql:commit
Signatures sql:commit($connection as xs:integer) as xs:element?
Summary This function commits the changes made to a relational database. $connection specifies the connection handle.
Errors FOSQ0001 is raised if an SQL exception occurs. FOSQ0002 is raised if a wrong connection handle is passed.
sql:rollback
Signatures sql:rollback($connection as xs:integer) as xs:element?
Summary This function rolls back the changes made to a relational database. $connection specifies the connection handle.
Errors FOSQ0001 is raised if an SQL exception occurs. FOSQ0002 is raised if a wrong connection handle is passed.
sql:close
Signatures sql:close($connection as xs:integer) as xs:element?
Summary This function closes a connection to a relational database. $connection specifies the connection handle.
Errors FOSQ0001 is raised if an SQL exception occurs. FOSQ0002 is raised if a wrong connection handle is passed.
Examples
Direct queries A simple select statement can be executed on the following way:
let $conn := sql:connect("jdbc:postgresql://localhost:5432/coffeehouse") return sql:execute($conn, "SELECT * FROM coffees WHERE price < 10")
The result will look like:
Prepared Statements A prepared select statement can be executed in the following way:
(: Establish a connection :) let $conn := sql:connect("jdbc:postgresql://localhost:5432/coffeehouse") (: Obtain a handle to a prepared statement :) let $prep := sql:prepare($conn, "SELECT * FROM coffees WHERE price < ? AND cof_name = ?") (: Values and types of prepared statement parameters :) let $params :=
Changelog The module was introduced with Version 7.0. Utility Module 153 Utility Module
This module contains auxiliary XQuery Functions, which can be used to perform data conversions and test and profile code snippets. All functions are preceded by the util: prefix, which is linked to the statically declared
http:/ / basex. org/ modules/ util namespace.
Conversion
util:format
Signatures util:format($format as xs:string, $item1 as item(), ...) as xs:string
[1] Summary Returns a formatted string. $item1 and all following items are applied to the $format string, according to Java’s printf syntax .
Examples • util:format("%b", true()) returns true. • util:format("%06d", 256) returns 000256. • util:format("%e", 1234.5678) returns 1.234568e+03.
util:integer-to-base
Signatures util:integer-to-base($num as xs:integer, $base as xs:integer) as xs:string
Summary Converts $num to base $base, interpreting it as a 64-bit unsigned integer. The first $base elements of the sequence '0',..,'9','a',..,'z' are used as digits. Valid bases are 2, .., 36.
Examples • util:integer-to-base(-1, 16) returns the hexadecimal string 'ffffffffffffffff'. • util:integer-to-base(22, 5) returns '42'.
util:integer-from-base
Signatures util:integer-from-base($str as xs:string, $base as xs:integer) as xs:integer
Summary Decodes an xs:integer from $str, assuming that it's encoded in base $base. The first $base elements of the sequence '0',..,'9','a',..,'z' are allowed as digits, case doesn't matter. Valid bases are 2, .., 36. If $str contains more than 64 bits of information, the result is truncated arbitarily.
Examples • util:integer-from-base('ffffffffffffffff', 16) returns -1. • util:integer-from-base('CAFEBABE', 16) returns 3405691582. • util:integer-from-base('42', 5) returns 22. • util:integer-from-base(util:integer-to-base(123, 7), 7) returns 123.
util:to-bytes Utility Module 154
Signatures util:to-bytes($bin as xs:binary) as xs:byte*
Summary Extracts the bytes from the given binary data $bin.
Examples • util:to-bytes(xs:base64Binary('QmFzZVggaXMgY29vbA==')) returns the sequence (66, 97, 115, 101, 88, 32, 105, 115, 32, 99, 111, 111, 108). • util:to-bytes(xs:hexBinary("4261736558")) returns the sequence (66 97 115 101 88).
util:to-string
Signatures util:to-string($bytes as xs:binary, $encoding as xs:string) as xs:string
Summary Converts the specifed bytes to a string, using the optional $encoding.
Examples • util:to-string(xs:hexBinary('48656c6c6f576f726c64')) returns the string HelloWorld.
Reflection, Introspection
util:eval
Signatures util:eval($expr as xs:string) as item()*
Summary Evaluates $expr as XQuery expression at runtime and returns the resulting items.
Examples • util:eval("1+3") returns 4.
util:run
Signatures util:run($input as xs:string) as item()*
Summary Opens $input as file, evaluates it as XQuery expression at runtime, and returns the resulting items.
util:path
Signatures util:path() as xs:string?
Summary Returns the full path to the file containing the executed query. An empty sequence is returned if no such file exists, or if the filename is not known to the query processor. Utility Module 155
util:type Added in Version 7.2.
Signatures util:type($expr as item()*) as item()*
Summary Similar to fn:trace($expr, $msg), but instead of a user-defined message, it emits the compile-time type and estimated result size of its argument.
Profiling
util:mem Along with Version 7.2, the $label argument was added to the function:
Signatures util:mem($expr as item()) as item()* util:mem($expr as item(), $cache as xs:boolean) as item()* util:mem($expr as item(), $cache as xs:boolean, $label as xs:string) as item()*
Summary Measures the memory allocated by evaluating $expr and sends it to standard error or, if the GUI is used, to the Info View. If $cache is set to true(), the result will be temporarily cached. This way, a potential iterative execution of the expression (which often yields different memory usage) is blocked. A third, optional argument $label may be specified to tag the profiling result.
Examples • util:mb("1 to 100000") may output 0 Bytes. • util:mb("1 to 100000", true()) may output 26.678 mb.
util:time Along with Version 7.2, the $label argument was added to the function:
Signatures util:time($expr as item()) as item()* util:time($expr as item(), $cache as xs:boolean) as item()* util:time($expr as item(), $cache as xs:boolean, $label as xs:string) as item()*
Summary Measures the time needed to evaluate $expr and sends it to standard error or, if the GUI is used, to the Info View. If $cache is set to true(), the result will be temporarily cached. This way, a potential iterative execution of the expression (which often yields different memory usage) is blocked. A third, optional argument $label may be specified to tag the profiling result.
Examples • util:time("1 to 100000") may output 25.69 ms. • util:time("1 to 100000", true()) may output 208.12 ms.
Cryptography
util:md5 Utility Module 156
Signatures util:md5($str as xs:string) as xs:hexBinary
Summary Calculates the MD5 hash of the given string $str.
Examples • util:md5("") returns 'D41D8CD98F00B204E9800998ECF8427E'. • util:md5('BaseX') returns '0D65185C9E296311C0A2200179E479A2'.
util:sha1
Signatures util:sha1($str as xs:string) as xs:hexBinary
Summary Calculates the SHA1 hash of the given string $str.
Examples • util:sha1("") returns 'DA39A3EE5E6B4B0D3255BFEF95601890AFD80709'. • util:sha1("BaseX") returns '3AD5958F0F27D5AFFDCA2957560F121D0597A4ED'.
util:crc32
Signatures util:crc32($str as xs:string) as xs:hexBinary
Summary Calculates the CRC32 check sum of the given string $str.
Examples • util:crc32("") returns '00000000'. • util:crc32("BaseX") returns '4C06FC7F'.
util:uuid
Signatures util:uuid() as xs:string
Summary Creates a random universally unique identifier (UUID), represented as 128-bit value.
Examples • util:uuid() ne util:uuid() will (most probably) return the boolean value true.
Changelog
Version 7.2 • Updated: util:time(), util:mem(), util:type()
Version 7.1 • Added: util:path(), util:time(), util:mem() • Removed: util:mb(), util:ms()
Version 7.0 • Added: util:to-string(), util:uuid()
References
[1] http:/ / download. oracle. com/ javase/ 1. 5. 0/ docs/ api/ java/ util/ Formatter. html#syntax XSLT Module 157 XSLT Module
This module contains XQuery functions and variables to perform XSLT transformations. All functions are preceded
by the xslt: prefix, which is linked to the statically declared http:/ / basex. org/ modules/ xslt namespace. By default, this module uses Java’s XSLT 1.0 Xalan implementation to transform documents. XSLT 2.0 is used instead if Version 9.x of the Saxon XSLT Processor [1] (saxon9he.jar, saxon9pe.jar, saxon9ee.jar) is found in the classpath. A custom transformer can be specified by overwriting the system property javax.xml.transform.TransformerFactory, as shown in the following Java example:
System.setProperty("javax.xml.transform.TransformerFactory", "org.custom.xslt.TransformerFactoryImpl"); Context ctx = new Context(); String result = new XQuery("xslt:transform('...', '...')").execute(ctx); ... ctx.close();
$xslt:processor
Signatures $xslt:processor as xs:string
Summary This variable contains the name of the applied XSLT processor, or the path to a custom implementation (currently: "Java", "Saxon EE", "Saxon PE", or "Saxon HE").
$xslt:version
Signatures $xslt:version as xs:string
Summary This variable contains the supported XSLT version (currently: "1.0" or "2.0"). "Unknown" is returned if a custom implementation was chosen.
xslt:transform
Signatures xslt:transform($input as item(), $stylesheet as item()) as node() xslt:transform($input as item(), $stylesheet as item(), $params as item()) as node()
Summary Transforms the document specified by $input, using the XSLT template specified by $stylesheet, and returns the result as node() instance. $input and $stylesheet can be specified as • xs:string, containing the path to the document, • xs:string, containing the document in its string representation, or • node(), containing the actual document. The $params argument can be used to bind variables to a stylesheet. It can be specified as • element(xslt:parameters):
Examples Example 1: Basic XSL transformation with dummy document and without parameters Query:
xslt:transform(
basic.xslt
Result:
Example 2: XSLT transformation of an input document Query:
let $in :=
let $style :=
Books
return xslt:transform($in, $style)
Result: XSLT Module 159
Books
- XSLT Programmer´s Reference: Michael H. Kay
- XSLT: Doug Tidwell, Simon St. Laurent, Robert Romano
Example 3: Assigning a variable to an XSLT stylesheet Query:
let $in :=
variable.xslt
Result:
References
[1] http:/ / www. saxonica. com/ ZIP Module 160 ZIP Module
This module contains XQuery functions to handle ZIP archives. The contents of ZIP files can be extracted and listed, and new archives can be created. All functions are preceded by the zip: prefix, which is linked to the statically declared http://expath.org/ns/zip namespace. The module is based on the EXPath ZIP Module [11]. Another page in this Wiki demonstrates how to modify Word documents with the ZIP module.
zip:binary-entry
Signatures zip:binary-entry($uri as xs:string, $path as xs:string) as xs:base64Binary
Summary Extracts the binary file at $path within the ZIP file located at $uri and returns it as an xs:base64Binary item.
Errors FOZP0001 is raised if the specified path does not exist. FOZP0003 is raised if the operation fails for some other reason.
zip:text-entry
Signatures zip:text-entry($uri as xs:string, $path as xs:string) as xs:string zip:text-entry($uri as xs:string, $path as xs:string, $encoding as xs:string) as xs:string
Summary Extracts the text file at $path within the ZIP file located at $uri and returns it as an xs:string item. An optional encoding can be specified via $encoding.
Errors FOZP0001 is raised if the specified path does not exist. FOZP0003 is raised if the operation fails for some other reason.
zip:xml-entry
Signatures zip:xml-entry($uri as xs:string, $path as xs:string) as document-node()
Summary Extracts the XML file at $path within the ZIP file located at $uri and returns it as a document node.
Errors FODC0006 is raised if the addressed file is not well-formed. FOZP0001 is raised if the specified path does not exist. FOZP0003 is raised if the operation fails for some other reason.
zip:html-entry
Signatures zip:html-entry($uri as xs:string, $path as xs:string) as document-node()
Summary Extracts the HTML file at $path within the ZIP file located at $uri and returns it as a document node. The file is converted to [2] XML first if Tagsoup is found in the classpath.
Errors FODC0006 is raised if the addressed file is not well-formed, or cannot be converted to correct XML. FOZP0001 is raised if the specified path does not exist. FOZP0003 is raised if the operation fails for some other reason. ZIP Module 161
zip:entries
Signatures zip:entries($uri as xs:string) as element(zip:file)
[1] Summary Generates an ZIP XML Representation of the hierarchical structure of the ZIP file located at $uri and returns it as an element node. The file contents are not returned by this function.
Errors FOZP0001 is raised if the specified path does not exist. FOZP0003 is raised if the operation fails for some other reason.
Examples • If the ZIP archive archive.zip is empty, zip:entries('archive.zip') returns
zip:zip-file
Signatures zip:zip-file($zip as element(zip:file)) as empty-sequence()
[1] Summary Creates a new ZIP archive with the characteristics described by $zip, the ZIP XML Representation .
Errors FOZP0001 is raised if an addressed file does not exist. FOZP0002 is raised if entries in the ZIP archive description are unknown, missing, or invalid. FOZP0003 is raised if the operation fails for some other reason. Serialization Errors are raised if an inlined XML fragment cannot be successfully serialized.
Examples • The following function creates a file archive.zip with the file file.txt inside:
zip:zip-file(
• The following function creates a file archive.zip. It contains one file readme with the content "thanks":
zip:zip-file(
zip:update-entries
Signatures zip:update-entries($zip as element(zip:file), $output as xs:string) as empty-sequence()
Summary Updates an existing ZIP archive or creates a modifed copy, based on the characteristics described by $zip, the ZIP XML [1] Representation . The $output argument is the URI where the modified ZIP file is copied to.
Errors FOZP0001 is raised if an addressed file does not exist. FOZP0002 is raised if entries in the ZIP archive description are unknown, missing, or invalid. FOZP0003 is raised if the operation fails for some other reason. Serialization Errors are raised if an inlined XML fragment cannot be successfully serialized.
Examples • The following function creates a copy new.zip of the existing archive.zip file:
zip:update-entries(zip:entries('archive.zip'), 'new.zip')
• The following function deletes all PNG files from archive.zip:
declare namespace zip = "http://expath.org/ns/zip"; copy $doc := zip:entries('archive.zip') modify delete node $doc//zip:entry[ends-with(lower-case(@name), '.png')] return zip:update-entries($doc, 'archive.zip') ZIP Module 162
References
[1] http:/ / expath. org/ spec/ zip#spec-file-handling-elements-sect
ZIP Module: Word Documents
Contents of Word and Open Office documents can be modified with the help of the ZIP Module, as demonstrated in the following example:
Example 1. Create a new Word document writing "HELLO WORLD!" in it and save it as "HelloWorld.docx". 2. Get archive structure of "HelloWorld.docx" using the following query:
zip:entries("HelloWorld.docx")
3. Look at the XML representation and locate "document.xml" 4. Get the XML representation of "document.xml" with the following query:
zip:xml-entry("HelloWorld.docx", "word/document.xml")
5. Look at the XML representation of "document.xml" 6. Locate the element containing text "HELLO WORLD!" in "document.xml":
for $i in zip:xml-entry("HelloWorld.docx", "word/document.xml")//* where contains($i/text(), "HELLO WORLD!") return $i
7. Modify the contents of the element:
declare variable $input := "HelloWorld.docx"; declare variable $output := "HelloUniverse.docx";
let $modified := copy $c := zip:xml-entry($input, "word/document.xml") modify replace value of node $c//*[text() = "HELLO WORLD!"] with "HELLO UNIVERSE!" return $c let $target := copy $c := zip:entries($input) modify insert node $modified into $c//*[@name = "document.xml"] return $c return zip:update-entries($target, $output)
8. Open the newly created Word document named "HelloUniverse.docx" 9. You can also modify the font of the Word document:
declare variable $input := "Arial.docx"; declare variable $output := "Times.docx"; ZIP Module: Word Documents 163
let $modified := copy $c := zip:xml-entry($input, "word/document.xml") modify for $i in $c//@*[data() = "Arial"] return replace value of node $i with "Times New Roman" return $c let $target := copy $c := zip:entries($input) modify insert node $modified into $c//*[@name = "document.xml"] return $c return zip:update-entries($target, $output)
10. Open the new created Word document named "HelloWorldTimes.docx" 164
Developing
Developing
This page is one of the Main Sections of the documentation. It provides useful information for developers. Here you can find information on various alternatives to integrate BaseX into your own project.
Source Code and Integration • Integrate: Integrate BaseX into your IDE • Git: Learn how to work with Git • Maven: Embed BaseX into your own projects, or compile a development version of BaseX yourself • Releases: Learn more about the locations where you find our releases, snapshots, and old versions • Translations: Contribute a new translation to BaseX
HTTP Services • REST: Details on the REST API • RESTXQ: Details on the new RESTXQ API (introduced with Version 7.2) • WebDAV: Details on the WebDAV Protocol
Client APIs • Clients: Communicate with the BaseX server from different programming languages (C#, PHP, Python, Perl, C, etc.) • Server Protocol: Protocol for implementing new language bindings • Java Examples: Code examples for developing with the BaseX, REST, XML:DB, and XQJ APIs
JavaDoc The project's JavaDoc [1] can be explored online.
References
[1] http:/ / docs. basex. org/ javadoc Integrate 165 Integrate
This page is part of the Developer Section. It describes how to get the BaseX sources compiled and running on your system.
Prerequisites • BaseX is being developed with the Eclipse [1] environment. Other IDEs are used as well in our community, but are not supported by our team. • The EGit [1] plugin can be used to check out the latest sources from our repository within Eclipse. • The m2eclipse [2] plugin is required to work with packages other than the main project; it adds Maven support to Eclipse. • Additional coding guidelines are defined via Checkstyle and can be integrated with the eclipse-cs [3] plugin. • Other Eclipse plugins we frequently use are FindBugs [4] to analyze Java byte code, and Core Tools [5] to find unreferenced members. You may as well use the standalone version of Maven to compile and run the project.
Check Out To get some help on how to check out BaseX and its sub projects from the GitHub Repositories [6], and how to optionally use BaseX on command line, please have a look at our Git Tutorial. The following repositories are available: 1. basex [7] is the main project 2. basex-api [8] contains the BaseX APIs (XQJ, XMLDB, and bindings in other languages) and HTTP Services (REST, RESTXQ, WebDAV) 3. basex-examples [9] includes some examples code for BaseX 4. basex-tests [10] contains several correctness and stress tests
Start in Eclipse 1. Press Run → Run… 2. Create a new "Java Application" launch configuration 3. Select "basex" as "Project" 4. Choose a "Main class" (e.g., org.basex.BaseXGUI for the graphical user interface) 5. Launch the project via Run
References
[1] http:/ / www. eclipse. org/ egit/
[2] http:/ / m2eclipse. sonatype. org
[3] http:/ / eclipse-cs. sourceforge. net
[4] http:/ / findbugs. sourceforge. net/
[5] http:/ / www. eclipse. org/ eclipse/ platform-core/ downloads. php
[6] https:/ / github. com/ BaseXdb
[7] https:/ / github. com/ BaseXdb/ basex
[8] https:/ / github. com/ BaseXdb/ basex-api
[9] https:/ / github. com/ BaseXdb/ basex-examples
[10] https:/ / github. com/ BaseXdb/ basex-tests Git 166 Git
This page is part of the Developer Section. It describes how to use git [1] to manage the BaseX sources.
Using Git to contribute to BaseX Our team uses git and GitHub [2] to manage the source code. All team members have read+write access to the repository, and external contributors are welcome to fork the project. Git makes it easy to retain a full copy of the repository for yourself. To get started and running, simply fork BaseX. If forking sounds unfamiliar to you, we suggest to check out the git introduction below. You can then build BaseX with Maven. Using Eclipse is optional.
Using Git & Eclipse
1. (Optional) Head over to https:/ / github. com/ BaseXdb and create an account 2. Fork BaseX, so you have a version on your own 3. Make yourself familiar with git (see the end of this page) 4. Open Eclipse
5. Install egit (Eclipse: Help → Marketplace → Search for egit or get it from http:/ / www. eclipse. org/ egit/ )
Clone
• In the Package Explorer to the left use right-click and choose Import... • Select "Projects from Git" and click Next > • Click "Clone..." to create a local copy of the remote repository. This copy will include the full project history • Copy & Paste the github URI in the Location field. If you want to use SSH make sure you provided GitHub with your public key to allow write-access. If in doubt use the HTTPS URI and authenticate yourself with your GitHub credentials. • Select the master branch (or arbitrary branches you like) • Now choose a location where the local repository is stored: Create
Create the project
• Select our newly cloned repository and click Next • Select "Import Existing Projects" and depending on your Eclipse version enable automatic sharing. More recent versions will not offer this feature as sharing is enabled by default. • Click next to select the Project to import • Check "basex" to checkout and click finish • You are now ready to contribute.
EGit & SSH
EGit uses the JSch [3] library which is, however, reported [4] to have problems with RSA SSH keys in linux and possibly other platforms. A solution would be to use the variable GIT_SSH and assign it a path to the native SSH executable. According to this [5] change in EGit, the plugin will try to use a native SSH implementation instead of JSch (this, however, may not always work either :( ).
Using Git on Command-Line
Note: this is not intended to be a complete git reference; it's purpose is to quickly introduce BaseX developers to the most commonly used git commands in the context of the BaseX project.
Preparation
1. Create a GitHub user account: here [6] (your github user name will be referenced as $username) 2. Set up SSH access to GitHub as described here [7] 3. Create a fork of one of the BaseXdb projects (it will be referenced as $project) 4. Choose a directory where the project will be created and make it your working directory (e. g. /home/user/myprojects) Git 168 Git 169 Git 170
Clone Your Personal Repository $ git clone [email protected]:$username/$project.git Cloning into $project... Enter passphrase for key '/home/user/.ssh/id_rsa': ...
$ ls -d -1 $PWD/* /home/user/myprojects/$project
Note that git automatically creates a directory where the repository content will be checked out.
List Remote Repositories $ git remote -v origin [email protected]:$username/$project.git (fetch) origin [email protected]:$username/$project.git (push)
Currently, there is only one remote repository; it is automatically registered during the clone operation. Git remembers this repository as the default repository for push/pull operations.
List Local Changes After some files have been changed locally, the changes can be seen as follows:
$ git diff diff --git a/readme.txt b/readme.txt index fabaeaa..cd09568 100644 --- a/readme.txt +++ b/readme.txt @@ -49,6 +49,10 @@ ADDING CHECKSTYLE ------Enter the URL: http://eclipse-cs.sourceforge.net/update - Follow the installation procedure and restart Eclipse
+USING GIT ------
Any kind of feedback is welcome; please check out the online documentation at
Commit to Local Repository Note: this commit operation does not commit into the remote repository! First, it is needed to select the modified files which should be committed:
$ git add readme.txt
Then perform the actual commit:
$ git commit [master 0fde1fb] Added TODO in section "USING GIT" 1 files changed, 4 insertions(+), 0 deletions(-)
Before executing the actual commit, git will open the default shell editor (determined using the $EDITOR variable, usually vi) to enter a message describing the commit changes. Git 171
Alternative way is to commit all changed files, i. e. it is not needed to explicitly add the changed files:
$ git commit -a [master 0fde1fb] Added TODO in section "USING GIT" 1 files changed, 4 insertions(+), 0 deletions(-)
Pushing Local Changes to Remote Repository $ git push Enter passphrase for key '/home/user/.ssh/id_rsa': Everything up-to-date
Pulling Changes from Remote Repository $ git pull Enter passphrase for key '/home/user/.ssh/id_rsa': Already up-to-date.
Add BaseXdb Upstream Repository The upstream repository is the one from which the BaseX releases are made and the one from which the personal repository was forked.
$ git remote add upstream [email protected]:BaseXdb/$project.git
$ git remote -v origin [email protected]:$username/$project.git (fetch) origin [email protected]:$username/$project.git (push) upstream [email protected]:BaseXdb/$project.git (fetch) upstream [email protected]:BaseXdb/$project.git (push)
Pulling Changes from Upstream to Local Repository When some changes are made in the upstream repository, they can be pulled to the local repository as follows:
$ git pull upstream master Enter passphrase for key '/home/user/.ssh/id_rsa': From github.com:BaseXdb/$project * branch master -> FETCH_HEAD Already up-to-date.
The changes can then be pushed in the personal repository:
$ git push
Check out the links at the end of the page for more git options. Git 172
Need help using git?
Installing For information on how to install git on various platforms please refer to: GitHub: git Installation Guide [8]
Documentation • Comprehensive Getting Starting Guide on GitHub [9] • The git book [10] • Gitcasts.com – Video Guides [11]
References
[1] http:/ / git-scm. com/
[2] https:/ / github. com
[3] http:/ / www. jcraft. com/ jsch
[4] https:/ / bugs. eclipse. org/ bugs/ show_bug. cgi?id=326526
[5] http:/ / egit. eclipse. org/ r/ #change,2037
[6] https:/ / github. com/ signup/ free
[7] http:/ / help. github. com/ key-setup-redirect
[8] http:/ / help. github. com/ git-installation-redirect/
[9] http:/ / help. github. com/
[10] http:/ / book. git-scm. com/ index. html
[11] http:/ / gitcasts. com/
Maven
This page is part of the Developer Section. It demonstrates how Maven [1] is used to compile and run BaseX, and embed it into other projects.
Using Maven If you have cloned our repositories and installed Maven on your machine, you can run the following commands from all local repository directories: • mvn compile: the BaseX source files are compiled. To launch the project, type in java -cp target/classes org.basex.BaseX, or have a look at our Start Scripts. • mvn package: JAR archives are created in the target class directory. • mvn install: the JAR archive is installed to the local repository, and made available to other Maven projects. This is particularly useful if you are compiling a beta version of BaseX, for which no archives exist in the repositories. By adding the flag -DskipTests=true you can skip running the JUnit tests and speed up the packaging procedure. You may as well use Eclipse and m2eclipse to compile the BaseX sources. Maven 173
Artifacts You can easily embed BaseX into your own Maven projects by adding the following XML snippets to your pom.xml file:
BaseX Main Package
BaseX APIs ...including the REST, XML:DB [2] and XQJ [3] APIs:
References
[1] http:/ / maven. apache. org
[2] http:/ / sourceforge. net/ projects/ xmldb-org
[3] http:/ / jcp. org/ en/ jsr/ detail?id=225 Releases 174 Releases
This page is part of the Developer Section. It lists the official locations of major and minor BaseX versions:
Official Releases Our releases, packaged for various platforms, are linked from our homepage. They are updated every 2-8 weeks:
• http:/ / basex. org/ download Our file server contains links to older releases as well (but we recommend everyone to stay up-to-date, as you'll get faster feedback working with the latest version):
• http:/ / files. basex. org/ releases
Stable Snapshots If you are a developer, we recommend you to regularly download one of our stable snapshots, which are packaged and uploaded several times a week:
• http:/ / files. basex. org/ releases/ latest/ Note that the offered snapshot files are replaced as soon as newer versions are available.
Code Base If you always want to be on the cutting edge, you are invited to watch and clone our GitHub repository:
• https:/ / github. com/ BaseXdb/ We do our best to keep our main repository stable as well.
Maven Artifacts The official releases and the current snapshots of both our core and our API packages are also deployed as Maven artifacts on our file server at regular intervals:
• http:/ / files. basex. org/ maven/ org/ basex/
Linux BaseX can also be found in some Linux distributions, such as Debian, Ubuntu and archlinux (Suse and other distributions will follow soon):
• Debian: http:/ / packages. debian. org/ sid/ basex
• Ubuntu: http:/ / launchpad. net/ ubuntu/ + source/ basex
• Arch Linux: http:/ / aur. archlinux. org/ packages. php?ID=38645 Translations 175 Translations
This page is part of the Developer Section. It describes how to translate BaseX into other (natural) languages. BaseX is currently available in nine languages, namely English, German, Japanese, French, Italian, Dutch, Indonesian, Vietnamese and Mongolian. It is easy to translate BaseX into your native language! This is how you can proceed:
Using the JAR file JAR files are nothing else than ZIP archives. All language files are placed in the lang directory inside the JAR file: 1. Unzip the source file English.lang and rename it to your target language (e.g. Zulu.lang) 2. Enter your name and potential contact information in the second line and translate all texts 3. Update your JAR file by copying the translated file into the zipped lang directory. Your new language file will be automatically scanned. 4. Start BaseX and choose your language in the GUI (Options → Preferences...) 5. Restart BaseX to see the changes
Using the sources All language files are placed in the src/main/resources/lang directory of the main project: 1. Create a copy of the source file English.lang and rename it to your target language (e.g. Zulu.lang) 2. Enter your name and potential contact information in the second line and translate all texts 3. Copy the translated file back to the lang directory. Your new language file will be automatically scanned. 4. Recompile the project, start BaseX and choose your language in the GUI (Options → Preferences...) 5. Restart BaseX to see the changes You may as well change the language in the .basex configuration file, which is placed in your home directory. To see where the all text keys are used within BaseX, we recommend you to temporarily set the LANGKEY option to true. 176
HTTP Services
REST
This page is part of the Developer Section. It describes how to use the REST API of BaseX. BaseX offers a RESTful API for accessing distributed XML resources. REST (REpresentational State Transfer [1]) facilitates a simple and fast access to databases through HTTP. The HTTP methods GET, PUT, DELETE, and POST can be used to interact with the database. The REST implementation has formerly been based on JAX-RX, a generic layer to provide unified access to XML databases and resources. With Version 7.0, it has been replaced with a native REST implementation that allows a closer integration with XQuery, WebDAV, and other features of BaseX. If you have worked with JAX-RX before, please take some time to understand the differences between the old and new API.
Getting Started First of all, launch the BaseX as Web Application. By default, Jetty [3] is used as web server. All HTTP services will
be available on port 8984, and the REST service is accessible at http:/ / localhost:8984/ rest/ . If the server is started as servlet, all Main Options (such as the path to the database) can be configured in the web.xml file. If run as a standalone application, the settings are stored in the file .basex. Most browsers can be used to get to know the REST API, and to directly display the results. When requesting the first result, you will have to enter some database credentials (default: admin/admin, see below). Some alternatives for using REST are listed in the Usage Examples.
URL Architecture The root URL lists all available databases. The following examples assume that you have created a database instance from the factbook.xml [3] document:
http:/ / localhost:8984/ rest
The resources of a database can be listed by specifying the database, and potential sub directories, in the URL. In the given example, a single XML document is stored in the factbook database:
http:/ / localhost:8984/ rest/ factbook
The contents of a database can be retrieved by directly addressing the resource:
http:/ / localhost:8984/ rest/ factbook/ factbook. xml If a file with the mime type application/xquery is addressed, it will be evaluated, and the result will be returned: REST 177
http:/ / localhost:8984/ rest/ factbook/ index. xq If a resource is not found, an HTTP response will be generated with 404 as status code.
Operations GET and POST requests support the following operations: • Query: Evaluates an XPath/XQuery expression. If a database or database path is specified in the URL, it is used as initial query context. • Run: Runs a query file located on the server. The query directory is defined by the HTTPPATH option. • Command: Executes a database command. • Get: This is the default operation for the GET operation (it is not possible to use this operation in a POST request). It returns a list of all databases, the resources of a database or the addressed resource. If a resource with content type application/xquery is addressed, it will be evaluated first, and the result will be returned.
Parameters Additionally, the following parameters can be applied to the operations: • Variables: External variables can be bound before a query is evaluated (see below for more). • Context: The context parameter may be used to provide an initial XML context node. • Options (Introduced with Version 7.1.1): Specified Options are applied before the actual operation will be performed. • Serialization: All Serialization parameters known to BaseX can be specified as query parameters. Parameters that are specified within a query will be interpreted by the REST server before the output is generated. • Wrap:
The wrap parameter encloses all query results with XML elements, using the http:/ / basex. org/ rest namespace. While Options can be specified for all operations, the remaining parameters will only make sense for Query and Run.
Request Methods
GET Requests If the GET method is used, all query parameters are directly specified within the URL. Examples • The first example lists all resources found in the tmp path of the factbook database:
http:/ / localhost:8984/ rest/ factbook/ tmp • The first example prints the city names from the factbook database and encloses all results with a
http:/ / localhost:8984/ rest/ factbook?query=/ / city/ name& wrap=yes REST 178
• In the next request, US-ASCII is chosen as output encoding, and the query eval.xq is evaluated:
http:/ / localhost:8984/ rest?run=eval. xq& encoding=US-ASCII • The next URL turns on XML wrapping and lists all database users that are known to BaseX:
http:/ / localhost:8984/ rest?command=show+ users • The last example includes an to disallow XQuery 3.0 expressions:
http:/ / localhost:8984/ rest?query=12345& xquery3=false
POST Requests The body of a POST request is interpreted as XML fragment, which specifies the operation to perform. The body must conform to a given XML Schema. Examples • The following query returns the first five city names of the factbook database:
• The second query returns the string lengths of all text nodes, which are found in the node that has been specified as initial context node:
• The following request returns the registered database users encoded in ISO-8859-1:
• This example creates a new database from the specified input and retains all whitespaces (works since Version 7.1.1):
• The last request runs a query query.xq located in the directory specified by HTTPPATH:
PUT Requests The PUT method is used to create new databases, or to add or update existing database resources: • Create Database: A new database is created if the URL only specifies the name of a database. If the request body contains XML, a single document is created, adopting the name of the database. • Store Resource: A resource is added to the database if the URL contains a database path. If the addressed resource already exists, it is replaced by the new input. There are two ways to store non-XML data in BaseX: • Store as raw: If application/octet-stream is chosen as content-type the input data is added as raw. • Convert to XML: Raw data can be explicitly converted to XML by specifying the content-type. Trying to add raw data without specifying the content type or specifying a wrong content type will eventually lead to a 400 (BAD REQUEST) exception. The following content types are available: • application/octet-stream: Stores input data as raw file. • application/json: Stores JSON as XML. • application/jsonml: Stores JSONML input as XML. • text/plain: Stores plain text input as XML. • text/csv: Stores CSV text input as XML. • text/html: Stores HTML input as XML. Examples • A new database with the name XMark is created. If XML input is sent in the HTTP body, the resulting database resource will be called XMark.xml: http://admin:admin@localhost:8984/rest/XMark • A new database is created, and no whitespaces will be removed from the passed on XML input (works since Version 7.1.1): http://admin:admin@localhost:8984/rest/XMark?chop=false • The contents of the HTTP body will be taken as input for the document one.xml, which will be stored in the XMark database: http://admin:admin@localhost:8984/rest/XMark/one.xml An HTTP response with status code 201 (CREATED) is sent back if the operation was successful. Otherwise, the server will reply with 404 (if a specified database was not found) or 400 (if the operation could not be completed). Have a look at the usage examples for more detailed examples using Java and shell tools like cURL. REST 180
DELETE Requests The DELETE method is used to delete databases or resources within a database. Example • The factbook database is deleted: http://admin:admin@localhost:8984/rest/factbook • All resources of the XMark database are deleted that reside in the tmp path: http://admin:admin@localhost:8984/rest/XMark/tmp/ The HTTP status code 404 is returned if no database is specified. 200 (OK) will be sent in all other cases.
Assigning Variables
GET Requests All query parameters that have not been processed before will be treated as variable assignments: Examples • The following request binds a single variable to the query to be processed:
http:/ / localhost:8984/ rest?query=$text& text=Hello+ World • The following request assigns two variables to a server-side query file mult.xq placed in the database DB:
http:/ / localhost:8984/ rest/ DB/ mult. xq?a=21& b=2
(: XQuery file: mult.xq :) declare variable $a as xs:integer external; declare variable $b as xs:integer external; $a * $b
Variables can also be explicitly prefixed with a dollar sign ($); this way, those variables can be bound as well that would otherwise be interpreted in a different way (e.g.: $method).
POST Requests If query or run is used as operation, external variables can be specified via the
User Management By default, the HTTP server is started with no predefined user. Users and passwords can be sent via HTTP basic authentication [2] with each HTTP request. As alternative, users and passwords can also be stored server-side in the "org.basex.user" and "org.basex.password" system properties before the HTTP server is started, or specified as command-line arguments. With cURL, and most browsers, you can specify the user name and password with each HTTP request within the request string as plain text, using the format USER:PASSWORD@URL. An example:
http:/ / admin:admin@localhost:8984/ rest/ factbook
Content Type As the content type of a REST response cannot be dynamically determined in all cases, it can be manually adjusted by the user. The final content type of a REST response is chosen in several steps: 1. By default, the content type of a response depends on the chosen operation: • Query/Run ? application/xml • Command ? text/plain • Get ? application/xml, or content type of the addressed resource 2. The default content type is overwritten if a serialization method is specified, either as query parameter or within the XQuery expression. The following methods are available: • xml ? application/xml • xhtml ? text/html • html ? text/html • text ? text/plain • raw ? application/octet-stream • json or jsonml ? application/json 3. The content type is overwritten in any case if a specific media-type is chosen, again as query parameter or within the query. The following three example requests will all return as result and use application/xml as content-type:
http:/ / localhost:8984/ rest?query=%3Ca/ %3E
http:/ / localhost:8984/ rest?query=%3Ca/ %3E& method=xml
http:/ / localhost:8984/ rest?query=%3Ca/ %3E& media-type=application/ xml
Usage Examples
Java
Authentication Most programming languages offer libraries to communicate with HTTP servers. The following example demonstrates how easy it is to perform a DELETE request with Java. Basic access authentication can be activated in Java by adding an authorization header to the HttpURLConnection instance. The header contains the word Basic, which specifies the authentication method, followed by the Base64-encoded USER:PASSWORD pair. As Java does not include a default conversion library for Base64 data, the internal BaseX class org.basex.util.Base64 can be used for that purpose: REST 182
// The java URL connection to the resource. URL url = new URL("http://admin:admin@localhost:8984/rest/factbook");
// Establish the connection to the URL. HttpURLConnection conn = (HttpURLConnection) url.openConnection(); // Set as DELETE request. conn.setRequestMethod("DELETE");
// User and password. String user = "bob"; String pw ="alice"; // Encode user name and password pair with a base64 implementation. String encoded = Base64.encode(user + ":" + pw); // Basic access authentication header to connection request. conn.setRequestProperty("Authorization", "Basic " + encoded);
// Print the HTTP response code. System.out.println("HTTP response: " + conn.getResponseCode());
// Close connection. conn.disconnect();
Content-Types The content-type of the input can easily be included, just add the following property to the connection (in this example we explicitly store the input file as raw):
// store input as raw conn.setRequestProperty("Content-Type", "application/octet-stream");
See the PUT Requests section for a description of the possible content-types. Find Java examples for all methods here: GET [3], POST [4], PUT [5], DELETE [6].
Command Line Tools such as the Linux commands Wget [7] or cURL [8] exist to perform HTTP requests (try copy & paste): GET • curl -i "admin:admin@localhost:8984/rest/factbook?query=//city/name" POST • curl -i -X POST -H "Content-Type: application/xml" -d "
• curl -i -X PUT -H "Content-Type: text/plain" -T "etc/xml/factbook.xml" "admin:admin@localhost:8984/rest/factbook" DELETE • curl -i -X DELETE "admin:admin@localhost:8984/rest/factbook"
Changelog
Version 7.1.1 • Added: options parameter for specifying database options
Version 7.1 • Added: PUT request: automatic conversion to XML if known content type is specified
Version 7.0 • REST API introduced, replacing the old JAX-RX API
References
[1] http:/ / en. wikipedia. org/ wiki/ Representational_State_Transfer
[2] http:/ / en. wikipedia. org/ wiki/ Basic_access_authentication
[3] https:/ / github. com/ BaseXdb/ basex-examples/ tree/ master/ src/ main/ java/ org/ basex/ examples/ rest/ RESTGet. java
[4] https:/ / github. com/ BaseXdb/ basex-examples/ tree/ master/ src/ main/ java/ org/ basex/ examples/ rest/ RESTPost. java
[5] https:/ / github. com/ BaseXdb/ basex-examples/ tree/ master/ src/ main/ java/ org/ basex/ examples/ rest/ RESTPut. java
[6] https:/ / github. com/ BaseXdb/ basex-examples/ tree/ master/ src/ main/ java/ org/ basex/ examples/ rest/ RESTDelete. java
[7] http:/ / www. gnu. org/ s/ wget/
[8] http:/ / curl. haxx. se/ REST: POST Schema 184 REST: POST Schema
The following schema is used from the REST API to validate POST requests:
RESTXQ
This page is part of the Developer Section. It describes how to use the RESTXQ API of BaseX. RESTXQ, introduced by Adam Retter [1], is a new API that facilitates the use of XQuery as a Server Side processing language for the Web. RESTXQ has been inspired by Java’s JAX-RS API [2]: it defines a pre-defined set of XQuery 3.0 annotations for mapping HTTP requests to XQuery functions, which in turn generate and return HTTP responses. As of Version 7.2, RESTXQ is supported by BaseX. Note that various details of the specification may be subject to change due to the early state of the API.
Getting started First of all, launch the BaseX as Web Application. By default, Jetty [3] is used as web server. All HTTP services will
be available on port 8984, and the RESTXQ service is accessible at http:/ / localhost:8984/ restxq/ . If the server is started as servlet, all Main Options (such as the path to the database) can be configured in the web.xml file. If run as a standalone application, the settings are stored in the file .basex.
Module Declarations
A RESTXQ module needs to contain a declaration to the namespace http:/ / exquery. org/ ns/ restxq. A Resource Function is an XQuery function that has been marked up with RESTXQ annotations (annotations will be introduced with the upcoming XQuery 3.0 standard). When an HTTP request comes in, a resource function will be invoked that matches the constraints indicated by its annotations. All files with extension *.xqm, placed inside the directory specified by HTTPPATH (refer to HTTP Server Configuration) will be treated as RESTXQ modules. These will be parsed for RESTXQ annotations and cached. If a module is modified, it will be parsed again at runtime.
A simple RESTXQ module is shown below, it is part of a clean installation and available at http:/ / localhost:8984/
restxq/ .
(:~ simplified module as in http/restxq.xqm :) module namespace page = 'http://basex.org/modules/web-page'; declare namespace rest = 'http://exquery.org/ns/restxq'; RESTXQ 186
declare %rest:path("hello/{$world}") %rest:GET %rest:header-param("User-Agent", "{$agent}") function page:hello($world as xs:string, $agent as xs:string*) {
If the URI http:/ / localhost:8984/ restxq/ hello/ world is accessed, the result will be kind of
We added another method within that module:
declare %rest:path("form/") %rest:POST %rest:form-param("content","{$message}", "'no message delivered'") function page:hello-postman($message as xs:string) {
If you posted something (e.g. using curl or the embedded formular at http:/ / localhost:8984/ restxq/ )
curl -i -X POST --data "content='Here comes the post'" http://admin:admin@localhost:8984/restxq/form
You would recieve
Annotations This section lists all annotations provided by RESTXQ. rest is used as namespace prefix.
Constraints Constraints restrict the HTTP requests that a resource function may process.
Paths A resource function must have a single Path Annotation. It will be called if a URL matches the path segments and templates specified as argument. Path templates contain variables in curly brackets, and map the values of the actual request path to the function arguments. The following example contains a path annotation with three segments and two templates. One of the function arguments is further specified with a data type, which means that the value for $variable will be cast to an xs:integer before being bound:
declare %rest:path("/a/path/{$with}/some/{$variable}") function($with, $variable as xs:integer) { ... };
HTTP Methods The HTTP method annotations relate to some of the HTTP request methods [3] (GET, HEAD, DELETE, POST, PUT). Depending on the request method of the request, a function is invoked.
Simple Method Annotations All available simple method annotations:
%rest:GET %rest:HEAD %rest:DELETE
Content Method Annotations The variable declaration, for processing the content in a XQuery function, is optional. All available content method annotations:
%rest:POST %rest:POST("{$post-body}") %rest:PUT %rest:PUT("{$put-body}")
Content Types • HTTP Content Types: One or more media-types may be specified as strings, e.g.:
%rest:consumes("application/xml", "text/xml")
• HTTP Accept: One or more media-types may be specified as strings, e.g.:
%rest:produces("application/atom+xml")
These default to */* if no media-type annotations are given. RESTXQ 188
Parameters Parameters are optional annotations that can be used to bind additional values to function arguments:
Query Strings The value of the first parameter, if found in the Query String [4], will be assigned to the variable specified as second parameter. Optionally, a third parameter may be specified as default:
%rest:query-param("parameter", "{$value}", "default") %rest:query-param("answer", "{$answer}", 42, 43, 44) %rest:query-param("search", "{$search-param}")
HTML Form Fields Form parameters are specified the same way as query strings. Their values are extracted from GET or POST requests.
%rest:form-param("parameter", "{$value}", "default")
HTTP Headers Header parameters are specified the same way as query strings:
%rest:header-param("User-Agent","{$user-agent}") %rest:header-param("Referer","{$referer}", "none")
Cookies Cookie parameters are specified the same way as query strings:
%rest:cookie-param("username","{$user}") %rest:cookie-param("authentication","{$auth}", "no_auth")
References RESTXQ has been proposed by Adam Retter [1]. More information on all specifics can be found in the following two documents: • RESTful XQuery, Standardised XQuery 3.0 Annotations for REST [5]. Paper, XMLPrague, 2012 • RESTXQ [6]. Slides, MarkLogic User Group London, 2012
References
[1] http:/ / www. adamretter. org. uk/
[2] http:/ / en. wikipedia. org/ wiki/ Java_API_for_RESTful_Web_Services
[3] http:/ / en. wikipedia. org/ wiki/ HTTP#Request_methods
[4] http:/ / en. wikipedia. org/ wiki/ Query_string
[5] http:/ / www. adamretter. org. uk/ papers/ restful-xquery_january-2012. pdf
[6] http:/ / www. adamretter. org. uk/ presentations/ restxq_mugl_20120308. pdf WebDAV 189 WebDAV
This page is part of the Developer Section. It describes how to use the WebDAV file system interface. BaseX offers access to the databases and documents using the WebDAV [1] protocol. WebDAV provides convenient means to access and edit XML documents by representing BaseX databases and documents in the form of a file system hierarchy.
Getting Started First of all, launch the BaseX as Web Application. By default, Jetty [3] is used as web server. All HTTP services will
be available on port 8984, and the WebDAV service is accessible at http:/ / localhost:8984/ webdav/ . If the server is started as servlet, all Main Options (such as the path to the database) can be configured in the web.xml file. If run as a standalone application, the settings are stored in the file .basex. Generally, the BaseX WebDAV Server can be accessed using either with a http://
Authorization The WebDAV service uses the database user credentials in order to perform authentication and authorization. If database user and password are explicitly specified when starting the BaseX HTTP Server using the corresponding startup options, WebDAV will not request additional user authentication from the client.
WebDAV Clients Please check out the following tutorials to get WebDAV running on different operating systems and with oXygen: • Windows 7 • Windows XP • Mac OSX 10.4+ • GNOME and Nautilus • KDE • oXygen Editor
Changelog
Version 7.0 • WebDAV API introduced
References
[1] http:/ / en. wikipedia. org/ wiki/ Webdav WebDAV: Windows 7 190 WebDAV: Windows 7
This page belongs to the WebDAV page. It describes how to get the WebDAV API running with Windows 7. • Open the Explorer • Open the "Map network drive..." dialog by right-clicking on "My Computer" • Click on the link "Connect to a Web site that you can use to store your documents and pictures."
• Click "Next", select "Choose a custom network location" and click "Next" again.
• Enter the URL address of the BaseX WebDAV Server (e.g. http:/ / localhost:8984/ webdav) and click "Next". WebDAV: Windows 7 191
If a message saying that the folder is not valid, this is because Microsoft WebClient is not configured to use Baseic HTTP authentication. Please check this Microsoft article [1] in order to enable Basic HTTP authentication. • Enter a name for the network location and click "Next".
• The BaseX WebDAV can be accessed from the Explorer window. WebDAV: Windows 7 192
References
[1] http:/ / support. microsoft. com/ kb/ 928692/ en
WebDAV: Windows XP
This page belongs to the WebDAV page. It describes how to get the WebDAV API running with Windows XP. • In the "My Network Places" view, double click on "Add Network Place":
• Confirm the upcoming introductory dialog:
• Select "Choose another network location" in the next dialog: WebDAV: Windows XP 193
• Next, specify the BaseX WebDAV URL:
• Enter the user/password combination to connect to the WebDAV service:
• Assign a name to your WebDAV connection: WebDAV: Windows XP 194
• Finish the wizard:
• You can now see all BaseX databases in the Windows Explorer: WebDAV: Mac OSX 195 WebDAV: Mac OSX
This page belongs to the WebDAV page. It describes how to get the WebDAV API running with Mac OS X 10.4+. • Mac OS X supports WebDAV since 10.4/Tiger • Open Finder, choose Go -> Connect to Server:
• Enter BaseX WebDAV URL (eg. http:/ / localhost:8984/ webdav) - do not use webdav://-scheme! Press Connect: WebDAV: Mac OSX 196
• Enter the user credentials:
• That's it, now the databases can be browsed: WebDAV: GNOME 197 WebDAV: GNOME
This page belongs to the WebDAV page. It describes how to get the WebDAV API running with GNOME and Nautilus. • In Nautilus choose File -> Connect to Server:
• Choose "WebDAV (HTTP)" from the "Type" drop-down and enter the server address, port and user credentials: WebDAV: GNOME 198
• After clicking "Connect" the databases can be browsed: WebDAV: KDE 199 WebDAV: KDE
This page belongs to the WebDAV page. It describes how to get the WebDAV API running with KDE. • KDE SC provides two file managers - Dolphin and Konqueror, which both support WebDAV using the "webdav://" URL prefix. Start Dolphin or Konqueror and enter the BaseX WebDAV URL (eg. webdav://localhost:8984/webdav):
• Enter the user credentials:
• After clicking "OK" the databases can be browsed: WebDAV: KDE 200 201
Client APIs
Clients
This page is part of the Developer Section. It describes how to use BaseX from other programming languages. With the following light-weight bindings in different programming languages, you will be able to connect to a running BaseX server instance, execute database commands, perform queries or listen to events. Most clients offer the following two classes: • Standard Mode: connecting to a server, sending commands • Query Mode: defining queries, binding variables, iterative evaluation Please have a look at our Server Protocol for more information on the clients and the underlying protocol. Bindings for other languages are easy to write; your contributions are welcome. Currently, we offer bindings for the following programming languages: Object oriented C# [1], VB [2], Scala [3], Java [4] ActionScript [5] (contributed by Manfred Knobloch) Scripting Perl [6], Ruby [7] PHP [8] (example) Python [9] (improved by Arjen van Elteren) Rebol [10] (contributed by Sabu Francis) Functional Lisp [11] (contributed by Andy Chambers) Haskell [12] (contributed by Leo Wörteler) Others node.js [13] (contributed by Andy Bunce) Qt [14] (contributed by Hendrik Strobelt) C [15] Many of the interfaces contain the following files: • BaseXClient contains the code for creating a session, sending and executing commands and receiving results. An inner Query class facilitates the binding of external variables and iterative query evaluation. • Example demonstrates how to send database commands. • QueryExample shows you how to evaluate queries in an iterative manner. • QueryBindExample shows you how to bind a variable to your query and evaluates the query in an iterative manner. • CreateExample shows how new databases can be created by using streams. • AddExample shows how documents can be added to a database by using streams. • EventExample demonstrates how to watch and unwatch Events. Clients 202
References
[1] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ c%23
[2] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ vb
[3] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ scala
[4] https:/ / github. com/ BaseXdb/ basex-examples/ tree/ master/ src/ main/ java/ org/ basex/ examples/ api
[5] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ as
[6] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ perl
[7] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ ruby
[8] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ php
[9] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ python
[10] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ rebol
[11] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ lisp
[12] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ haskell
[13] https:/ / github. com/ apb2006/ basex-node
[14] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ qt
[15] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ c
Standard Mode
In the standard mode of the Clients, a database command can be sent to the server using the execute() function of the Session. This functions returns the whole result. With the info() function, you can request some information on your executed process. If an error occurs, an exception with the error message will be thrown.
Usage The standard execution works as follows: 1. Create a new session instance with hostname, port, username and password. 2. Call the execute() function of the session with the database commands as argument. 3. Receive the result of a successfully executed command. If an error occurs, an exception is thrown. 4. Optionally, call info() to get some process information 5. Continue using the client (back to 2.), or close the session.
Example in PHP Taken from our repository [1]:
try { // initialize timer $start = microtime(true);
// create session Standard Mode 203
$session = new Session("localhost", 1984, "admin", "admin");
// perform command and print returned string print $session->execute("xquery 1 to 10");
// close session $session->close();
// print time needed $time = (microtime(true) - $start) * 1000; print "\n$time ms\n";
} catch (Exception $e) { // print exception print $e->getMessage(); } ?>
References
[1] https:/ / github. com/ BaseXdb/ basex-api/ blob/ master/ src/ main/ php/ Example. php
Query Mode
The query mode of the Clients allows you to bind external variables to a query and evaluate the query in an iterative manner. The query() function of the Session instance returns a new query instance.
Usage The query execution works as follows: 1. Create a new session instance with hostname, port, username and password. 2. Call query() with your XQuery expression to get a query object. 3. Optionally bind variables to the query with one of the bind() functions. 4. Version 7.2: Optionally bind a value to the context item via context(). 5. Iterate through the query object with the more() and next() functions. 6. As an alternative, call execute() to get the whole result at a time. 7. info() gives you information on query evaluation. 8. options() returns the query serialization parameters. 9. Don't forget to close the query with close().
PHP Example Taken from our repository [1]:
* * (C) BaseX Team 2005-11, BSD License */ include("BaseXClient.php");
try { // create session $session = new Session("localhost", 1984, "admin", "admin");
try { // create query instance $input = 'declare variable $name external; '. 'for $i in 1 to 10 return element { $name } { $i }'; $query = $session->query($input);
// bind variable $query->bind("$name", "number");
// print result print $query->execute()."\n";
// close query instance $query->close();
} catch (Exception $e) { // print exception print $e->getMessage(); }
// close session $session->close();
} catch (Exception $e) { // print exception print $e->getMessage(); } ?>
References
[1] https:/ / github. com/ BaseXdb/ basex-api/ blob/ master/ src/ main/ php/ QueryBindExample. php PHP Example 205 PHP Example
This page is referenced from the Clients page. It demonstrates how database commands and XQuery can be executed on a database server with a PHP client. The results of the query are stored into a DOM document and can be processed in several ways.
Requirements • BaseXClient [1]: BaseX PHP Client • DOMExample [2]: Example used in this tutorial • any PHP Server, such as XAMPP [3]
Setting up • Install and start XAMPP, or choose a PHP Server of your own • Copy BaseXClient.php and DOMExample.php to the XAMPP folder or upload it to your webserver
Usage 1. Start a Database Server instance on your local or a remote machine. Make sure the host and port settings in DOMExample.php are correct. 2. Call DOMExample.php in a web browser of your choice. 3. Look at the DOM document [4] on the PHP documentation for further information on the DOM document functions. 4. Open DOMExample.php in an editor and edit it for your own needs.
References
[1] https:/ / github. com/ BaseXdb/ basex-api/ blob/ master/ src/ main/ php/ BaseXClient. php
[2] https:/ / github. com/ BaseXdb/ basex-api/ blob/ master/ src/ main/ php/ DOMExample. php
[3] http:/ / www. apachefriends. org/ en/ xampp. html
[4] http:/ / php. net/ manual/ en/ class. domdocument. php Server Protocol 206 Server Protocol
This page presents the classes and functions of the BaseX Clients, and the underlying protocol, which is utilized for communicating with the database server.
Workflow • First of all, a BaseX database server must be running, which will process the client requests. • Each client provides a session class or script with methods to connect to and communicate with the database server. A socket connection will be established by the constructor, which expects a host, port, user name and password as arguments. • The execute() method is called to launch a database command. It returns the result or throws an exception with the received error message. • The query() method creates a query instance. Variables can be bound to that object, and the result can either be requested via execute(), or in an iterative manner with the more() and next() functions. If an error occurs, an exception will be thrown. • The create(), add(), replace() and store() method pass on input streams to the corresponding database commands. • To speed up execution, an output stream can be specified by some clients; this way, all results will be directed to that output stream. • Most clients are accompanied by some example files, which demonstrate how database commands can be executed or how queries can be evaluated.
Class Structure
Session • Create and return session with host, port, user name and password: Session(String host, int port, String name, String password) • Execute a command and return the result: String execute(String command) • Return a query object for the specified query: Query query(String query) • Create a database from an input stream: void create(String name, InputStream in) • Add a document to the current database from an input stream: void add(String path, InputStream in) • Replace a document with the specified input stream: void replace(String path, InputStream in) • Store raw data at the specified path: void store(String path, InputStream in) • Watch the specified event: void watch(String name, Event notifier) • Unwatch the specified event: void unwatch(String name) Server Protocol 207
• Return process information: String info() • Close the session: void close()
Query • Create query object with session and query: Query(Session s, String query) • Bind an external variable: void bind(String name, String value, String type). The type can be an empty string. • Version 7.2: Bind the context item: void context(String value, String type). The type can be an empty string. • Execute the query and return the result: String execute() • Iterator: check if a query returns more items: boolean more() • Iterator: return the next item: String next() • Return query information: String info() • Return serialization parameters: String options() • Return if the query may perform updates: boolean updating() • Close the query: void close()
Transfer Protocol All Clients use the following client/server protocol to communicate with the server. The description of the protocol is helpful if you want to implement a new client.
General Syntax • \x: single byte. • {...}: utf8 strings or raw data, suffixed with a \0 byte. To avoid confusion with the suffix byte, all \0 and \FF bytes that occur in raw data will be prefixed with \FF. Server Protocol 208
Authentication (via cram-md5 [1]) 1. Client connects to server socket 2. Server sends timestamp: {timestamp} 3. Client sends username and hashed password/timestamp: {username} {md5(md5(password) + timestamp)} 4. Server replies with \0 (success) or \1 (error)
Command Protocol The following byte sequences are sent and received from the client (please note that a specific client need not support all of the presented commands):
Command Client Request Server Response Description
COMMAND {command} {result} {info} \0 Executes a database command.
QUERY \0 {query} {id} \0 Creates a new query instance and returns its id.
CREATE \8 {name} {input} {info} \0 Creates a new database with the specified input (may be empty).
ADD \9 {name} {path} {info} \0 Adds a new resource to the opened database. {input}
WATCH \10 {name} Registers the client for the specified event.
UNWATCH \11 {name} Unregisters the client.
REPLACE \12 {path} {input} {info} \0 Replaces a resource with the specified input.
STORE \13 {path} {input} {info} \0 Stores a binary resource in the opened database.
↯ error {beginning of result} {error} Error feedback. \1
Query Command Protocol Queries are referenced via an id, which has been returned by the QUERY command (see above):
Query Client Request Server Response Description Command
CLOSE \2 {id} \0 \0 Closes and unregisters the query with the specified id.
BIND \3 {id} {name} \0 \0 Binds a value to a variable. An empty string can be specified as {value} {type} data type.
RESULTS \4 {id} \x {item} ... \x Returns all resulting items as strings, prefixed by a Type byte {item} \0 (\x).
EXECUTE \5 {id} {result} \0 Executes the query and returns all results as a UTF8 string.
INFO \6 {id} {result} \0 Returns a query info string.
OPTIONS \7 {id} {result} \0 Returns a string with all query serialization parameters.
CONTEXT \14 {id} {value} \0 \0 Version 7.2: Binds a value to the context item. An empty string {type} can be specified as data type.
UPDATING \30 {id} {result} \0 Version 7.2: Returns true if the query may perform updates; false otherwise.
FULL \31 {id} XDM {item} ... XDM Version 7.2: Returns all resulting items as strings, prefixed by {item} \0 XDM Meta Data (see below). Server Protocol 209
↯ error {beginning of result} \1 Error feedback. {error}
XDM Meta Data In most cases, the XDM meta data boils down to a single byte, which represents the node kind or item type. There are three exceptions: document-node(), attribute() and xs:QName items are followed by an additional {URI} string.
Examples • Java client [2] • C# client [3] • Python client [4] • Perl client [5]
Changelog
Version 7.2 • Added: Query Commands CONTEXT, UPDATING and FULL
References
[1] http:/ / tools. ietf. org/ html/ rfc2195
[2] https:/ / github. com/ BaseXdb/ basex-api/ blob/ master/ src/ main/ java/ BaseXClient. java
[3] https:/ / github. com/ BaseXdb/ basex-api/ blob/ master/ src/ main/ c%23/ BaseXClient. cs
[4] https:/ / github. com/ BaseXdb/ basex-api/ blob/ master/ src/ main/ python/ BaseXClient. py
[5] https:/ / github. com/ BaseXdb/ basex-api/ blob/ master/ src/ main/ perl/ BaseXClient. pm Server Protocol: Types 210 Server Protocol: Types
Version 7.1: The following table lists all node kinds and item types that are returned by the Server Protocol. Currently, all node kinds are of type xs:untypedAtomic:
ID Node Kind/Item Type Type
7 Function item function
8 node() node
9 text() node
10 processing-instruction() node
11 element() node
12 document-node() node
13 document-node(element()) node
14 attribute() node
15 comment() node
32 item() atomic value
33 xs:untyped atomic value
34 xs:anyType atomic value
35 xs:anySimpleType atomic value
36 xs:anyAtomicType atomic value
37 xs:untypedAtomic atomic value
38 xs:string atomic value
39 xs:normalizedString atomic value
40 xs:token atomic value
41 xs:language atomic value
42 xs:NMTOKEN atomic value
43 xs:Name atomic value
44 xs:NCName atomic value
45 xs:ID atomic value
46 xs:IDREF atomic value
47 xs:ENTITY atomic value
48 xs:float atomic value
49 xs:double atomic value
50 xs:decimal atomic value
51 xs:precisionDecimal atomic value
52 xs:integer atomic value
53 xs:nonPositiveInteger atomic value
54 xs:negativeInteger atomic value
55 xs:long atomic value
56 xs:int atomic value Server Protocol: Types 211
57 xs:short atomic value
58 xs:byte atomic value
59 xs:nonNegativeInteger atomic value
60 xs:unsignedLong atomic value
61 xs:unsignedInt atomic value
62 xs:unsignedShort atomic value
63 xs:unsignedByte atomic value
64 xs:positiveInteger atomic value
65 xs:duration atomic value
66 xs:yearMonthDuration atomic value
67 xs:dayTimeDuration atomic value
68 xs:dateTime atomic value
69 xs:dateTimeStamp atomic value
70 xs:date atomic value
71 xs:time atomic value
72 xs:gYearMonth atomic value
73 xs:gYear atomic value
74 xs:gMonthDay atomic value
75 xs:gDay atomic value
76 xs:gMonth atomic value
77 xs:boolean atomic value
78 basex:binary atomic value
79 xs:base64Binary atomic value
80 xs:hexBinary atomic value
81 xs:anyURI atomic value
82 xs:QName atomic value
83 xs:NOTATION atomic value Java Examples 212 Java Examples
This page is part of the Developer Section. The following Java code snippets demonstrate how easy it is to run database commands, create collections, perform queries, etc. via the BaseX API. Most examples are taken from our basex-examples [1] repository, in which you will find some more use cases. Note that we recommend everyone to use our own APIs, as they offer better performance and are better supported by our core team. The use of the XML:DB and XQJ APIs is discouraged: as these APIs do not utilize the client/server architecture of BaseX, their use may lead to conflicting database access operations.
Local Examples RunCommands.java [2] creates and drops database and index instances, prints a list of all existing databases. WikiExample.java [3] creates a database from an url (wiki instance), runs a query against it and drops the database. RunQueries.java [4] shows three variants of running queries. CreateCollection.java [5] creates and manages a collection. QueryCollection.java [6] creates, runs queries against it and drops a collection.
Server Examples ServerCommands.java [7] launches server-side commands using a client session. ServerAndLocal.java [8] processes server results locally. ServerConcurrency.java [9] runs concurrent queries. UserExample.java [10] manages database users.
REST API Examples RESTGet.java [11] presents the HTTP GET method. RESTPost.java [12] presents the HTTP POST method. RESTPut.java [13] presents the HTTP PUT method. RESTDelete.java [14] presents the HTTP DELETE method. Java Examples 213
XML:DB API Examples XMLDBCreate.java [15] creates a collection using XML:DB. XMLDBQuery.java [16] runs a query using XML:DB. XMLDBInsert.java [17] inserts a document into a database using XML:DB.
XQJ API Example XQJQuery.java [18] runs a query using XQJ.
References
[1] https:/ / github. com/ BaseXdb/ basex-examples/ tree/ master/ src/ main/ java/ org/ basex/ examples
[2] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ query/ RunCommands. java
[3] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ WikiExample. java
[4] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ query/ RunQueries. java
[5] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ query/ CreateCollection. java
[6] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ query/ QueryCollection. java
[7] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ server/ ServerCommands. java
[8] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ server/ ServerAndLocal. java
[9] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ server/ ServerConcurrency. java
[10] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ UserExample. java
[11] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ rest/ RESTGet. java
[12] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ rest/ RESTPost. java
[13] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ rest/ RESTPut. java
[14] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ rest/ RESTDelete. java
[15] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ xmldb/ XMLDBCreate. java
[16] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ xmldb/ XMLDBQuery. java
[17] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ xmldb/ XMLDBInsert. java
[18] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ xqj/ XQJQuery. java 214
Advanced User's Guide
Advanced User's Guide
This page is one of the Main Sections of the documentation. It contains details on the BaseX storage and the Server architecture, and presents some more GUI features.
Storage • Configuration: Information on the BaseX configuration • Catalog Resolver Information on entity resolving • Statistics: Exemplary statistics on databases created with BaseX • Backups: Backup and restore databases
Server • User Management: User management in the client/server environment • Transaction Management: Insight into the BaseX transaction management • Logging: Description of the server logs • Events: Description of the event feature
Querying • Indexes: Available index structures and their utilization • Execution Plan: Analyzing query evaluation Configuration 215 Configuration
This article is part of the Advanced User's Guide. It gives some more insight into the configuration of BaseX.
Configuration Files BaseX maintains some configuration files, which are stored in the project’s Home Directory: • .basex contains all options that are relevant for running the server or standalone versions of BaseX. • .basexgui defines all options relevant to the BaseX GUI. • .basexperm contains user name, passwords, and permissions (see last paragraph). • .basexevents contains all existing events (see Events). • .basexhistory contains commands that have been typed in most recently. Note that, depending on your OS and configuration, files and folders with a '.' prefix may be hidden.
Home Directory As BaseX is distributed in different flavors, and may be started from different locations, it dynamically determines its home directory: • First, the system property "org.basex.path" is checked. If it contains a value, it is chosen as directory path. • If not, the current user directory (defined by the system property "user.dir") is chosen if the .basex configuration file is found in this directory. • Otherwise, the configuration file is searched in the application directory (the folder in which the project is located). • In all other cases, the user's home directory (defined in "user.home") is chosen.
Database Directory A database in BaseX consists of several files, which are all bundled in a folder with the database name. If the user’s home directory has been chosen as base directory, the database folders will be stored in a BaseXData directory. Otherwise, the directory will be named datda. The database path can be changed as follows: • GUI: Choose Options → Preferences and choose a new database path. • Server/Standalone: SET DBPATH [path] Note: Existing databases will not be automatically moved to the new destination.
User and Log Files Global users, along with their passwords and permissions, are stored in the .basexperm file in the home directory. Local users and permissions are stored inside the database files. Log files are stored in text format in the home directory BaseXData/.logs (see Logging for more information). Catalog Resolver 216 Catalog Resolver
This article is part of the Advanced User's Guide. It clarifies how to deal with external DTD declarations when parsing XML data.
Overview XML documents often rely on Document Type Definitions (DTDs). While parsing a document with BaseX, entities can be resolved with respect to that particular DTD. By default, the DTD is only used for entity resolution. XHTML, for example, defines its doctype via the following line:
Fetching xhtml1-strict.dtd obviously involves network traffic. When dealing with single files, this may seem tolerable, but importing large collections benefits from caching these resources. Depending on the remote server, you will experience significant speed improvements when caching DTDs locally.
XML Entity and URI Resolvers BaseX comes with a default URI resolver that is usable out of the box. To enable entity resolving you have to provide a valid XML Catalog file, so that the parser knows where to look for mirrored DTDs. A simple working example for XHTML might look like this:
This rewrites all systemIds starting with: http://www.w3.org/TR/xhtml1/DTD/ to file:///path/to/dtds/. The XHTML DTD xhtml1-strict.dtd and all its linked resources will now be loaded from the specified path.
GUI Mode When running BaseX in GUI mode, simply provide the path to your XML Catalog file in the Parsing Tab of the Database Creation Dialog.
Console & Server Mode To enable Entity Resolving in Console Mode, specify the following options: • SET CATFILE [path] Now entity resolving is active for the current session. All subsequent ADD commands will use the catalog file to resolve entities. The paths to your catalog file and the actual DTDs are either absolute or relative to the current working directory. When using BaseX in Client-Server-Mode, this is relative to the server's working directory. Catalog Resolver 217
Please Note Entity resolving only works if the internal XML parser is switched off (which is the default case). If you use the internal parser, you can manually specify whether you want to parse DTDs and entities or not.
Using other Resolvers There might be some cases when you do not want to use the built-in resolver that Java provides by default (via com.sun.org.apache.xml.internal.resolver.*). BaseX offers support for the Apache-maintained XML Commons Resolver [1], available for download here [2]. To use it add resolver.jar to the classpath when starting BaseX:
java -cp basex.jar:resolver.jar org.basex.BaseXServer
More Information • Wikipedia on Document Type Definitions [3] • Apache XML Commons Article on Entity Resolving [4] • XML Entity and URI Resolvers [5], Sun • XML Catalogs. OASIS Standard, Version 1.1. 07-October-2005. [6]
References
[1] http:/ / xml. apache. org/ commons
[2] http:/ / xerces. apache. org/ mirrors. cgi
[3] http:/ / en. wikipedia. org/ wiki/ Document_Type_Definition
[4] http:/ / xml. apache. org/ commons/ components/ resolver/ resolver-article. html
[5] http:/ / java. sun. com/ webservices/ docs/ 1. 6/ jaxb/ catalog. html
[6] http:/ / www. oasis-open. org/ committees/ download. php/ 14810/ xml-catalogs. pdf Statistics 218 Statistics
This article is part of the Advanced User's Guide. It lists statistics on various XML instances that have been created with BaseX. The URLs to the original sources, if available or public, are listed below. The database size does not include any indexes • #nodes represents the number of XML nodes which have been created in the database • #atr, #eln, and #uri represent the number of distinct attributes, element names, and namespaces
Databases
Instances file size #files db size #db nodes #atr #eln #atn #uri height
RuWikiHist 421 GiB 1 416 GiB 324,848,508 3 21 6 2 6
ZhWikiHist 126 GiB 1 120 GiB 179,199,662 3 21 6 2 6
EnWiktionary 79 GiB 1 75 GiB 134,380,393 3 21 6 2 6
XMark 55 GiB 1 64 GiB 1,615,071,348 2 74 9 0 13
EnWikiMeta 54 GiB 1 52 GiB 401,456,348 3 21 6 2 6
MedLine 38 GiB 379 36 GiB 1,623,764,254 2 84 6 0 9
iProClass 36 GiB 1 37 GiB 1,631,218,984 3 245 4 2 9
Inex209 31 GiB 2,666,500 34 GiB 1,336,110,639 15 28,034 451 1 37
CoPhIR 29 GiB 10,000,000 31 GiB 1,104,623,376 10 42 42 0 8
EnWikipedia 26 GiB 1 25 GiB 198,546,747 3 24 21 2 6
XMark 22 GiB 1 26 GiB 645,997,965 2 74 9 0 13
InterPro 14 GiB 1 19 GiB 860,304,235 5 7 15 0 4
Genome1 13 GiB 1 13 GiB 432,628,105 12 26 101 2 6
NewYorkTimes 12 GiB 1,855,659 13 GiB 280,407,005 5 41 33 0 6
TrEMBL 11 GiB 1 14 GiB 589,650,535 8 47 30 2 7
XMark 11 GiB 1 13 GiB 323,083,409 2 74 9 0 13
IntAct 7973 MiB 25,624 6717 MiB 297,478,392 7 64 22 2 14
Freebase 7366 MiB 1 10 GiB 443,627,994 8 61 283 1 93
SDMX 6356 MiB 1 8028 MiB 395,871,872 2 22 6 3 7
OpenStreetMap 5312 MiB 1 5171 MiB 6,910,669 3 19 5 2 6
SwissProt 4604 MiB 1 5422 MiB 241,274,406 8 70 39 2 7
EURLex 4815 MiB 1 5532 MiB 167,328,039 23 186 46 1 12
Wikicorpus 4492 MiB 659,338 4432 MiB 157,948,561 12 1,257 2,687 2 50
EnWikiRDF 3679 MiB 1 3537 MiB 98,433,194 1 11 2 11 4
CoPhIR 2695 MiB 1,000,000 2882 MiB 101,638,857 10 42 42 0 8
MeSH 2091 MiB 1 2410 MiB 104,845,819 3 6 5 2 5
FreeDB 1723 MiB 1 2462 MiB 102,901,519 2 7 3 0 4
XMark 1134 MiB 1 1303 MiB 32,298,989 2 74 9 0 13
DeepFS 810 MiB 1 850 MiB 44,821,506 4 3 6 0 24 Statistics 219
LibraryUKN 760 MiB 1 918 MiB 46,401,941 3 23 3 0 5
Twitter 736 MiB 1,177,495 767 MiB 15,309,015 0 8 0 0 3
Organizations 733 MiB 1,019,132 724 MiB 33,112,392 3 38 9 0 7
DBLP 694 MiB 1 944 MiB 36,878,181 4 35 6 0 7
Feeds 692 MiB 444,014 604 MiB 5,933,713 0 8 0 0 3
MedLineSupp 477 MiB 1 407 MiB 21,602,141 5 55 7 0 9
AirBase 449 MiB 38 273 MiB 14,512,851 1 111 5 0 11
MedLineDesc 260 MiB 1 195 MiB 10,401,847 5 66 8 0 9
ZDNET 130 MiB 95,663 133 MiB 3,060,186 21 40 90 0 13
JMNEdict 124 MiB 1 171 MiB 8,592,666 0 10 0 0 5
XMark 111 MiB 1 130 MiB 3,221,926 2 74 9 0 13
Freshmeat 105 MiB 1 86 MiB 3,832,028 1 58 1 0 6
DeepFS 83 MiB 1 93 MiB 4,842,638 4 3 6 0 21
Treebank 82 MiB 1 92 MiB 3,829,513 1 250 1 0 37
DBLP2 80 MiB 170,843 102 MiB 4,044,649 4 35 6 0 6
DDI 76 MiB 3 39 MiB 2,070,157 7 104 16 21 11
Alfred 75 MiB 1 68 MiB 3,784,285 0 60 0 0 6
University 56 MiB 6 66 MiB 3,468,606 1 28 4 0 5
MediaUKN 38 MiB 1 45 MiB 1,619,443 3 21 3 0 5
HCIBIB2 32 MiB 26,390 33 MiB 617,023 1 39 1 0 4
Nasa 24 MiB 1 25 MiB 845,805 2 61 8 1 9
MovieDB 16 MiB 1 19 MiB 868,980 6 7 8 0 4
KanjiDic2 13 MiB 1 18 MiB 917,833 3 27 10 0 6
XMark 11 MiB 1 13 MiB 324,274 2 74 9 0 13
Shakespeare 7711 KiB 1 9854 KiB 327,170 0 59 0 0 9
TreeOfLife 5425 KiB 1 7106 KiB 363,560 7 4 7 0 243
Thesaurus 4288 KiB 1 4088 KiB 201,798 7 33 9 0 7
MusicXML 3155 KiB 17 2942 KiB 171,400 8 179 56 0 8
BibDBPub 2292 KiB 3,465 2359 KiB 80,178 1 54 1 0 4
Factbook 1743 KiB 1 1560 KiB 77,315 16 23 32 0 6
XMark 1134 KiB 1 1334 KiB 33,056 2 74 9 0 13
Sources Statistics 220
Instances Source
AirBase [1]
Alfred [2]
BibDBPub [3]
CoPhIR http:/ / cophir. isti. cnr. it/
DBLP http:/ / dblp. uni-trier. de/ xml
DBLP2 [3]
DDI http:/ / tools. ddialliance. org/
EnWikiMeta [4]
EnWikipedia [5]
EnWikiRDF http:/ / www. xml-benchmark. org/ generated with xmlgen
EnWiktionary [6]
EURLex http:/ / www. epsiplatform. eu/
Factbook [7]
Freebase [8]
FreeDB [9]
Freshmeat [10]
Genome1 [11]
HCIBIB2 [3]
Inex2009 [12]
IntAct [13]
InterPro [14]
iProClass [15]
JMNEdict [16]
KanjiDic2 [17]
MedLine http:/ / www. nlm. nih. gov/ bsd
MeSH [18]
MovieDB [19]
MusicXML [20]
Nasa [7]
NewYorkTimes [21]
OpenStreetMap [22]
Organizations http:/ / www. data. gov/ raw/ 1358
RuWikiHist [23]
SDMX [24]
Shakespeare [25]
SwissProt [26]
Thesaurus [27]
Treebank [28] Statistics 221
TreeOfLife [29]
TrEMBL [26]
Wikicorpus [30]
XMark http:/ / www. xml-benchmark. org/ generated with xmlgen
ZDNET [3]
ZhWikiHist [31]
LibraryUKN generated from university library data
MediaUKN generated from university library data
DeepFS generated from filesystem structure
University generated from students test data
Feeds compiled from news feeds
Twitter compiled from Twitter feeds
References
[1] http:/ / air-climate. eionet. europa. eu/ databases/ airbase/ airbasexml
[2] http:/ / alfred. med. yale. edu/ alfred/ alfredWithDescription. zip
[3] http:/ / inex. is. informatik. uni-duisburg. de/ 2005/
[4] http:/ / dumps. wikimedia. org/ enwiki/ latest/ enwiki-latest-pages-meta-current. xml. bz2
[5] http:/ / dumps. wikimedia. org/ enwiki/ latest/ enwiki-latest-pages-articles. xml. bz2
[6] http:/ / dumps. wikimedia. org/ enwiktionary/ latest/ enwiktionary-latest-pages-meta-history. xml. 7z
[7] http:/ / www. cs. washington. edu/ research/ xmldatasets/ www/ repository. html
[8] http:/ / download. freebase. com/ wex
[9] http:/ / www. xmldatabases. org/ radio/ xmlDatabases/ projects/ FreeDBtoXML
[10] http:/ / freshmeat. net/ articles/ freshmeat-xml-rpc-api-available
[11] ftp:/ / ftp. ncbi. nih. gov/ snp/ organisms/ human_9606/ XML/ ds_ch1. xml. gz
[12] http:/ / www. mpi-inf. mpg. de/ departments/ d5/ software/ inex
[13] ftp:/ / ftp. ebi. ac. uk/ pub/ databases/ intact/ current/ index. html
[14] ftp:/ / ftp. bio. net/ biomirror/ interpro/ match_complete. xml. gz
[15] ftp:/ / ftp. pir. georgetown. edu/ pir_databases/ iproclass/ iproclass. xml. gz
[16] ftp:/ / ftp. monash. edu. au/ pub/ nihongo/ enamdict_doc. html
[17] http:/ / www. csse. monash. edu. au/ ~jwb/ kanjidic2
[18] http:/ / www. nlm. nih. gov/ mesh/ xmlmesh. html
[19] http:/ / eagereyes. org/ InfoVisContest2007Data. html
[20] http:/ / www. recordare. com/ xml/ samples. html
[21] http:/ / www. nytimes. com/ ref/ membercenter/ nytarchive. html
[22] http:/ / dump. wiki. openstreetmap. org/ osmwiki-latest-files. tar. gz
[23] http:/ / dumps. wikimedia. org/ ruwiki/ latest/ ruwiki-latest-pages-meta-history. xml. 7z
[24] http:/ / www. metadatatechnology. com/
[25] http:/ / www. cafeconleche. org/ examples/ shakespeare
[26] ftp:/ / ftp. uniprot. org/ pub/ databases/ uniprot/ current_release/ knowledgebase
[27] http:/ / www. drze. de/ BELIT/ thesaurus
[28] http:/ / www. cs. washington. edu/ research/ xmldatasets
[29] http:/ / tolweb. org/ data/ tolskeletaldump. xml
[30] http:/ / www-connex. lip6. fr/ ~denoyer/ wikipediaXML
[31] http:/ / dumps. wikimedia. org/ zhwiki/ latest/ zhwiki-latest-pages-meta-history. xml. 7z Backups 222 Backups
This page is part of the Advanced User's Guide. The following two paragraphs demonstrate how to create a backup and restore the database within BaseX.
GUI Example 1. Start the BaseX GUI and create a new database in Database → New... with your XML document. 2. Go to Database → Manage... and create a backup of your database. The backup will be created in the database directory. 3. Go to Database → Add... and add another document. 4. Go to Database → Manage... and restore your database. The database will be restored from the latest backup of to the database found in the database directory.
Console Example 1. Start the BaseX Standalone client from a console. 2. Create a new database via the CREATE DB command. 3. Use the CREATE BACKUP command to back up your database. 4. Add a new document via ADD: ADD AS newdoc.xml
User Management
This article is part of the Advanced User's Guide. The user management defines which permissions are required by a user to perform a specific database command. In the permission hierarchy below, the existing permissions are illustrated. A higher permission includes all lower permissions. For example, all users who have the WRITE permission assigned will also be able to execute commands requiring READ permission. Next, local permissions can be assigned to databases, which override global user settings.
Permissions hierarchy
User names must follow the valid names constraints. User Management 223
Commands Admin permissions are needed to execute all of the following commands: Creating user 'test' (password will be entered on command line): > CREATE USER test Change user 'test' password (password will be entered on command line): > ALTER USER test As global permissions, you can set 'none', 'read', 'write', 'create' and 'admin': Grant all permissions to user 'test': > GRANT admin TO test Valid local permissions are 'none', 'read' and 'write': Granting write permission on database 'factbook' to user 'test': > GRANT write ON factbook TO test Note: Local permissions overwrite global permissions. As a consequence, the 'test' user will only be allowed to access (i.e., read and write) the 'factbook' database. If no local permissions are set, the global rights are inherited. Showing global permissions: > SHOW USERS Showing local permissions on database 'factbook': > SHOW USERS ON factbook Dropping of user 'test': > DROP USER test Transaction Management 224 Transaction Management
This article is part of the Advanced User's Guide. The BaseX client-server architecture offers ACID safe transactions, with multiple readers and single writers. Here are some more informations about the transaction management.
Transaction In a nutshell, a transaction is equal to a command or query. So each command or query sent to the server becomes a transaction. Incoming requests are parsed and checked for errors on the server. If the command or query is not correct, the request will not be executed, and the user will receive an error message. Otherwise the request becomes a transaction and gets into the transaction monitor. Note: An unexpected abort of the server during a transaction, caused by a hardware failure or power cut, will probably lead to an inconsistent database state if a transaction was active at the shutdown time. So we advise to use the BACKUP command to backup your database regularly. If the worst case occurs you can restore the database with the RESTORE command.
Update Transactions Update transactions are mainly update queries. When executing a XQuery Update query, all update operations of the query are stored in a pending update list. They will be executed all at once, so the database is updated atomically. If any of the update sub-operations is erroneous, the overall transaction will be aborted.
Concurrency Control The concurrency control checks for each transaction, which will perform a read or write operation on the database, the status of the lock object and decides whether the isolation is guaranteed for that transaction or not. If the isolation can be guaranteed the transaction will be started immediately. Otherwise, the transaction enters a waiting queue and waits till the transaction monitor validates and starts the transaction. The transaction monitor starts either the next writing transaction or the next group of reading transactions (if there are any on the queue).
Transaction Monitor The transaction monitor ensures that just one writing transaction is active at the same time. This seems to be an odd mechanism, but it is needed since the complexity of updates increased and it is possible now to access multiple databases in one XQuery Update query. To avoid starvation of any transaction and wrong execution orders the waiting queue works with the FIFO principle ('First-In First-Out'), which states that the first process that arrives at the server will be the first one that will be executed. The FIFO principle cannot be adhered in a group of reading transactions, as they run in different threads and thus can overtake each other. The use of the monitor also prevents the system from deadlocks, because the critical resource is only assigned to one writing transaction resp. a group of reading transactions. Logging 225 Logging
This article is part of the Advanced User's Guide. It describes how client operations are logged by the server.
Introduction The server logs give you the following advantages: • Overview about all processes executed on your server • Tracing of any errors thrown by BaseX • Tracing of wrong modified data • Tracing of all specific user processes • Tracing of time specific processes The server logs are written in plain-text and can be opened with any editor. In your Database Directory, you can find a folder named .logs in which all log files are stored with the according date. Note that, depending on your OS and configuration, files and folders with a '.' prefix may be hidden.
Logformat Example
16:00:00.094 [127.0.0.1:3920] LOGIN admin OK 16:00:00.104 [127.0.0.1:3920] XQUERY 1 to 10 OK 12.36 ms 16:00:00.114 [127.0.0.1:3920] LOGOUT admin OK
Now you can see the 'admin' user has the IP 127.0.0.1 with the socketport 3920. With this information you can identify each transaction of the corresponding user. Example
10:06:36.498 [127.0.0.1:49990] LOGIN admin OK
10:06:53.297 [127.0.0.1:49990] XQUERY 1 to 10 OK 17.89 ms
10:07:03.353 [127.0.0.1:49993] LOGIN testuser OK
10:07:08.259 [127.0.0.1:49993] XQUERY 1 to z Error: Stopped at line 1, column 6: [XPDY0002] No context item set for 'z'. 9.69 ms
10:07:15.505 [127.0.0.1:49990] LOGOUT admin OK
10:07:19.790 [127.0.0.1:49993] LOGOUT testuser OK
Now you can see the 'admin' user has the IP 127.0.0.1 with the socketport 49990 and the 'testuser' has the IP 127.0.0.1 with the socketport 49993. With this information you can identify each transaction of the corresponding user. The 'testuser' for example executed a query which was aborted by a syntax error. Events 226 Events
This article is part of the Advanced User's Guide. it presents how to trigger database events and notify listening clients.
Introduction The events feature enables users with admin permissions to create events, which can then be watched by other clients. All clients that have registered for an event will be notified if an event is triggered by another client.
Managing Events CREATE EVENT [name] Creates an event [name]. DROP EVENT [name] Drops the event with the specified [name]. SHOW EVENTS Shows all events.
Watching/Unwatching Events The events can currently be watched by the Java [1] and C# [1] clients. See the following Java code example: Watch events:
// name of the event String event = "call"; // create new client BaseXClient client = new BaseXClient("localhost", 1984, "admin", "admin"); // register for an event client.watch(event, new EventNotifier() { @Override public void notify(final String value) { System.out.println("Received data: " + value); } });
Unwatch events:
// unregister from an event client.unwatch(event);
For a complete and self-contained example in Java, you may have a look [2]. Events 227
Firing Events Events are triggered via the XQuery function db:event(): db:event($name as xs:string, $query as item()) Executes a $query and sends the resulting value to all clients watching the event with the specified $name. No event will be sent to the client that fired the event.
Example Scenarios
Basic 1. Client1 creates an event with the name "EVENT" 2. Client2 and Client3 call the watch method for event "EVENT" 3. Client1 executes XQuery
db:event("EVENT", "1 to 2")
4. Client2 and Client3 will receive the result 1 2 5. Client2 executes XQuery
db:event("EVENT", "2 to 3")
6. Client3 will receive the result 2 3
Included in Update Expression 1. Client1 creates an event with the name "DELETED" 2. Client2 and Client3 call the watch method for event "DELETED" 3. Client1 executes XQuery
let $deleted := //nodes return ( delete node $deleted, db:event( "DELETED", $deleted) )
4. Client2 and Client3 will receive the deleted nodes.
Included in Update Expression with Payload 1. Client1 creates an event with the name "DELETED" 2. Client2 and Client3 call the watch method for event "DELETED" 3. Client1 executes XQuery
let $deleted := //nodes return ( delete node $deleted, db:event( "DELETED",
4. Client2 and Client3 will receive the message with the payload and the deleted nodes. Events 228
References
[1] https:/ / github. com/ BaseXdb/ basex-api/ tree/ master/ src/ main/ java
[2] https:/ / github. com/ BaseXdb/ basex-examples/ blob/ master/ src/ main/ java/ org/ basex/ examples/ api/ EventExample. java
Indexes
This article is part of the Advanced User's Guide and introduces the available index structures, which may speed up querying by orders of magnitudes.
Index Structures Currently, the following index structures exist in BaseX:
Structural Indexes Structural indexes will always be present and cannot be dropped by the user: • Tag/Attribute Name Index All element and attribute names are automatically indexed and enriched with statistical information. • Path Summary Unique paths in a document or collection are referenced by the path index, which is applied e.g. to rewrite descendant to more specific child steps. • Document Index This index caches references to all document nodes in a database. It provides fast access to single documents in large database instances.
Value Indexes Value indexes can be dropped and created by the user: • Text Index This index speeds up equality tests and simple range queries on text nodes in XPath location steps with predicates. • Attribute Index This index speeds up equality tests and simple range queries on attribute value in XPath location steps with predicates. • Full-Text Index This index speeds up queries using the contains text keyword. Internally, BaseX handles two different index structures: the default index sorts all keys alphabetically by their character length. It is particularly fast if fuzzy searches are performed. The second index is a compressed trie structure, which needs slightly more memory, but is specialized on wildcard searches. With Version 7.1, a new database option was introduced to support incremental indexing of texts and attributes. Indexes 229
Example Queries The following queries are examples for expressions that will be optimized for index access (provided that the relevant index exists in a particular database):
Name/Path Index • //address is rewritten to addressbook/address if all address elements have an addressbook element as their only ancestor. • /non-existing-name is rewritten to an empty sequence
Text Index • //node()[text() = 'Usability'] • //div[p = 'Usability' or p = 'Testing'] • path/to/relevant[text() = 'Usability Testing']/and/so/on
Attribute Index • //node()[@align = 'right'] • descendant::elem[@id = '1'] • range/query[@id >= 1 and @id <= 5]
Full-Text Index • //node[text() contains text 'Usability'] • //node[text() contains text 'Usebiliti' using fuzzy] • //book[chapter contains text ('web' ftor 'WWW' using no stemming) ftand 'diversity' using stemming distance at most 5 words] Execution Plan 230 Execution Plan
This article is part of the Advanced User's Guide. For each execution of a query, BaseX creates an execution plan. This execution plan shows you each step of the query, so that you can evaluate your query and analyse if it accesses any indexes or not. You can activate the execution plan by activating the XMLPLAN or DOTPLAN options.
Examples
Execution plan for original and optimized query execution Query: for $item in doc(’xmark’)/descendant::item where $item/payment = ’Creditcard’ return $item Optimized query: doc(’xmark’)/descendant::item[payment = ’Creditcard’] Execution plan:
Replacing XQuery with equivalent XPath expressions
Execution plan for query execution with full-text index access and without Query: //MEDIUM/LAN[text() contains text "dt"] Execution plan:
Query Plan 2 Article Sources and Contributors 231 Article Sources and Contributors
Main Page Source: http://docs.basex.org/index.php?oldid=6358 Contributors: AW, CG, Dimitar, Elmedin, Lukas.kircher, MediaWiki default, Michael, Ralf Jung, 44 anonymous edits
Getting Started Source: http://docs.basex.org/index.php?oldid=6257 Contributors: AW, Arve, CG, Michael, 2 anonymous edits
Startup Source: http://docs.basex.org/index.php?oldid=6331 Contributors: AW, Arve, CG, Dimitar, Lukas.kircher, 1 anonymous edits
Startup Options Source: http://docs.basex.org/index.php?oldid=6081 Contributors: AW, CG, Holu, Michael
Start Scripts Source: http://docs.basex.org/index.php?oldid=6324 Contributors: AW, CG, François Parmentier, Holu, Michael
Graphical User Interface Source: http://docs.basex.org/index.php?oldid=6346 Contributors: AW, CG, Michael, 2 anonymous edits
Shortcuts Source: http://docs.basex.org/index.php?oldid=5606 Contributors: CG, Jens Erat
Database Server Source: http://docs.basex.org/index.php?oldid=6253 Contributors: AW, CG, Lukas.kircher
Standalone Mode Source: http://docs.basex.org/index.php?oldid=6254 Contributors: AW, CG, Lukas.kircher
Web Application Source: http://docs.basex.org/index.php?oldid=6380 Contributors: CG, Dimitar
Databases Source: http://docs.basex.org/index.php?oldid=5979 Contributors: AW, CG, Jens Erat, Lukas.kircher, Michael
Binary Data Source: http://docs.basex.org/index.php?oldid=5331 Contributors: CG
Parsers Source: http://docs.basex.org/index.php?oldid=5995 Contributors: AW, CG, Jidanni, Lukas.kircher, Michael, Mroth, 1 anonymous edits
Commands Source: http://docs.basex.org/index.php?oldid=6350 Contributors: AW, CG, Dimitar, Holu, Jan.vlcinsky, Jens Erat, Lukas.kircher, Michael
Options Source: http://docs.basex.org/index.php?oldid=6252 Contributors: AW, CG, Holu, Lukas.kircher, Michael, Mroth
Integrating oXygen Source: http://docs.basex.org/index.php?oldid=6264 Contributors: AW, CG, Michael
Integrating Eclipse Source: http://docs.basex.org/index.php?oldid=6172 Contributors: AW, CG
Querying Source: http://docs.basex.org/index.php?oldid=6003 Contributors: AW, CG, Dimitar, LeoWoerteler, Michael, Mroth, Ralf Jung, Rosishadura, 1 anonymous edits
XQuery 3.0 Source: http://docs.basex.org/index.php?oldid=6013 Contributors: CG, Dknippers, LeoWoerteler, Michael
Higher-Order Functions Source: http://docs.basex.org/index.php?oldid=6033 Contributors: CG, LeoWoerteler, Michael
Full-Text Source: http://docs.basex.org/index.php?oldid=5496 Contributors: CG, Dimitar, Michael, Piotr Banski, 8 anonymous edits
Full-Text/Japanese Source: http://docs.basex.org/index.php?oldid=5343 Contributors: CG
XQuery Update Source: http://docs.basex.org/index.php?oldid=5670 Contributors: AW, CG, Dknippers, Holu, Lukas.kircher, Michael, Mroth, 7 anonymous edits
Java Bindings Source: http://docs.basex.org/index.php?oldid=5553 Contributors: AW, CG, Dimitar, Dknippers, Michael, 7 anonymous edits
Packaging Source: http://docs.basex.org/index.php?oldid=5663 Contributors: AW, CG, Lukas.kircher, Michael, Rosishadura
XQuery Errors Source: http://docs.basex.org/index.php?oldid=5598 Contributors: CG, Lukas.kircher, Rosishadura
Serialization Source: http://docs.basex.org/index.php?oldid=6392 Contributors: CG, Jidanni, Michael
Cryptographic Module Source: http://docs.basex.org/index.php?oldid=5921 Contributors: CG, Lukas.kircher, Michael
Database Module Source: http://docs.basex.org/index.php?oldid=6153 Contributors: AW, CG, Dimitar, Holu, Lukas.kircher, Michael, 17 anonymous edits
File Module Source: http://docs.basex.org/index.php?oldid=5463 Contributors: AW, CG, Dimitar, Michael, Rosishadura, 1 anonymous edits
Full-Text Module Source: http://docs.basex.org/index.php?oldid=5923 Contributors: AW, CG
HTTP Module Source: http://docs.basex.org/index.php?oldid=5806 Contributors: CG, Rosishadura
Higher-Order Functions Module Source: http://docs.basex.org/index.php?oldid=6002 Contributors: CG, LeoWoerteler
Index Module Source: http://docs.basex.org/index.php?oldid=5925 Contributors: AW, CG
JSON Module Source: http://docs.basex.org/index.php?oldid=5926 Contributors: CG, Michael
Map Module Source: http://docs.basex.org/index.php?oldid=5467 Contributors: CG, Dknippers, Holu, LeoWoerteler
Math Module Source: http://docs.basex.org/index.php?oldid=5468 Contributors: AW, CG, Michael, 3 anonymous edits
Repository Module Source: http://docs.basex.org/index.php?oldid=5987 Contributors: CG, Rosishadura
SQL Module Source: http://docs.basex.org/index.php?oldid=5930 Contributors: CG, Michael, Rosishadura
Utility Module Source: http://docs.basex.org/index.php?oldid=5990 Contributors: AW, CG, LeoWoerteler, Leonard.woerteler, Lukas.kircher, Michael, Mroth, 1 anonymous edits
XSLT Module Source: http://docs.basex.org/index.php?oldid=5488 Contributors: CG
ZIP Module Source: http://docs.basex.org/index.php?oldid=6213 Contributors: AW, CG
ZIP Module: Word Documents Source: http://docs.basex.org/index.php?oldid=6214 Contributors: AW, CG
Developing Source: http://docs.basex.org/index.php?oldid=6359 Contributors: AW, Arve, CG, Michael, Ralf Jung
Integrate Source: http://docs.basex.org/index.php?oldid=6164 Contributors: AW, CG, Dimitar, Michael, Mroth
Git Source: http://docs.basex.org/index.php?oldid=4622 Contributors: CG, Dimitar, Michael
Maven Source: http://docs.basex.org/index.php?oldid=5810 Contributors: CG, Lukas.kircher, Michael, 2 anonymous edits
Releases Source: http://docs.basex.org/index.php?oldid=6365 Contributors: CG
Translations Source: http://docs.basex.org/index.php?oldid=5625 Contributors: CG Article Sources and Contributors 232
REST Source: http://docs.basex.org/index.php?oldid=6386 Contributors: Arve, CG, Lukas.kircher, LukasL, Michael, Ralf Jung
REST: POST Schema Source: http://docs.basex.org/index.php?oldid=6284 Contributors: CG
RESTXQ Source: http://docs.basex.org/index.php?oldid=6387 Contributors: Arve, CG
WebDAV Source: http://docs.basex.org/index.php?oldid=6390 Contributors: CG, Dimitar, Jens Erat
WebDAV: Windows 7 Source: http://docs.basex.org/index.php?oldid=6293 Contributors: CG
WebDAV: Windows XP Source: http://docs.basex.org/index.php?oldid=6291 Contributors: CG
WebDAV: Mac OSX Source: http://docs.basex.org/index.php?oldid=6292 Contributors: CG
WebDAV: GNOME Source: http://docs.basex.org/index.php?oldid=6290 Contributors: CG
WebDAV: KDE Source: http://docs.basex.org/index.php?oldid=6289 Contributors: CG
Clients Source: http://docs.basex.org/index.php?oldid=6304 Contributors: AW, CG, Holu, Michael
Standard Mode Source: http://docs.basex.org/index.php?oldid=5247 Contributors: AW, CG, Michael
Query Mode Source: http://docs.basex.org/index.php?oldid=6043 Contributors: AW, CG, Michael
PHP Example Source: http://docs.basex.org/index.php?oldid=6306 Contributors: AW, CG, Dimitar, Michael
Server Protocol Source: http://docs.basex.org/index.php?oldid=6217 Contributors: CG, Lukas.kircher, Michael
Server Protocol: Types Source: http://docs.basex.org/index.php?oldid=6215 Contributors: CG
Java Examples Source: http://docs.basex.org/index.php?oldid=6298 Contributors: AW, CG, Lukas.kircher, Michael, Mroth, 1 anonymous edits
Advanced User's Guide Source: http://docs.basex.org/index.php?oldid=5408 Contributors: CG
Configuration Source: http://docs.basex.org/index.php?oldid=6277 Contributors: AW, CG, Lukas.kircher
Catalog Resolver Source: http://docs.basex.org/index.php?oldid=5939 Contributors: CG, Gimsieke, Michael, Mroth, 3 anonymous edits
Statistics Source: http://docs.basex.org/index.php?oldid=4508 Contributors: AW, CG, Mroth
Backups Source: http://docs.basex.org/index.php?oldid=6189 Contributors: AW, CG, Dimitar, Michael
User Management Source: http://docs.basex.org/index.php?oldid=5978 Contributors: AW, CG, Jens Erat, Kulnor, Michael
Transaction Management Source: http://docs.basex.org/index.php?oldid=5167 Contributors: AW, CG, Elmedin, Lukas.kircher, Michael, Mroth
Logging Source: http://docs.basex.org/index.php?oldid=6273 Contributors: AW, CG, Michael, Mroth
Events Source: http://docs.basex.org/index.php?oldid=6366 Contributors: AW, CG, Dimitar, Michael
Indexes Source: http://docs.basex.org/index.php?oldid=6357 Contributors: AW, CG, Lukas.kircher, Michael, Mroth, 4 anonymous edits
Execution Plan Source: http://docs.basex.org/index.php?oldid=5409 Contributors: AW, CG, Dimitar, Leonard.woerteler, Michael Image Sources, Licenses and Contributors 233 Image Sources, Licenses and Contributors
Image:Screenshot.png Source: http://docs.basex.org/index.php?title=File:Screenshot.png License: unknown Contributors: CG Image:TextView.jpg Source: http://docs.basex.org/index.php?title=File:TextView.jpg License: unknown Contributors: CG, Michael Image:MapView.jpg Source: http://docs.basex.org/index.php?title=File:MapView.jpg License: unknown Contributors: CG, Michael Image:TreeView.jpg Source: http://docs.basex.org/index.php?title=File:TreeView.jpg License: unknown Contributors: CG, Michael Image:FolderView.jpg Source: http://docs.basex.org/index.php?title=File:FolderView.jpg License: unknown Contributors: CG, Michael Image:Scatterplot.jpg Source: http://docs.basex.org/index.php?title=File:Scatterplot.jpg License: unknown Contributors: CG, Michael Image:TableView.jpg Source: http://docs.basex.org/index.php?title=File:TableView.jpg License: unknown Contributors: CG, Michael Image:ExplorerView.jpg Source: http://docs.basex.org/index.php?title=File:ExplorerView.jpg License: unknown Contributors: CG, Michael Image:InfoView.png Source: http://docs.basex.org/index.php?title=File:InfoView.png License: unknown Contributors: CG File:Webdav-oxygen01.png Source: http://docs.basex.org/index.php?title=File:Webdav-oxygen01.png License: unknown Contributors: Dimitar File:Webdav-oxygen02.png Source: http://docs.basex.org/index.php?title=File:Webdav-oxygen02.png License: unknown Contributors: CG File:Git01.png Source: http://docs.basex.org/index.php?title=File:Git01.png License: unknown Contributors: CG, Michael File:Git02.png Source: http://docs.basex.org/index.php?title=File:Git02.png License: unknown Contributors: CG, Michael File:Git03.png Source: http://docs.basex.org/index.php?title=File:Git03.png License: unknown Contributors: CG, Michael File:Git04.png Source: http://docs.basex.org/index.php?title=File:Git04.png License: unknown Contributors: CG, Michael File:Git05.png Source: http://docs.basex.org/index.php?title=File:Git05.png License: unknown Contributors: CG, Michael File:Git06.png Source: http://docs.basex.org/index.php?title=File:Git06.png License: unknown Contributors: CG, Michael File:Git07.png Source: http://docs.basex.org/index.php?title=File:Git07.png License: unknown Contributors: CG, Michael File:Git08.png Source: http://docs.basex.org/index.php?title=File:Git08.png License: unknown Contributors: CG, Michael File:Git09.png Source: http://docs.basex.org/index.php?title=File:Git09.png License: unknown Contributors: CG, Michael File:Git10.png Source: http://docs.basex.org/index.php?title=File:Git10.png License: unknown Contributors: CG, Michael File:Webdav-explorer01.png Source: http://docs.basex.org/index.php?title=File:Webdav-explorer01.png License: unknown Contributors: CG, Dimitar File:Webdav-explorer03.png Source: http://docs.basex.org/index.php?title=File:Webdav-explorer03.png License: unknown Contributors: CG, Dimitar File:Webdav-explorer04.png Source: http://docs.basex.org/index.php?title=File:Webdav-explorer04.png License: unknown Contributors: CG, Dimitar File:Webdav-explorer06.png Source: http://docs.basex.org/index.php?title=File:Webdav-explorer06.png License: unknown Contributors: CG, Dimitar File:Webdav-explorer07.png Source: http://docs.basex.org/index.php?title=File:Webdav-explorer07.png License: unknown Contributors: CG, Dimitar File:WinXP01.png Source: http://docs.basex.org/index.php?title=File:WinXP01.png License: unknown Contributors: CG File:WinXP02.png Source: http://docs.basex.org/index.php?title=File:WinXP02.png License: unknown Contributors: CG File:WinXP03.png Source: http://docs.basex.org/index.php?title=File:WinXP03.png License: unknown Contributors: CG File:WinXP04.png Source: http://docs.basex.org/index.php?title=File:WinXP04.png License: unknown Contributors: CG File:WinXP05.png Source: http://docs.basex.org/index.php?title=File:WinXP05.png License: unknown Contributors: CG File:WinXP06.png Source: http://docs.basex.org/index.php?title=File:WinXP06.png License: unknown Contributors: CG File:WinXP07.png Source: http://docs.basex.org/index.php?title=File:WinXP07.png License: unknown Contributors: CG File:WinXP08.png Source: http://docs.basex.org/index.php?title=File:WinXP08.png License: unknown Contributors: CG File:Webdav-osx-1.jpg Source: http://docs.basex.org/index.php?title=File:Webdav-osx-1.jpg License: unknown Contributors: Jens Erat File:Webdav-osx-2.jpg Source: http://docs.basex.org/index.php?title=File:Webdav-osx-2.jpg License: unknown Contributors: Jens Erat File:Webdav-osx-3.jpg Source: http://docs.basex.org/index.php?title=File:Webdav-osx-3.jpg License: unknown Contributors: Jens Erat File:Webdav-osx-4.jpg Source: http://docs.basex.org/index.php?title=File:Webdav-osx-4.jpg License: unknown Contributors: Jens Erat File:webdav-nautilus01.png Source: http://docs.basex.org/index.php?title=File:Webdav-nautilus01.png License: unknown Contributors: Dimitar File:webdav-nautilus02.png Source: http://docs.basex.org/index.php?title=File:Webdav-nautilus02.png License: unknown Contributors: Dimitar File:webdav-nautilus03.png Source: http://docs.basex.org/index.php?title=File:Webdav-nautilus03.png License: unknown Contributors: Dimitar File:webdav-dolphin01.png Source: http://docs.basex.org/index.php?title=File:Webdav-dolphin01.png License: unknown Contributors: Dimitar File:webdav-dolphin02.png Source: http://docs.basex.org/index.php?title=File:Webdav-dolphin02.png License: unknown Contributors: Dimitar File:webdav-dolphin03.png Source: http://docs.basex.org/index.php?title=File:Webdav-dolphin03.png License: unknown Contributors: Dimitar File:perms.png Source: http://docs.basex.org/index.php?title=File:Perms.png License: unknown Contributors: AW, CG File:QueryPlan1.png Source: http://docs.basex.org/index.php?title=File:QueryPlan1.png License: unknown Contributors: AW, CG File:QueryPlan2.png Source: http://docs.basex.org/index.php?title=File:QueryPlan2.png License: unknown Contributors: AW, CG License 234 License
Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0)
http:/ / creativecommons. org/ licenses/ by-sa/ 3. 0/