<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: java-admin-client.xml 18236 2013-02-06 10:04:57Z wolfgang_m $ --><book><bookinfo><productname>eXist-db – Open Source Native XML Database</productname><title>Java Admin Client</title><date>October 2012</date></bookinfo><chapter id="ch01"><title>Java Admin Client</title><section id="introduction"><title>Introduction</title><para>eXist-db ships with a Java-based 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. The Client can be
                used either as a graphical interface or on the command line.</para></section><section id="launching"><title>Launching the Client</title><para>You can launch the Java Admin Client using one of the following methods:</para><itemizedlist><listitem><para>Windows and Linux users: Double-click on the <guibutton>Java Admin
                            Client</guibutton> desktop shortcut icon (if the option to create
                        desktop shortcuts was selected during installation) or select the shortcut
                        icon from the Start Menu (if the option to select Start Menu entries was
                        selected during installation)</para></listitem><listitem><para>You can download a Java WebStart file (exist.jnlp) via your web browser;
                        once the download has completed, double-click on the exist.jnlp file to
                        launch the client: </para><para><ulink url="/webstart/exist.jnlp"><inlinemediaobject><imageobject><imagedata fileref="resources/webstart.small.jpg"/></imageobject></inlinemediaobject></ulink></para><para>You can also find a Java WebStart <guibutton>Launch</guibutton> icon in the Administration menu
                        in the left sidebar of all documentation pages.</para><note><para>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: 
                            <synopsis format="linespecific">build.bat -f build/scripts/jarsigner.xml (DOS/Windows)</synopsis><synopsis format="linespecific">build.sh -f build/scripts/jarsigner.xml  (Unix)</synopsis></para></note></listitem><listitem><para>Enter the following on your command line from the eXist directory (with the JAVA_HOME
                        environmental variable set correctly):</para><synopsis format="linespecific">bin\client.bat (DOS/Windows)</synopsis><synopsis format="linespecific">bin/client.sh (Unix)</synopsis></listitem><listitem><para>Enter the following on the command line:</para><synopsis>java -jar start.jar client</synopsis></listitem></itemizedlist></section><section id="gui"><title>Using the Graphical Client</title><para>Once the Graphical Client is launched, you will see the "eXist Database Login" window.</para><screenshot><graphic fileref="resources/client1.png"/></screenshot><para>Enter your eXist-db username and password, select "Remote" from the "Type" dropdown menu, and in the URL field enter the URI for your database. By
                default, the URI for your database is
                xmldb:exist://localhost:8080/exist/xmlrpc.</para><note><para>The Java Admin Client can either connect to a "remote" server—as demonstrated
                    here—or it can launch an "embedded 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.</para></note><para>After clicking "OK", the main client window will open.</para><screenshot><graphic fileref="resources/client2.png"/></screenshot><para>This window is split into two
                panels, and has a top menu and a toolbar. The top panel lists the database
                collections; the bottom panel is the "shell" and has a command prompt. This shell
                allows you to manually enter database commands. Most commands, however, can be
                accessed using the menu. All of the menu and toolbar items have tooltips that explain
                their functions.</para><note><para>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 by following these steps:</para><orderedlist><listitem><para>Open the "Edit Users" window by selecting the "Manage Users" icon (image
                        of a pair of keys) in the toolbar</para></listitem><listitem><para>At the top, select the "admin" user in the table of users</para></listitem><listitem><para>Type in the new password into the password fields</para></listitem><listitem><para>Click the "Modify User" button to apply the changes</para></listitem></orderedlist><screenshot><graphic fileref="resources/client3.png"/></screenshot></note></section><section id="command-line"><title>Using the Command-line Client</title><para>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:</para><orderedlist continuation="restarts" inheritnum="ignore"><listitem><para>If an action is specified on the command-line, it will be processed in
            non-interactive mode and the client will terminate after completion.</para></listitem><listitem><para>Without an action, the client switches to interactive mode and displays the
            graphical user interface.</para></listitem><listitem><para>If option <option>-s</option> or <option>--no-gui</option> is specified without an
            action, the client switches to shell-mode and prompts for user input. No graphical
            interface is displayed.</para></listitem></orderedlist><section><title>Interactive Shell Mode</title><para>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 <command moreinfo="none">help</command> to get a list of supported commands.</para><para>The shell mode may support full command line history and command completion, depending
        on your type of operating system. 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
          <filename moreinfo="none">lib/core/libJavaReadline.so</filename> has to be found by the
        system's loader. On Linux, just add <filename moreinfo="none">lib/core</filename> to your
          <option>LD_LIBRARY_PATH</option> (the client.sh script does this automatically).</para><para>On Windows OS, you should at least be able to use the cursor-up/cursor-down keys to
        browse through the command history.</para><para>To explain the shell-mode, we just provide a short example, showing how to store the
        sample files into the database. Typing <command moreinfo="none">mkcol shakespeare</command>
        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
          <command moreinfo="none">ls</command> to get a listing of the current collection contents.
        The listing below shows an example session of how to add the sample documents:</para><example><title>Adding the sample documents</title><screen format="linespecific">
