# dbXML Command Line Tools Reference version 1.0

Kalafus
Jay
The dbXML Project
2001
The dbXML Group L.L.C.
$Id: ToolsReference.xml,v 1.21 2001/08/15 09:49:52 kstaken Exp $

This documentation is a work in progress. Links to the most current version can be found at http://www.dbxml.org/docs/

## Collection Management Commands

### Adding a Collection

Adds a new collection to the database. When adding a collection under an existing collection hierarchy all parent collections must already exist in the database.

Summary:

                dbxmladmin add_collection
                -c context
                -n name
                -v
                -u host uri

Action: | `add_collection`
Abberviated-Action: | `ac`
Access Level: | Admin

Parameters:

- `-c` The collection context under which to create the new collection.
- `-n` The name of the collection to create
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Creating a Top Level Collection

                   dbxmladmin add_collection -c /db -n pebbles

#### Creating a Sub Collection Under an Existing Collection

                   dbxmladmin add_collection -c /db/pebbles -n boulder

### Deleting a Collection

Deletes a collection or subcollection from the database. If deleting a collection that has subcollections and documents they will also be deleted.

Summary:

                dbxmladmin delete_collection
                -c context
                -n name
                -y
                -v
                -u host uri

Action: | `delete_collection`
Abberviated-Action: | `dc`
Access Level: | Admin

Parameters:

- `-c` The collection context under which to delete the collection.
- `-n` The name of the collection to delete.
- `-y` Do not ask for confirmation of delete
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Deleting a Top Level Collection

                   dbxmladmin delete_collection -c /db -n pebbles

#### Deleting a Sub Collection

                   dbxmladmin delete_collection -c /db/pebbles -n boulder

### List Collections

List all collections under the collection context given. If no collection is given then the root collection will be asumed.

Summary:

                dbxml list_collections
                -c context
                -v
                -u host uri

Action: | `list_collections`
Abberviated-Action: | `lc`
Access Level: | User

Parameters:

- `-c` The collection context under which all sub collections are listed
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Listing the Top Level Collections

                   dbxml list_collections -c /db

#### Listing a Sub Collection

                   dbxml list_collections -c /db/pebbles

## Document Management Commands

### Adding a Document

Adds a document to a collection or nested collection. Adding a document requires two parameters - the collection it will be stored under, and the file path to the document. If a document key is not provided an auto-generated system key will be used for the document. Documents cannot be added to collections that do not already exist. When entering the file path be sure to include the path and file extension.

Summary:

                dbxml add_document
                -c context
                -f file path
                -n key to assign to document
                -v
                -u host uri

Action: | `add_document`
Abberviated-Action: | `ad`
Access Level: | User

Parameters:

- `-c` The collection context under which to add the document
- `-f` The complete file path to the document being added
- `-n` The key to assign to the document
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Adding a document to a collection with a key of "stones"

                   dbxml add_document -c /db/pebbles -f /tmp/stones.xml -n stones

#### Adding a document to the root collection with an automatically generated key

                   dbxml add_document -c /db -f /tmp/bookmarks.xml

### Adding Multiple Documents

Adds multiple documents to a collection or a nested collection. This command requires two arguments: the collection to store the documents under and the directory path containing the documents. Documents can be added to collections as well as subcollections as long as they exist. Documents added will be assigned their file name as the document key. The optional "extension" parameter can be used to import documents with a certain file extension. Document keys are shown as they are created.

Summary:

                dbxml add_multiple_documents
                -c context
                -f Directory to use
                -e file extenstion
                -v
                -u host uri

Action: | `add_multiple_documents`
Abberviated-Action: | `addmultiple`
Access Level: | User

Parameters:

- `-c` The collection context under which to add the documents
- `-f` The path to the directory to import documents from
- `-e` The file extension to use when importing documents
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Adding all files from a directory to a collection

                   dbxml add_multiple_documents -c /db/pebbles -f /tmp/mydocs

#### Adding all files from a directory with an extension of ".xml"

                   dbxml add_multiple_documents -c /db/pebbles -f /tmp/mydocs -e xml

### Deleting a Document

Deletes an existing document from a collection or nested collection within the database.

Summary:

                dbxml delete_document
                -c context
                -n document key
                -v
                -u host uri

Action: | `delete_document`
Abberviated-Action: | `dd`
Access Level: | User

Parameters:

- `-c` The collection context under which to delete the document
- `-n` The key of the document to be deleted
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Deleting a Document from a collection

                   dbxml delete_document -c /db/pebbles -n stones

### Retrieving a Document

Retrieves an existing document from a collection or nested collection within the database. The complete path where the document will be stored is required. If the file path passed in does not exist, it will be created . If the file argument given already exists, it will be overwritten automatically.

