To add a document to a container, you use
XmlContainer.putDocument()
.
When you use this method, you must:
Somehow obtain the document that you want to put into
the container. To do this, you can create an input stream
to the content or load the XML document into a string object.
Alternatively, you can load the document into
an XmlDocument
object
and then provide the
XmlDocument
object to
XmlContainer.putDocument()
.
When you do this, you can provide the document to the
XmlDocument
object using an
input stream or string, or you can construct the
document using an event writer.
Provide a name for the document. This name must be unique or
BDB XML will throw
XmlException.UNIQUE_ERROR
.
If you are using an XmlDocument
object to add the document, use
XmlDocument.setName()
to set the document's name. Otherwise, you can set the name
directly on the call to
XmlContainer.putDocument()
.
Note that if you do not want to explicitly set a name for
the document, you can
set XmlDocumentConfig.setGenerateName()
to true
and then pass that object to
XmlContainer.putDocument()
.
This causes BDB XML to generate a unique name for you. The
name that it generates is a concatenation of a unique
value, an underscore, and the value that you provide for the document's
name, if any. For example:
myDocName_a
where myDocName
is the name that you set
for the document and a
is the unique value generated
by BDB XML.
If you do not set a name for the document, but you do
specify that a unique name is to be generated, then
dbxml
is used as the name's prefix.
dbxml_b
If you do not set a name for the document and if you do not
use
XmlDocumentConfig.setGenerateName(true)
,
then BDB XML throws
XmlException.UNIQUE_ERROR
.
Note that the content that you supply to
XmlContainer.putDocument()
is read and validated. By default, this includes any schema or
DTDs that the document might reference. Since this can cause
you some performance issues, you can cause BDB XML to only
examine the document body itself by
set XmlDocumentConfig.setWellFormedOnly()
o
to true
and then pass that object to
XmlContainer.putDocument()
.
However, using this
option
cause parsing errors if the document references
information that might have come from a schema or DTD.
Further, note that while your documents are stored in the container with their shared text entities (if any) as-is, the underlying XML parser does attempt to expand them for indexing purposes. Therefore, you must make sure that any entities contained in your documents are resolvable at load time.
For example, to add a document that is held in a string:
package dbxml.gettingStarted; import com.sleepycat.dbxml.XmlContainer; import com.sleepycat.dbxml.XmlException; import com.sleepycat.dbxml.XmlManager; ... XmlManager myManager = null; XmlContainer myContainer = null; // The document String docString = "<a_node><b_node>Some text</b_node></a_node>"; // The document's name. String docName = "testDoc1"; try { myManager = new XmlManager(); // Assumes the container currently exists. myContainer = myManager.openContainer("container.bdbxml"); // Do the actual put myContainer.putDocument(docName, // The document's name docString, // The actual document, // in a string. null); // XmlDocumentConfig object } catch (XmlException e) { // Error handling goes here. You may want to check // for XmlException.UNIQUE_ERROR, which is raised // if a document with that name already exists in // the container. If this exception is thrown, // try the put again with a different name. } finally { try { if (myContainer != null) { myContainer.close(); } if (myManager != null) { myManager.close(); } } catch (XmlException ce) { // Exception handling goes here } }
To load the document from an input stream, the code is identical except that
you use the appropriate method on XmlManager
to
obtain the stream. For example, to load an XmlDocument directly from a file
on disk:
package dbxml.gettingStarted; import com.sleepycat.dbxml.XmlContainer; import com.sleepycat.dbxml.XmlException; import com.sleepycat.dbxml.XmlInputStream; import com.sleepycat.dbxml.XmlManager; ... XmlManager myManager = null; XmlContainer myContainer = null; // The document String docString = "/export/testdoc1.xml"; // The document's name. String docName = "testDoc1"; try { myManager = new XmlManager(); // Assumes the container currently exists. myContainer = myManager.openContainer("container.bdbxml"); // Get the input stream. XmlInputStream theStream = myManager.createLocalFileInputStream(fileName); // Do the actual put myContainer.putDocument(docName, // The document's name theStream, // The actual document. null); // XmlDocumentConfig object } catch (XmlException e) { // Error handling goes here. You may want to check // for XmlException.UNIQUE_ERROR, which is raised // if a document with that name already exists in // the container. If this exception is thrown, // try the put again with a different name. } finally { try { if (myContainer != null) { myContainer.close(); } if (myManager != null) { myManager.close(); } } catch (XmlException ce) { // Exception handling goes here } }