<?xml version="1.0" encoding="UTF-8"?>
<book xmlns:ci="http://apache.org/cocoon/include/1.0">
  <bookinfo>
    <graphic fileref="logo.jpg"/>

    <productname>Open Source Native XML Database</productname>
    <title>Java Admin Client</title>
    <author>
      <firstname>Wolfgang M.</firstname>
      <surname>Meier</surname>
      <affiliation>
        <address format="linespecific"><email>wolfgang at exist-db.org</email></address>
      </affiliation>
    </author>
  </bookinfo>
  
  <ci:include src="sidebar.xml"/>
  
  <chapter id="ch01">
    <title>Using the Java Client on the Command Line</title>
    
    <para>eXist offers an integrated command-line and gui client. The <ulink url="quickstart.xml">QuickStart</ulink>
    shows a few screenshots of the graphical interface. However, it is also possible (and sometimes faster or 
    more convenient) to use the client on the command line. The following sections provide a quick introduction
    to the most common command line parameters and their use:</para>

    <section>
      <title>Introduction</title>
      <para>You can launch the client by doing <emphasis>ONE</emphasis> of the following:</para>
      <procedure>
        <step>
          <para>For Windows and Mac users, double-click on the desktop shortcut icon (if
            created) or by selecting the shortcut icon from the start menu</para>
        </step>
        <step>
          <para>OR launch using Java WebStart:</para>
          
          <para><ulink url="webstart/exist.jnlp">
            <graphic fileref="resources/webstart.small.jpg"/>
          </ulink></para> 
          
          <para>You can also find the Java WebStart launch icon in the
            <guimenuitem>Administration</guimenuitem> menu in the left sidebar of
            all documentation pages. NOTE: Java WebStart needs to be found by the web
            browser and the eXist jars need to be signed (if you compiled them yourself)!</para>
        </step>
        <step>
          <para>OR enter the following in a Unix shell or DOS/Windows command prompt:</para>
          <synopsis format="linespecific">bin\client.bat (DOS/Windows)</synopsis>
          <synopsis format="linespecific">bin\client.sh (Unix)</synopsis>
        </step>
        <step>
          <para>OR if both of the above approaches fail to launch the client, you can
            enter the following on the command-line:</para>
          <synopsis>java -jar start.jar client</synopsis>
        </step>
      </procedure>
      
      <para>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 completition.</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>-l</option> or <option>--nogui</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>

    <section>
      <title>Using the shell</title>
      <para>We will not describe the interactive shell mode in detail here. 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 completition, 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. 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"><![CDATA[
        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
        ]]></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 and your database files
          get corrupt: just remove the data files created by eXist 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>-o</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>-o</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 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 : <unorderedlist>
            <listitem> a MIME type </listitem>
            <listitem> an eXist type ("xml" or "binary") </listitem>
            <listitem> a file extension </listitem>
          </unorderedlist> This is also used by the eXist servers . For example to specify that
          .xmap extension is used for XML files you can specify it like this in mime-types.xml : <programlisting>  
			  <![CDATA[  
<mime-type name="text/xml" type="xml">
 <description>XML document</description>  
 <extensions>.xml,.xsl,.xsd,.mods,.xmi,.xconf,.xslt,.wsdl,.x3d,.rdf,.owl,.xmap</extensions>  
</mime-type>  
			  ]]>
		  </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[LINE &amp;= 'love']" | bin/client.sh -x</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>Release 0.9.1 contains a simple backup/restore client, 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>
  </chapter>
</book>