Summary:

                dbxml retrieve_document
                -c context
                -n document key
                -f file path and name
                -v
                -u host uri

Action: | `retrieve_document`
Abberviated-Action: | `rd`
Access Level: | User

Parameters:

- `-c` The collection context under which to retrieve the document
- `-n` The key of the document to be retrieved
- `-f` The file path to store the document under
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Retrieving a document from a collection

                   dbxml retrieve_document -c /db/pebbles -n stones -f /tmp/stones.xml

### Importing a Directory Tree

Adds multiple documents into a collection or a nested collection within the database, copying the directory structure into the database as collections. This command is designed to take a directory and create a collection from it's name. Directories under the directory will also be created as collections, duplicating the directory tree. The files within the specified directory are converted into Documents and then stored into the newly created collection with their filenames as the document keys. The optional "extension" parameter can be used to only import documents with a certain file extension. If the collection name used already exists it will be overwritten. Collection and document keys will are shown as they are created.

Summary:

                dbxmladmin import
                -c context
                -f file path and name
                -e file extenstion
                -v
                -u host uri

Action: | `import`
Abberviated-Action: | `import`
Access Level: | Admin

Parameters:

- `-c` The collection context under which to import the documents
- `-f` The path to the documents being added
- `-e` The file extension to use when importing documents
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Importing all directories and documents

                   dbxmladmin import -c /db/pebbles -f /tmp/flintstones

#### Importing all directories and documents with an extension of ".xml"

                   dbxmladmin import -c /db/pebbles -f /tmp/flintstones -e xml

### Exporting a Directory Tree

Creates an identical directory tree from a collection including any subcollections. The directory tree will be created starting at the directory passed in as an argument. This command requires the collection which you are eporting and the directory to export to as arguments.

Summary:

                dbxml export
                -c context
                -f directory path
                -v
                -u host uri

Action: | `export`
Abberviated-Action: | `export`
Access Level: | User

Parameters:

- `-c` The collection context under which to export the document tree
- `-f` The directory to create the collection structure under
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Creating a directory tree indentical to a collection

                   dbxml export -c /db/pebbles -f /tmp/pebbles

## XMLObject Management Actions

### Adding a XMLObject

Adds a new XmlObject or nested XmlObject to the database. Adding an XmlObject requires an implementing class and a name. In order to add the XmlObject the collection that it is being added to must already exist. to sucessfully complete this topertation, the implementing class must be in the server's classpath.

Summary:

                dbxmladmin add_xmlobject
                -c context
                -i implementing class
                -n object name
                -v
                -u host uri

Action: | `add_xmlobject`
Abberviated-Action: | `ao`
Access Level: | Admin

Parameters:

- `-c` The collection context under which to add the XmlObject
- `-i` The fully qualified class name for the implementing class
- `-n` The name to assign to the XmlObject
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Create a XmlObject in the pebbles collection

                   dbxmladmin add_xmlobject -c /db/pebbles -i example.XmlRockObject -n rockXmlObject

#### Create a XmlObject in a sub collection

                   dbxmladmin add_xmlobject -c /db/pebbles/boulder -i example.XmlRockObject -n rockXmlObject

### Deleting a XmlObject

Deletes an XmlObject or nested XmlObject from the database. Deleting an XmlObject requires the collection name and the XmlObject name.

Summary:

                dbxmladmin delete_xmlobject
                -c context
                -n name
                -v
                -u host uri

Action: | `delete_xmlobject`
Abberviated-Action: | `do`
Access Level: | Admin

Parameters:

- `-c` The collection context under which to delete the XmlObject
- `-n` The name of the XmlObject to delete
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Delete an XmlObject in the pebbles collection

                   dbxmladmin delete_xmlobject -c /db/pebbles -n rockXmlObject

#### Delete an XmlObject from the boulder sub collection

                   dbxmladmin delete_xmlobject -c /db/pebbles/boulder -n rockXmlObject

### Listing XmlObjects

Lists all XmlObjects or nested XmlObjects in the database. The listing of XmlObjects works in a similar fashion to listing collections.

Summary:

                dbxml lists_xmlobjects
                -c context
                -v
                -u host uri

Action: | `list_xmlobjects`
Abberviated-Action: | `lo`
Access Level: | User

Parameters:

- `-c` The collection context under which to list the XmlObjects
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### List all XmlObjects in the pebbles collection

                   dbxml list_xmlobjects -c /db/pebbles

#### List all XmlObjects in the boulder sub collection

                   dbxml list_xmlobjects -c /db/pebbles/boulder

### Invoke an XmlObject