exist:/db&gt;mkcol shakespeare
created collection.
exist:/db&gt;cd shakespeare
exist:/db/shakespeare&gt;mkcol plays
created collection.
exist:/db/shakespeare&gt;cd plays
exist:/db/shakespeare/plays&gt;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&gt; cd
exist:/db&gt;mkcol library
created collection.
exist:/db&gt;cd library
exist:/db/library&gt;put samples/biblio.rdf
storing document biblio.rdf (1 of 1) ...done.
exist:/db/library&gt;cd
exist:/db&gt;mkcol xinclude
created collection.
exist:/db&gt;cd xinclude
exist:/db/xinclude&gt;put samples/xinclude
</screen></example><para>Adding files to the database is done using put. Put 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. To see if the files have actually
        been stored, you may view the contents of the current collection with ls. To view a
        document, use the get command, e.g.:</para><synopsis format="linespecific">get hamlet.xml</synopsis><note><para><command moreinfo="none">put</command> also accepts file-patterns, i.e. a path with
          wildcards ? or *. ** means: any sub-directory. So the command <command moreinfo="none">put
            samples/**/*.xml</command> will parse any XML files found in the <filename moreinfo="none">samples</filename> directory and any of its sub-directories. </para></note><note><para>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 <filename moreinfo="none">.dbx</filename>. You will either
          find them in directory <filename moreinfo="none">webapp/WEB-INF/data</filename> or
            <filename moreinfo="none">WEB-INF/data</filename>, depending on your installation. It is
          also ok to backup those data-files to be able to restore them in case of a database
          corruption.</para></note></section><section><title>Specifying Parameters</title><para>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
        form with <command>-u user</command> or in long form <command>--user=user</command>. You can
        also combine argument-less parameters: for example, <command>-ls</command> is short for
          <command>-l -s</command>.</para></section><section><title>General Configuration</title><para>The client reads its default options from the properties file <filename moreinfo="none">client.properties</filename>. Most of the properties can be overwritten by command-line
        parameters or by the <command moreinfo="none">set</command> command in shell-mode.</para><para>The client relies on the XML:DB API to communicate with the database. It will thus 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 <ulink url="deployment.xml"> deployment</ulink> document describes
        how different servers are addressed by the XML:DB URI.</para><para>The XML:DB base URI used by the client for connections is defined by the
        <option>uri=</option> property. By default, this is set to
          <option>uri=xmldb:exist://localhost:8080/exist/xmlrpc</option>. The client will thus try
        to connect to a database instance running inside the webserver at port 8080 of the local
        host. This doesn't mean that the client is not communicating through the network. In fact,
        any XML:DB URI containing a host part is accessed through the XMLRPC protocol.</para><para>There are several ways to specify an alternate XML:DB base URI: first, you may change
        the <option>uri=</option> property in <filename moreinfo="none">client.properties</filename>. Second, you may use the <option>-ouri</option> parameter on the
        command-line to temporarily select another target for the connection. For example, to start
        the client in local mode, use:</para><synopsis format="linespecific">bin/client.sh -ouri=xmldb:exist://</synopsis><para>To access a server running inside the Jetty webserver at port 8080 on a remote host, use</para><synopsis format="linespecific">bin/client.sh -ouri=xmldb:exist://host:8080/exist/xmlrpc</synopsis><para><emphasis>Local mode</emphasis> means here, that an embedded database instance will be
        initialized and started by the client. It will thus 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.</para><para>Using the <option>-ouri</option>, you can temporarily change any property specified in the
        properties file. Since switching to local mode is required quite often, there's also a
        shortcut: specifying</para><synopsis format="linespecific">bin/client.sh -l</synopsis><para>is equivalent to the <option/><command>-ouri=xmldb:exist://</command> option shown
        above.</para><para>If you have set a password for the admin user (as described in the <ulink url="security.xml">security</ulink> doc), you may have to authenticate yourself to the
        database. In this case, specify the <option>-u username</option> on the command line, e.g.</para><synopsis format="linespecific">bin/client.sh -l -u peter -P somepass</synopsis><para>If the <option>-P</option> password option is missing, the client will prompt for the
        password.</para><note><para>The graphical user interface will always prompt for username and password unless you
          specify both on the command-line.</para></note></section><section><title>Storing documents</title><para>To store a set of documents, use the <option>-m</option> and <option>-p</option>
        parameters, e.g.</para><synopsis format="linespecific">bin/client.sh -m /db/shakespeare/plays -p /home/exist/xml/shakespeare</synopsis><para>The <option>-m</option> argument differs from the <option>-c</option> option, because it
        tells the client to implicitely create any missing collection. The <option>-p</option>
        parameter means that all of the following arguments should be interpreted as a list of paths
        to XML documents, i.e. you may specify more than one document or directory.</para><para>If the passed path denotes a directory, the client will try to store all documents in
        that directory to the database. However, it will not recurse into subdirectories. For this,
        you have to pass the <option>-d</option>. For example,</para><synopsis format="linespecific">bin/client.sh -d -m /db/movies -p /home/exist/xml/movies</synopsis><para>will recurse into all directories below <filename moreinfo="none">/home/exist/xml/movies</filename>. For each subdirectory, a collection will be created
        below the <filename moreinfo="none">/db/movies</filename> root collection, i.e. you may use
        this option to recursively import an entire collection tree.</para><note><para> eXist-db can also store binary resources in addition to XML files. The client thus tries
          to determine if the current file is XML or not. File <filename>mime-types.xml</filename>
          allows to associate : <itemizedlist><listitem><para>a MIME type</para></listitem><listitem><para>an eXist-db type ("xml" or "binary")</para></listitem><listitem><para>a file extension</para></listitem></itemizedlist>
                     This is also used by the eXist-db servers . For example to specify that
          .xmap extension is used for XML files you can specify it like this in mime-types.xml: <programlisting>  
			    
