Java Admin Client
eXist-db ships with the so-called "Java Admin Client". This application enables users to perform administrative tasks, such as user management, security settings, batch import of whole directories, and backup/restore of the database. It can be used either as a GUI or on the command line.
You can launch the Java Admin Client using one of the following methods:
Windows and Linux users: Click the eXist-db icon in the taskbar and choose the Open Java Admin Client menu entry.
You can download its Java WebStart file
exist.jnlpvia your web browser. Once the download has completed, double-click it to launch the client:
You can also find a link to download the Java WebStart file on the dashboard.
If you built eXist-db from source rather than using the downloadable installer, the Java WebStart function will not work unless you sign the jars. To do so, enter the following on your command line from the eXist directory:
build.bat -f build/scripts/jarsigner.xml (DOS/Windows)
build.sh -f build/scripts/jarsigner.xml (Unix)
Enter the following on your command line from the eXist installation directory (with the
JAVA_HOMEenvironment variable set correctly):
Or enter the following on the command line (again from the eXist installation directory):
java -jar start.jar client
Once the Graphical Client is launched, you will see the "eXist Database Login" window.
The Java Admin Client can connect to a database in two ways:
Most common is to connect to a "remote" server. The client talks with the server using the XML RPC protocol.
It can also launch an "enbedded database", that is, a database embedded in an application which runs in the same process as the client. This embedded option is useful for backup/restore or mass uploads of data; writing to an embedded instance avoids the network overhead.
To connect to a remote server, enter your eXist-db username and password, select Remote from the
Type dropdown menu, and in the URL field enter the database's URI. This by default set to
xmldb:exist://localhost:8080/exist/xmlrpc (the URI for a database installed with all the default settings).
After clicking OK, the main client window will open.
This window is split into two panels. The top panel lists the database collections. The bottom panel acts like a shell and has a command prompt. This shell allows you to manually enter database commands.
Using the Java Admin Client as a GUI is like using any other GUI application. That is why we do not explain it further.
If eXist-db is online, you expose it to exploitation if you use an empty admin password. If you did not specify an admin password during installation, you are strongly advised to set an admin password as soon as possible. You can do this in the Java Admin Client:
Open the Edit Users window by selecting the Manage Users icon (image of a pair of keys) in the toolbar
At the top, select the admin user in the table of users
Type in the new password into the password fields
Click the Modify User button to apply the changes
It is sometimes faster or more convenient to use the Java Admin Client on the command line. The following sections provide a quick introduction to the most common command line parameters and their use. The client offers three modes of operation:
If an action is specified on the command-line (when starting the client), it will be processed in non-interactive mode and the client will terminate after completion.
--no-guiis specified without an action, the client switches to interactive shell-mode and prompts for user input. No graphical interface is displayed.
Otherwise the client switches to interactive mode and displays the graphical user interface.
While this tutorial will not describe the interactive shell mode in detail, most commands work like their counterparts specified on the
command line. On the shell, just type
help to get a list of supported commands.
The shell mode may support full command line history and command completion, depending on the OS
On Unix systems, the client will try to load the GNU
readlinelibrary, which is part of most Unix installations. This gives you access to all the nice things you probably know from Linux shells. For example, pressing the tab-key will try to complete collection and document names. However, for this to work, the native library
lib/core/libJavaReadline.sohas to be found by the system's loader. On Linux, just add
LD_LIBRARY_PATH(the client.sh script does this automatically).
On Windows OS, you should at least be able to use the cursor-up/cursor-down keys to browse through the command history.
To explain the shell-mode we provide a short example, showing how to store the sample files into the database.
mkcol shakespeareand pressing enter will create a Shakespeare collection into which we will put some of the sample documents provided with eXist-db.
To check if the new collection is present, enter
lsto get a listing of the current collection contents. The listing below shows an example session of how to add the sample documents:
exist:/db>mkcol shakespeare created collection. exist:/db>cd shakespeare exist:/db/shakespeare>mkcol plays created collection. exist:/db/shakespeare>cd plays exist:/db/shakespeare/plays>put samples/shakespeare/ storing document hamlet.xml (1 of 4) ...done. storing document much_ado.xml (2 of 4) ...done. storing document r_and_j.xml (3 of 4) ...done. storing document shakes.xsl (4 of 4) ...done. exist:/db/shakespeare/plays> cd exist:/db>mkcol library created collection. exist:/db>cd library exist:/db/library>put samples/biblio.rdf storing document biblio.rdf (1 of 1) ...done. exist:/db/library>cd exist:/db>mkcol xinclude created collection. exist:/db>cd xinclude exist:/db/xinclude>put samples/xinclude
Adding files to the database is done using
put. This expects either a single file, a file-pattern or a directory name as argument. If a directory is specified, all XML and XSL files in that directory will be put into the database.
To add the files in directory
putalso accepts file-patterns, i.e. a path with wildcards
**means: any sub-directory. So the command
put samples/**/*.xmlwill parse any XML files found in the
samplesdirectory and any of its sub-directories.
To see if the files have actually been stored use
To view a document, use the get command, for instance
If you ever run into problems while experimenting with eXist-db and your database files get corrupt: just remove the data files created
by eXist-db and everything should work again. The data files all end with
.dbx. You will either find them in directory
WEB-INF/data, depending on your installation. It is ok to backup those
data-files to be able to restore them in case of a database corruption.
The client uses the CLI library from Apache's Excalibur project to parse command-line parameters. This means that the same conventions apply as for most GNU tools. Most parameters have a short and a long form.
For example, the user can be specified in short with
-u user or in long with
--user=user. You can
combine argument-less parameters: for example,
-ls is short for
The client reads its default options from the properties file
client.properties. Most of the properties can be
overwritten by command-line parameters or by the
set command in shell-mode.
The client relies on the XML:DB API to communicate with the database. It will therefore work with remote as well as embedded database instances. The correct database instance is determined through the XML:DB base URI as specified in the properties file or through command-line options. The deployment article describes how different servers are addressed using the XML:DB URI.
The XML:DB base URI used by the client for connections is defined by the
uri= property. By default, this is set to
uri=xmldb:exist://localhost:8080/exist/xmlrpc. With this, the client will try to connect to a database instance running
inside the webserver at port 8080 of the local host.
There are several ways to specify an alternate XML:DB base URI:
-ouriparameter on the command-line
For instance, to access a server running inside the Jetty webserver at port
8080on a remote host, use
To start the client in local mode, use:
Local mode means that an embedded database instance will be initialized and started by the client. It will have direct access to the database instance. Use this option if you want to batch-load a large document or a huge collection of documents.
Since switching to local mode is required quite often, there's also a shortcut:
This is equivalent to the
-ouri=xmldb:exist://option shown above.
When launching the client with option
-ouri=xmldb:exist://the configuration for the database instance is read from
-Cparameter to specify an alternate database location. For instance:
bin/client.sh -C /home/exist/test/conf.xml
This will temporarily launch a new database instance whose configuration is read from the provided file. Option
If you have set a password for the admin user you must to authenticate yourself to the database:
bin/client.sh -l -u username -P password
-P password option is missing, the client will prompt for the password.
The graphical user interface will always prompt for username and password unless you specify both on the command-line.
To store a set of documents, use the
-p parameters. For instance:
bin/client.sh -m /db/shakespeare/plays -p /home/exist/xml/shakespeare
-mtells the client to implicitly create any missing collection.
-pparameter means that all of the following arguments should be interpreted as a list of paths to XML documents (you may specify more than one document or directory).
If the passed path denotes a directory, the client will try to store all documents in that directory into the database. However, it will not recurse into subdirectories. For this, you have to pass the
-doption. For example:
bin/client.sh -d -m /db/movies -p /home/exist/xml/movies
This will recurse into all directories below
/home/exist/xml/movies. For each subdirectory, a collection will be created below the
/db/moviescollection. Use this to recursively import an entire collection tree.
eXist-db can also store binary resources in addition to XML files. The client tries to determine if the current file is XML or not. The
mime-types.xml lookup table (in the eXist root installation directory) is used for this. It associates:
a MIME type
an eXist-db type ("xml" or "binary")
a file extension
This mechanism is also used by the eXist-db servers . For example to specify that
.xmap extension is used for XML files:
-R parameters are used to remove a document or collection.
-rremoves a single document from the collection specified in the
-cparameter. For example:
bin/client.sh -c /db/shakespeare/plays -r hamlet.xml
This removes the document
To remove the entire
playscollection use the
bin/client.sh -c /db/shakespeare -R plays
Executing queries can be done as follows:
-xparameter. This parameter accepts an optional argument, which specifies the query to execute. However, passing XQuery on the command-line is a problem on many operating systems, because the command shell usually interprets whitespace characters as command separators. Therefore if no argument is passed to
-x, the client will try to read the query from standard input.
For example, on Unix you may do the follwong:
echo "//SPEECH[contains(LINE, 'love')]" | bin/client.sh -x
Remember to type Ctrl-d when working without pipe:
bin/client.sh -x ENTER //SPEECH[contains(LINE, 'love')] ENTER Ctrl-d
Queries can also be read from a file using the
-Fparameter. For example,
bin/client.sh -F samples/xquery/fibo.xq
This executes the XQuery contained in
As an addition use
-nto specify the number of hits that should be printed to the standard output.
You can update a stored document or multiple documents by passing an XUpdate file on the command-line. For example:
bin/client.sh -c /db/test -f address.xml -X samples/xupdate/xupdate.xml
This will apply the modifications described in
samples/xupdate/xupdate.xml to the document
address.xml in collection
If you don't specify the
-f option, the modifications will be applied to all documents in the collection.