Java Admin Client

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

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 -c /db/shakespeare/plays -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 -c /db/movies -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.