&lt;mime-type name="application/xml" type="xml"&gt;
 &lt;description&gt;XML document&lt;/description&gt;  
 &lt;extensions&gt;.xml,.xsl,.xsd,.mods,.xmi,.xconf,.xslt,.wsdl,.x3d,.rdf,.owl,.xmap&lt;/extensions&gt;  
&lt;/mime-type&gt;  
			  </programlisting></para></note></section><section><title>Removing Collections/Documents</title><para>The <option>-r</option> and <option>-R</option> parameters are used to remove a document
        or collection. <option>-r</option> removes a single document from the collection specified
        in the <option>-c</option> parameter. For example,</para><synopsis format="linespecific">bin/client.sh -c /db/shakespeare/plays -r hamlet.xml</synopsis><para>removes the document <filename moreinfo="none">hamlet.xml</filename> from the <filename moreinfo="none">/db/shakespeare/plays</filename> collection. To remove the entire
          <filename moreinfo="none">plays</filename> collection, use</para><synopsis format="linespecific">bin/client.sh -c /db/shakespeare -R plays</synopsis></section><section><title>Executing Queries</title><para>To execute queries, use the <option>-x</option> 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 may
        interprete whitespace characters as command separators. Thus, if no argument is passed to
          <option>-x</option>, the client will try to read the query from standard input. For
        example, on Unix you may do</para><synopsis format="linespecific">echo "//SPEECH[contains(LINE, 'love')]" | bin/client.sh -x</synopsis><para>NB! remember to type Ctrl-d when working without pipe.</para><synopsis format="linespecific">bin/client.sh -x ENTER
      //SPEECH[contains(LINE, 'love')] ENTER Ctrl-d</synopsis><para>Queries can also be read from a file. For example,</para><synopsis>bin/client.sh -F samples/xquery/fibo.xq</synopsis><para>executes the XQuery contained in <filename>fibo.xq</filename>.</para><para>There's an additional parameter to be used in conjunction with <option>-x</option>:
          <option>-n</option> specifies the number of hits that should be printed to the standard
        output.</para></section><section><title>XUpdate</title><para>You may also update a stored document or multiple documents by passing an XUpdate file
        on the command-line. For
        example:<abbrev/><synopsis>bin/client.sh -c /db/test -f address.xml -X samples/xupdate/xupdate.xml</synopsis>This
        will apply the modifications described in
        <abbrev/><filename>samples/xupdate/xupdate.xml</filename> to the document
          <filename>address.xml</filename> in collection <filename>/db/test</filename>. If you skip
        the <option>-f</option> option, the modifications will be applied to all documents in the
        collection.</para></section><section><title>Using an Alternate Database Configuration</title><para>If you start the client with option <option>-l</option> or
        <command>-ouri=xmldb:exist://</command>, it will launch its own embedded database instance.
        By default, the configuration for the database instance is read from file
        <filename>conf.xml</filename> located in EXIST_HOME.</para><para>However, you may want to use another database installation, stored in an alternate
        location. To make this as simple as possible, option <option>-C</option> is provided. The
        parameter expects a configuration file as argument, for example:</para><synopsis>bin/client.sh -C /home/exist/test/conf.xml</synopsis><para>This will temporarily launch a new database instance, whose configuration is read from
        the provided file. As is obvious, option <option>-C</option> implies option
        <option>-l</option>.</para></section><section><title>Backup/Restore on the Command-Line</title><para>A simple backup/restore client can be launched through the <command moreinfo="none">bin/backup.sh</command> or <command moreinfo="none">bin\backup.bat</command> scripts. The client allows to backup any local or remote
        collection available through the XML:DB API. To backup a collection, use for example</para><synopsis format="linespecific">bin/backup.sh -d backup -u admin -p somepass -b /db -ouri=xmldb:exist://</synopsis><para>This will launch a database instance in local mode and backup the <filename moreinfo="none">/db</filename> root collection. A hierarchy of directories will be created
        below the <filename moreinfo="none">backup</filename> directory. The directories correspond
        to the hierarchy of collections found in the database.</para><para>The tool will also backup user permissions for each collection and document. This
        information is written into the special file <filename moreinfo="none">__contents__.xml</filename> placed in each subdirectory. You need these files to restore
        the database contents.</para><para>To restore the backuped data, use the <option>-r</option> option and pass one of the
          <filename moreinfo="none">__contents__.xml</filename> files as an argument. The tool will
        restore all files and collections described in the XML file, for example,</para><synopsis format="linespecific">bin/backup.sh -r backup/db/__contents__.xml -ouri=xmldb:exist://</synopsis><para>will restore the entire database, while</para><synopsis format="linespecific">bin/backup.sh -r backup/db/shakespeare/__contents__.xml -ouri=xmldb:exist://</synopsis><para>restores only the <filename moreinfo="none">/db/shakespeare</filename> collection.</para><para>Please note that users and groups are defined in the database collection <filename moreinfo="none">/db/system</filename>. This collection will thus be restored first.</para></section></section></chapter></book>