Allows the invocation of an XmlObject in the database. This command requires two arguments - the collection to invoke the object under and the URI for the XmlObject. The URI given can be either relative or the absolute path. (See the users guide for more information on URI's)

Summary:

                dbxml invoke
                -c context
                -o object URI
                -v
                -u host uri

Action: | `invoke`
Abberviated-Action: | `invoke`
Access Level: | User

Parameters:

- `-c` The collection context under which to invoke the XmlObject
- `-o` The XmlObject that is being invoked
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Invoke the rockXmlObject in the pebbles collection

                   dbxml invoke -c /db/pebbles -o rockXmlObject

#### Invoke a rockXmlObject with a method named crush that takes a name parameter named rock

                   dbxml invoke -c /db/pebbles -o rockXmlObject/crush?rock=boulder

## Collection Indexer Actions

### Adding a Collection Indexer

Adds a new collection index or nested collection index to the database. In order to add the collection index, the collection it is being added to must already exist. This command allows you to supply optional parameters for setting the index page size, setting the maximum key size for the index, and the index data type.

Summary:

                dbxmladmin add_indexer
                -c context
                -n index name
                -p index pattern
                --pagesize pagesize
                --maxkeysize max key size
                -t  index type
                -v
                -u host uri

Action: | `add_indexer`
Abberviated-Action: | `ai`
Access Level: | Admin

Parameters:

- `-c` The collection context under which to add the indexer
- `-n` The name of the index being added
- `-p` The pattern used to create the index
- `--maxkeysize` The MaxKeySize for the index ( default: 0 = none )
- `--pagesize` The PageSize for the index ( default: 4096)
- `-t` The data type for the index to create. Possible values are:

            string   Non-normalized string value
            trimmed  Normalized (whitespace stripped) string value
            short    16-bit signed short integer
            int      32-bit signed integer
            long     64-bit signed integer
            float    32-bit floating point value
            double   64-bit floating point value (XPath number)
            byte     8-bit signed byte
            char     16-bit signed character
            boolean  8-bit boolean value
            name     Store document keys that contain the pattern

- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### To create a collection index in the pebbles collection for docuemnts with a "rock" element

                   dbxmladmin add_indexer -c /db/pebbles -n rockindex -p rock

#### To create a collection index in the boulder sub collection for documents containing a rock elements with an attribute of "hard"

                   dbxmladmin add_indexer -c /db/pebbles/boulder -n hardindex -p rock@type

### Deleting a Collection Indexer

Deletes a collection index or a nested collection index from the database. Deleting an index requires the collection and index name. If a collection index is deleted, the collection will still remain.

Summary:

                dbxmladmin delete_indexer
                -c context
                -n index name
                -v
                -u host uri

Action: | `delete_indexer`
Abberviated-Action: | `di`
Access Level: | Admin

Parameters:

- `-c` The collection context under which to delete the index
- `-n` The name of the indexer being deleted
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Delete a collecion index in the pebbles collection

                   dbxmladmin delete_indexer -c /db/pebbles -n hardindex

### Listing Collection Indexers

Lists all collection indexers or nested collection indexes in the database. The listing of indexes works in a similar fashion to listing collections

Summary:

                dbxmladmin list_indexers
                -c context
                -v
                -u host uri

Action: | `list_indexers`
Abberviated-Action: | `li`
Access Level: | Admin

Parameters:

- `-c` The collection context under which to list the indexers
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### To list all collection indexes from the pebbles collection

                   dbxmladmin list_indexers -c /db/pebbles

## Xpath Query Actions

### Executing an Xpath Query against a Collection

Execute an Xpath query against a collection or nested collection. The command requires two arguments : the collection to query against and the query string to use.

Summary:

                dbxml xpath
                -c context
                -q query
                -v
                -u host uri

Action: | `xpath`
Abberviated-Action: | `xpath`
Access Level: | User

Parameters:

- `-c` The collection context under which to execute the query
- `-q` The query to execute against the collection
- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Run an Xpath query against all documents in the pebbles collection with "rock" node that has the type attribute = "hard"

                   dbxml xpath -c /db/pebbles -q /rock[@type="hard"]

## Miscellaneous Actions

### Shutting down the server

Shutdown the dbXML server

Summary:

                dbxmladmin shutdown
                -v
                -u host uri

Action: | `shutdown`
Abberviated-Action: | `shutdown`
Access Level: | Admin

Parameters:

- `-v` Show verbose output
- `-u` The URI for the dbXML host to use. http://host:[port]

Examples:

#### Shutdown the server

                   dbxmladmin shutdown

### Accessing online Help

Show the online help

Summary:

                dbxml help
                -v

Action: | `help`
Abberviated-Action: | `help`
Access Level: | User

Parameters:

- `-v` Show verbose output

Examples:

#### Show online Help

                   dbxml help