You are viewing a plain text version of this content. The canonical link for it is here.
Posted to xindice-dev@xml.apache.org by gi...@apache.org on 2003/01/24 15:19:33 UTC
cvs commit: xml-xindice/src/documentation/content/xdocs/dev guide-administrator.xml
gianugo 2003/01/24 06:19:33
Modified: src/documentation/content/xdocs/dev guide-administrator.xml
Log:
Added information about database start/stop. Corrected backup procedures.
Revision Changes Path
1.3 +250 -202 xml-xindice/src/documentation/content/xdocs/dev/guide-administrator.xml
Index: guide-administrator.xml
===================================================================
RCS file: /home/cvs/xml-xindice/src/documentation/content/xdocs/dev/guide-administrator.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- guide-administrator.xml 26 Nov 2002 09:20:42 -0000 1.2
+++ guide-administrator.xml 24 Jan 2003 14:19:33 -0000 1.3
@@ -1,103 +1,104 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
-<!--
- - Version: $Revision$ $Date$
- - Author: Kimbro Staken (kstaken@xmldatabases.org)
- -->
<document>
- <header>
- <title>Administrator guide</title>
- <authors>
- <person id="ks" name="Kimbro Staken" email=""/>
- </authors>
- <notice/>
- <abstract/>
- </header>
- <body>
- <warning>This documentation is a work in progress and is only applicable to the CVS version of Xindice. There is absolutely no guarantee that this information is accurate. You have been warned.
- </warning>
+ <header>
+ <title>Xindice Administration 1.1 beta</title>
+ <authors>
+ <person id="ks" name="Kimbro Staken" email=""/>
+ <person id="gr" name="Gianugo Rabellino" email="gianugo@apache.org"/>
+ </authors>
+ <notice/>
+ <abstract/>
+ </header>
+ <body>
<section>
<title>Database Administration</title>
<p>
- Database administration of Xindice is accomplished from the command
- line using the
- <code>xindice</code> command. This command
- allows you to view and alter the database configuration on the fly
- on a running system. A complete list of available commands and more
- detail about each command can be found in the
- <link href="guide-commandline.html">Command Line Tools Reference Guide</link>.
+ Database administration of Xindice is accomplished from
+ the command line using the <code>xindice</code> command.
+ This command allows you to view and alter the database
+ configuration on the fly on a running system. A complete
+ list of available commands and more detail about each
+ command can be found in the
+ <link href="guide-tools.html">Command Line Tools Reference Guide</link>.
</p>
- <section>
- <title>Managing Collections</title>
- <p/>
- <section>
- <title>Adding a Collection</title>
- <p>
- Adds a collection named products under the collection /db/data.
- </p>
- <source>xindice add_collection -c /db/data -n products</source>
- </section>
- <section>
- <title>Deleting a Collection</title>
- <p>Deletes the collection named products from the collection /db/data.</p>
- <source>xindice delete_collection -c /db/data/products</source>
- </section>
- <section>
- <title>Listing the Collections</title>
- <p>This will display a list of all child collections under the collection /db/data</p>
- <source>xindice list_collections -c /db/data</source>
- </section>
- </section>
- <section>
- <title>Managing Indexes</title>
- <p>
- The Xindice indexing system allows you to define indexes to speed
- performance on commonly used XPath queries. If no indexes are defined
- you can still execute queries but performance will suffer
- because the
- query engine will need to scan the entire collection to create the
- result node-set.
- </p>
- <p>
- Indexes can be added using the
- <code>xindice</code>
- command.
- </p>
- <section>
- <title>Adding an Index</title>
- <p>
- Using this simple XML file you might want to index the product_id
- element because searches for products by product_id are common.
- </p>
- <source><![CDATA[
+ <section>
+ <title>Managing Collections</title>
+ <p/>
+ <section>
+ <title>Adding a Collection</title>
+ <p>
+ Adds a collection named products under the
+ collection /db/data.
+ </p>
+ <source>xindice add_collection -c /db/data -n products</source>
+ </section>
+ <section>
+ <title>Deleting a Collection</title>
+ <p>
+ Deletes the collection named products from the
+ collection /db/data.
+ </p>
+ <source>xindice delete_collection -c /db/data/products</source>
+ </section>
+ <section>
+ <title>Listing the Collections</title>
+ <p>
+ This will display a list of all child collections
+ under the collection /db/data
+ </p>
+ <source>xindice list_collections -c /db/data</source>
+ </section>
+ </section>
+ <section>
+ <title>Managing Indexes</title>
+ <p>
+ The Xindice indexing system allows you to define indexes
+ to speed performance on commonly used XPath queries. If no
+ indexes are defined you can still execute queries but
+ performance will suffer because the query engine will need
+ to scan the entire collection to create the result node-set.
+ </p>
+ <p>
+ Indexes can be added using the <code>xindice</code>
+ command.
+ </p>
+ <section>
+ <title>Adding an Index</title>
+ <p>
+ Using this simple XML file you might want to index the
+ product_id element because searches for products by
+ product_id are common.
+ </p>
+ <source><![CDATA[
<?xml version="1.0"?>
<product>
-<product_id>120320</product_id>
-<description>Glazed Ham</description>
-</product>]]></source>
- <p>
- This can be accomplished by running the following command.
- This will create an index named idindex on all product_id
- elements in the collection /db/data/catalog.
- </p>
- <source><![CDATA[
+ <product_id>120320</product_id>
+ <description>Glazed Ham</description>
+</product>
+ ]]></source>
+ <p>
+ This can be accomplished by running the following command.
+ This will create an index named idindex on all product_id
+ elements in the collection /db/data/catalog.
+ </p>
+ <source><![CDATA[
xindice add_indexer -c /db/data/catalog -n idindex -p product_id
- ]]></source>
- <p>
- Once this is done the query engine will now use this index to
- help resolve XPath queries that involve restriction on the
- value of the product_id element.
- </p>
- </section>
- <p>
- The -p parameter to the command specifies the pattern to use in the
- index. These patterns are used by the Indexing system to determine
- best-fit and match-based Indexers for queries and index updating.
- The pattern used
- MUST resemble the following scheme.
- </p>
- <source>
- <![CDATA[
+ ]]></source>
+ <p>
+ Once this is done the query engine will now use this index to
+ help resolve XPath queries that involve restriction on the
+ value of the product_id element.
+ </p>
+ </section>
+ <p>
+ The -p parameter to the command specifies the pattern to
+ use in the index. These patterns are used by the Indexing
+ system to determine best-fit and match-based Indexers for
+ queries and index updating. The pattern used MUST resemble
+ the following scheme.
+ </p>
+ <source> <![CDATA[
Pattern Description
=========== ====================================================
elem The value of the named element
@@ -106,124 +107,171 @@
*@attr The value of the named attribute for all elements
elem@* The value of all attributes for the named element
*@* The value of all attributes for all elements
- ]]></source>
- <p>
- Note: In order to index a namespace other than the default
- namespace, you must prepend your pattern components with a
- URI placed in square brackets. Example:
- </p>
- <source><![CDATA[
+ ]]></source>
+ <p>
+ Note: In order to index a namespace other than the default
+ namespace, you must prepend your pattern components with a
+ URI placed in square brackets. Example:
+ </p>
+ <source><![CDATA[
[http://www.world.org/People]person
*@[http://www.world.org/People]id
[http://www.world.org/People]person@[http://www.world.org/People]id
- ]]></source>
+ ]]></source>
+ <p>
+ Do not include a prefix in these patterns, as the indexing
+ system, like most Namespace processing applications, processes
+ namespaced elements and attributes independently of the prefix
+ that is used.
+ </p>
+ <section>
+ <title>Indexing both Elements and Attributes</title>
+ <p>
+ Because the patterns recognize either an element or
+ an attribute, and not both, in order to index all
+ element and attribute values in a collection, you'd
+ have to create two index entries. The * pattern will
+ index all elements and the *@* pattern will index all
+ attributes of all elements.
+ </p>
+ <source><![CDATA[
+xindice add_collection_indexer -c /db/data/catalog -n idindex -p '*'
+xindice add_collection_indexer -c /db/data/catalog -n idindex -p '*@*'
+ ]]></source>
+ </section>
+ <p>
+ Excessive use of wildcard indexes can adversely affect the
+ performance of the indexing system. Best practice would be
+ to use specific element or attribute indexes whenever
+ possible, and only define wildcard indexes when it is
+ absolutely necessary.
+ </p>
+ </section>
+ </section>
+ <section>
+ <title>Server Administration</title>
+ <section>
+ <title>Installing the Server</title>
+ <p>
+ Starting from 1.1, Xindice is not a standalone server
+ anymore. The server functions are now based on your
+ favourite Servlet 2.2 compliant Application Server.
+ Xindice has been tested and proven to work under both
+ Tomcat and Jetty, but there is no particular reason to
+ expect malfunctions under other application servers.
+ </p>
+ <p>
+ Installation is then straightforward: just deploy the Xindice
+ WAR file (<code>xindice-1.1b.war</code>) into your
+ favourite application server and you're ready to go. There
+ are only two minor points to be aware of:
+ </p>
+ <ul>
+ <li>The Xindice XML-RPC endpoint is configured in the client
+ as <code>http://anyserver:anyport/Xindice/</code>. This
+ means that it's strongly advisable to deploy the Xindice
+ WAR file under a <code>Xindice</code> context. This can be
+ easily accomplished under Tomcat by simply renaming the WAR
+ file to <code>Xindice.war</code> or (in Tomcat 4.1.x) by
+ copying the file <code>dist/xindice-1.1b.xml</code> under
+ the <code>$TOMCAT_HOME/webapps</code> directory. Note that
+ under some Tomcat versions you will need to start twice the
+ server the first time so that Tomcat can configure itself
+ properly.
+ </li>
+ <li>
+ You probably want to edit the Xindice configuration file
+ that resides under <code>/WEB-INF/system.xml</code>. This
+ file configures, among others, the physical location of the
+ database. By default, your data will be under
+ <code>[your_unpacked_war_location]/WEB-INF/db</code>, which
+ might not be a good idea for many users: leaving the
+ database as is will mean data loss if an upgrade takes place
+ inadvertently, since the directory will be overwritten.
+ Also, if your application server is not unpacking WARs,
+ Xindice won't be able to start.
+ </li>
+ </ul>
+
<p>
- Do not include a prefix in these patterns, as the indexing
- system, like most Namespace processing applications, processes
- namespaced elements and attributes independently of the prefix
- that is used.
+ Having the server packaged as a webapp means also that
+ starting and stopping Xindice is "just" a matter of
+ starting/stopping the application server.
</p>
+
<section>
- <title>Indexing both Elements and Attributes</title>
- <p>
- Because the patterns recognize either an element or an attribute,
- and not both, in order to index all element and attribute values
- in a collection, you'd have to create two index entries. The *
- pattern will index all elements and the *@* pattern will index
- all attributes of all elements.
- </p>
- <source><![CDATA[
-xindice add_collection_indexer -c /db/data/catalog -n idindex -p '*'
-xindice add_collection_indexer -c /db/data/catalog -n idindex -p '*@*'
- ]]></source>
- </section>
- <p>
- Excessive use of wildcard indexes can adversely affect the
- performance of the indexing system. Best practice would be to use
- specific element or attribute indexes whenever possible, and only
- define wildcard indexes when it is absolutely necessary.
- </p>
- </section>
-</section>
-<section>
- <title>Server Administration</title>
- <section>
- <title>Backing up Your Data</title>
- <p>
- Currently backing up Xindice consists of simply shutting down the
- server and copying the
- entire contents of the Xindice/db directory to the backup
- media.
- </p>
- <section>
- <title>Backing up the server</title>
- <p>
- This example assumes that the Xindice/bin directory
- is in your path.
- </p>
- <source><![CDATA[
-cd Xindice
-xindice shutdown
-cp -pr db /backup/db
-./start
- ]]></source>
- </section>
- <section>
- <title>Restoring the Data</title>
- <p>
- Restoring the data is simply removing the current database and
- reversing the backup process.
- This example assumes that the Xindice/bin directory
- is in your path.
- </p>
- <source><![CDATA[
-cd Xindice
-xindice shutdown
-rm -rf db
-cp -pr /backup/db db
-./start
- ]]></source>
- </section>
- </section>
- <section>
- <title>Exporting the Contents of the Database</title>
- <p>
- Xindice includes tools to export data to a directory hierarchy and to also import
- data from a directory hierarchy. Each directory in the hierachy corresponds to a
- collection in Xindice. Each XML document is stored in a separate file named with
- the key from the database.
- </p>
- <section>
- <title>Exporting the database</title>
- <p>
- This example assumes that the Xindice/bin directory
- is in your path.
- </p>
- <source><![CDATA[
-xindice export -c /db/root -f /path/to/data
+ <title>Backing up the server</title>
+
+ <p>
+ Just shutdown the application server and copy the db
+ directory structure somewhere else, e.g. using Tomcat and
+ the server version of Xindice with the default configuration:
+ </p>
+ <source><![CDATA[
+ catalina.sh stop
+ cd $TOMCAT_HOME/webapps/Xindice/WEB-INF
+ cp -pr db /backup/db
+ catalina.sh start
]]></source>
- <p>
- The entire contents of the collection /db/root will be exported to the
- directory /path/to/data.
- </p>
- </section>
- <section>
- <title>Importing the database</title>
- <p>
- This example assumes that the Xindice/bin directory
- is in your path.
- </p>
- <source><![CDATA[
-xindice import -c /db -f /path/to/data/root
+ </section>
+ <section>
+ <title>Restoring the Data</title>
+ <p>
+ Restoring the data is simply removing the current database and
+ reversing the backup process.
+ Again, using Tomcat, this will be something like:
+ </p>
+ <source><![CDATA[
+ catalina.sh stop
+ cd $TOMCAT_HOME/webapps/Xindice/WEB-INF
+ rm -rf db
+ cp -pr /backup/db db
+ catalina.sh start
]]></source>
- <p>
- Each directory under /path/to/data will be used to create a collection and
- all XML documents in the hierarchy will be imported in to the database. You
- can also restrict the documents that are imported by adding -i and the
- extension of the files you want to import.
- </p>
- </section>
- </section>
-</section>
-</body>
+ </section>
+ </section>
+ <section>
+ <title>Exporting the Contents of the Database</title>
+ <p>
+ Xindice includes tools to export data to a directory
+ hierarchy and to also import data from a directory hierarchy.
+ Each directory in the hierachy corresponds to a collection
+ in Xindice. Each XML document is stored in a separate file
+ named with the key from the database.
+ </p>
+ <section>
+ <title>Exporting the database</title>
+ <p>
+ This example assumes that the Xindice/bin directory
+ is in your path.
+ </p>
+ <source><![CDATA[
+ xindice export -c /db/root -f /path/to/data
+ ]]></source>
+ <p>
+ The entire contents of the collection /db/root will
+ be exported to the
+ directory /path/to/data.
+ </p>
+ </section>
+ <section>
+ <title>Importing the database</title>
+ <p>
+ This example assumes that the Xindice/bin directory
+ is in your path.
+ </p>
+ <source><![CDATA[
+ xindice import -c /db -f /path/to/data/root
+ ]]></source>
+ <p>
+ Each directory under /path/to/data will be used to
+ create a collection and all XML documents in the
+ hierarchy will be imported in to the database. You
+ can also restrict the documents that are imported by
+ adding -i and the extension of the files you want to import.
+ </p>
+ </section>
+ </section>
+ </section>
+ </body>
</document>