Copyright (c) 1999-2001 The dbXML Group, L.L.C.
All rights reserved.

See docs/LICENSE for The dbXML License


Frequently Asked Questions
==========================

1. What is dbXML?
2. What is dbXML not?
3. Why not use a relational database?
4. Why not use an object database?
5. Why not use a full-text indexing engine?
6. What query languages do you support?
7. Is your XPath implementation fully compliant?
8. Which JDK should I use?
9. The XML:DB API is missing something, what should I do?
10. My 5 megabyte file is crashing the command line, help?
11. Here's my stack trace, what's it mean?
   11a. CORBA ORB failure
   11b. XML parser conflict
   11c. Wrong Java VM Version
   
---
1. What is dbXML?

dbXML is an open source Native XML Database.  It stores and indexes
compressed XML documents in order to provide that data to a client
application with very little server-side processing overhead.  It
also provides functionality that is unique to XML data, which can't
easily be reproduced by relational databases.

---
2. What is dbXML not?

dbXML is not a persistent DOM implementation.  It was not designed
to store and manage single monster sized documents, where one
document is treated as a set of mini documents.  It was
specifically designed for managing many small to medium sized
documents.

---
3. Why not use a relational database?

XML documents are organized as tree structures.  Relational
databases organize data in a tabular, or grid-like fashion, and
use relational linking in order to expose hierarchical constraints
on the data.  Unfortunately, while it's generally very easy to map
relational data into XML, trying to map XML, which can be very
complex and freeform, into relational data can be incredibly
difficult and lossy.

---
4. Why not use an object database?

Object database are tightly coupled with the applications that
they serve, and are not generally considered to be client/server
databases.  Typically, the objects that they manage can only be
deserialized and used by the programming language that created
them.  While object graphs like DOM trees can be persisted in
object databases, the number of objects that are produced for a
a large collection of XML documents can become a serious
performance and resource bottleneck.

---
5. Why not use a full-text indexing engine?

Full text indexing engines are very fast and appropriate for
performing broad queries across a set of documents.  The
drawbacks to using them for XML applications is that creating
an inverted index causes you to lose document context, requiring
very intensive post-processing to isolate the document nodes
that are being managed.  dbXML provides efficient indexing of
element and attribute values in addition to the ability to
return and manage aggregated document fragments.

---
6. What query languages do you support?

dbXML Core supports XPath and XUpdate.  XPath is the W3C's XML
Pathing language, and is a very powerful way of selecting sets of
nodes from documents in a collection.  XUpdate is the XML:DB
Initiative's updating language, and is very flexible in its ability
to update sets of documents that meet specific XPath criteria.

---
7. Is your XPath implementation fully compliant?

Our XPath implementation is the Apache Software Foundation's Xalan
library.  dbXML provides indexing mechanisms and query
optimization facilities to augment the performance of collection
level XPath queries, but Xalan ultimately has the final say in
any query.

---
8. Which JDK should I use?

We recommend Sun's SDK for Java 1.3.  dbXML will not work with
the 1.2 SDK, and we have not tested it yet with the 1.4 SDK.
There are known issues with Sun's SDK for Java 1.3.1 on several
Linux distributions, but 1.3.0 should work without any problems.

---
9. The XML:DB API is missing something, what should I do?

The XML:DB API is being designed be the XML:DB Initiative, and
so its interfaces and classes are predetermined by that group.
If you have any questions or would like to help further define
the standard API for XML databases, please visit
http://www.xmldb.org

---
10. My 5 megabyte file is crashing the command line, help?

See FAQ #2.  dbXML wasn't designed for monster documents,
rather, it was designed for collections of small to medium
sized documents.  The best thing to do in this case would be to
look at your 5 megabyte file, and determine whether or not it's
a good candidate for being sliced into a set of small documents.
If so, you'll want to extract the separate documents and add
them to a dbXML collection individually.  A good example of
this, would be a massive document of this form:

   <cars>
      <car>
         <make>Boyoda</make>
         <model>Cordova</model>
         <year>1989</year>
      </car>
      <car>
         <make>Frod</make>
         <model>Tortorus</model>
         <year>1990</year>
      </car>
      ...
   </cars>
   
In this case, it makes more sense to split the file into
several <car> documents instead of a single <cars> document.

---
11. Here's my stack trace, what's it mean?

The following are a set of commonly encountered stack traces
that can be generated by dbXML at various times.  Fortunately,
they usually happen at startup.

11a. CORBA ORB failure

   org.omg.CORBA.INITIALIZE: can't instantiate default ORB imp
   jacorb.orb.ORB  minor code: 0  completed: No
     at java.lang.Throwable.<init>(Throwable.java:96)
     at java.lang.Exception.<init>(Exception.java:44)
     at java.lang.RuntimeException.<init>(RuntimeException.jav
     at org.omg.CORBA.SystemException.<init>(SystemException.j
     ...
     
This is a fairly common error that one will encounter when using
dbXML.  It has to do with the CORBA ORB that dbXML uses by default
(JacORB) not being found on startup, which leads the Java VM to
fall back to the standard Sun ORB.  The Sun ORB is not fully
compliant, and won't work with dbXML.  Making sure that the
JacORB Jar is on your CLASSPATH is usually all you need to do to
resolve this.  Also, you'll want to copy orb.properties to your
$JAVA_HOME/jre/lib/ directory.

11b. XML parser conflict

   org/w3c/dom/DOMException
     at org.dbxml.xml.dom.NodeImpl.<clinit>(NodeImpl.java:86)
     at java.lang.Class.forName0(Native Method)
     at java.lang.Class.forName(Class.java:120)
     at org.apache.xerces.parsers.DOMParser.setDocumentClassNa
     ...

This is also a common error one will encounter, and usually is
related to having more than one version of the Xerces XML Parser
on your CLASSPATH.  Before running dbXML or any client programs,
be sure that the Xerces Jar file that is included in the dbXML
distribution is the first Xerces Jar file on your CLASSPATH.

11c. Wrong Java VM Version

   Exception in thread "main" java.lang.ExceptionInInitializerError:
   org.omg.CORBA.BAD_PARAM:   minor code: 1 completed: Maybe
        at java.lang.Throwable.fillInStackTrace(Native Method)
        at java.lang.Throwable.fillInStackTrace(Compiled Code)
        ...
        
This error will occur if you try to use a JDK 1.2 VM to run dbXML. Make sure
that if you have more then one VM installed that the 1.3 VM occurs first in your
path and that your JAVA_HOME environment variable points to the right VM 
installation.
