
                DBXML Getting Started Examples
                            Readme

This directory contains examples and sample data designed to illustrate DBXML's
basic capabilities. To run the examples you must first compile the examples and
then load the sample data using exampleLoadContainer.java to load all the sample
data contained in the xmlData directory.

To compile the examples:

  - Make sure that the following libraries or dlls are included in your
    library search path:
	    - Berkeley DB XML library
		- Berkley DB C++ library
		- Xerces C Library
		- Pathan library
   - Make sure your java CLASSPATH includes the following jars:
        - db.jar (Berkeley DB jar file)
        - dbxml.jar (Berkeley DB XML jar file)

   - Compile each java file contained here with javac, using something 
     like the following:
       javac -d classes myXmlContainer.java

For best results, compile myDbEnv.java, myDb.java, myXmlContainer.java, 
and mdConst.java before compiling any other examples.

To run exampleLoadContainer, you must provide the directory where you want your
database environment to be placed and the location of the xmlData directory.
The xmlData directory is located immediately beneath the 'examples' directory
in your dbxml distribution, and it contains sample XML documents used by these
examples for their operations.

For example:

     cd <examples directory>
     mkdir dbEnvironment
	 java com.sleepycat.dbxml.examples.gettingStarted.exampleLoadContainer -h dbEnvironment ../../xmlData

Once loaded, most of the examples found here can be run by simply identifying
the directory where you placed your database environment. For example:

    java com.sleepycat.dbxml.examples.gettingStarted.simpleQuery -h dbEnvironment


EXAMPLES DESCRIPTION

- simpleContainer.java

  Creates a container, closes it, and then quits. No database environment is
  used. You should edit this file and identify a real path to where you want
  your container placed before running this example.

- simpleContainerInEnv.java
  Creates a database environment, opens it, and then creates and opens three
  containers in that environment. Finally, the containers and environments are
  closed. You should edit this file and provide a path to an existing
  directory where you want the database environment placed before running this
  example.

- myDbEnv.java
  Class that creates/opens a database environment. All of the following
  examples rely on this class.

- myXmlContainer.java
  Class that creates/opens a container. The container can opened with or without
  a database environment. All of the following examples rely on this class.

- simpleAdd.java
  Creates a database environment and container, and then adds two very simple
  XML documents to the container. You identify the location where you want the
  database environment placed using the -h option. This example requires no
  other command line options.

- mdConst.java
  Simple utility class use to encapsulate some constants used by some
  of the following examples.

- exampleLoadContainer.java
  Creates/opens the specified database environment, creates/opens the
  specified container in that environment, and then loads every XML document
  identified on the command line call into the identified container. As each
  document is loaded, a document name is set. Metadata is also set on each
  document that represents the day and time that the document was loaded into
  the container.

  All of the following examples assume that exampleLoadContainer has been run.

- simpleQuery.java
  Executes several XPath queries and prints query results to the console.
  Use the -h option to identify the database environment location that you
  used when you ran loadExamplesData.

       simpleQuery -h <dbenv>

  Note that all of the following examples use the same command line option.

- queryWithContext.java
  Identical to simpleQuery, except that contexts are used to define
  namespaces and variables. 

- queryForDocumentValue.java
  Identical to queryWithContext, except that specific document data is
  retrieved from each document found in the query's result set.

- queryWithDocumentNames.java
  Identical to queryWithContext, except that the query is performed using the
  document name that was set when exampleLoadContainer placed the document
  into the container.

- queryForMetaData.java
  Identical to queryWithContext, except that the timestamp that was stored as
  metadata is retrieved and displayed. This timestamp was set on the document
  when exampleLoadContainer placed the document into the container.

- updateDocument.java
  Identical to queryWithContext, except that the document retrieved as the
  result of the query is updated in a trivial way and then stored back into
  the container.

- modifyDocument.java
  Similar to updateDocument, except that the document(s) retrieved as the
  result of the query are updated via XmlContainer.modifyDocument(), and
  optionally committed back to the container.

- deleteDocument.java
  Identical to queryWithContext, except that every document retrieved as the
  result of the query is deleted from the container.

- addIndex.java
  Adds indexes to a specific document node.

- replaceIndex.java
  Replaces the indexes on a specific document node with new indexes. Iterates
  through the indexes maintained for the container and shows what is being
  used. For best results, run addIndex before running this example.
  
- deleteIndex.java
  Deletes indexes from a specific document. Iterates through the indexes
  maintained for the container and shows what is being used. For best results,
  run addIndex before running this example.
  
- myDb.java
  Class that creates/opens a Berkeley db. The following two examples rely 
  on this class.

- buildDB.java 
  Illustrates how a DBXML container can be used with a Berkeley DB database. A
  Berkeley DB database is created in the same environment as the container and
  data corresponding to documents in the container is loaded into the
  database. The DBXML query and database put are all wrapped in a common
  transaction.

- retrieveDB.java
  Illustrates how a DBXML container can be used with a Berkeley DB database.
  Documents are retrieved from the container and then data corresponding to
  each document is retrieved from the Berkeley DB database. Again, all queries
  are wrapped in a common transaction. For best results, run buildDB before
  running this example.
  


