Java Admin Client

(2Q19)


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.

Launching the Client

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.

  • Enter the following on your command line from the eXist installation directory (with the JAVA_HOME environment variable set correctly):

    bin\client.bat (DOS/Windows)
    bin/client.sh (Unix)

Using the Graphical 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.

Warning:

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:

  1. Open the Edit Users window by selecting the Manage Users icon (image of a pair of keys) in the toolbar

  2. At the top, select the admin user in the table of users

  3. Type in the new password into the password fields

  4. Click the Modify User button to apply the changes

Using the Command-line Client

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:

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

  2. If option -s or --no-gui is specified without an action, the client switches to interactive shell-mode and prompts for user input. No graphical interface is displayed.

  3. Otherwise the client switches to interactive mode and displays the graphical user interface.

Interactive Shell Mode

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 readline library, 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.so has to be found by the system's loader. On Linux, just add lib/core to your 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.

  • Typing mkcol shakespeare and 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 ls to 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 samples/shakespeare simply enter put samples/shakespeare.

    put also accepts file-patterns, i.e. a path with wildcards ? or *. ** means: any sub-directory. So the command put samples/**/*.xml will parse any XML files found in the samples directory and any of its sub-directories.

  • To see if the files have actually been stored use ls again.

  • To view a document, use the get command, for instance get hamlet.xml

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 find them in directory $EXIST_HOME/data. It is ok to backup those data-files to be able to restore them in case of a database corruption.

Specifying Parameters

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 -l -s.

General Configuration

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:

  • Change the uri= property in client.properties

  • Use the -ouri parameter on the command-line

    For instance, to access a server running inside the Jetty webserver at port 8080 on a remote host, use

    bin/client.sh -ouri=xmldb:exist://host:8080/exist/xmlrpc
  • To start the client in local mode, use:

    bin/client.sh -ouri=xmldb:exist://

    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:

    bin/client.sh -l

    This is equivalent to the -ouri=xmldb:exist:// option shown above.

    When launching the client with option -l or -ouri=xmldb:exist:// the configuration for the database instance is read from conf.xml located in $EXIST_HOME/etc.

    Use the -C parameter 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 -C implies option -l.

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

If the -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.

Storing documents

To store a set of documents, use the -m and -p parameters. For instance:

bin/client.sh -m /db/shakespeare/plays -p /home/exist/xml/shakespeare
  • The -m tells the client to implicitly create any missing collection.

  • The -p parameter 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 -d option. 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/movies collection. 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:

<mime-type name="application/xml" type="xml">
  <description>
    XML document
  </description>
  <extensions>
    .xml,.xsl,.xsd,.mods,.xmi,.xconf,.xslt,.wsdl,.x3d,.rdf,.owl,.xmap
  </extensions>
</mime-type>

Removing Collections/Documents

The -r and -R parameters are used to remove a document or collection.

  • -r removes a single document from the collection specified in the -c parameter. For example:

    bin/client.sh -c /db/shakespeare/plays -r hamlet.xml

    This removes the document hamlet.xml from the /db/shakespeare/plays collection.

  • To remove the entire plays collection use the -R parameter:

    bin/client.sh -c /db/shakespeare -R plays

Executing Queries

Executing queries can be done as follows:

  • Use the -x parameter. 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 -F parameter. For example,

    bin/client.sh -F samples/xquery/fibo.xq

    This executes the XQuery contained in fibo.xq.

  • As an addition use -n to specify the number of hits that should be printed to the standard output.

XUpdate

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 /db/test.

If you don't specify the -f option, the modifications will be applied to all documents in the collection.