Library Version 12.1.6.0

XmlContainer::putDocument
Prev  Chapter 5.  XmlContainer  Next

XmlContainer::putDocument

#include <DbXml.hpp>

void XmlContainer::putDocument(XmlDocument &document,
    XmlUpdateContext &context, u_int32_t flags = 0)

void XmlContainer::putDocument(XmlTransaction &txn, 
    XmlDocument &document, XmlUpdateContext &context, 
    u_int32_t flags = 0)

std::string XmlContainer::putDocument(const std::string &name,
    XmlEventReader &reader, XmlUpdateContext &context, 
    u_int32_t flags = 0)

std::string XmlContainer::putDocument(XmlTransaction &txn, 
    const std::string &name, XmlEventReader &reader,
    XmlUpdateContext &context, u_int32_t flags = 0)

std::string XmlContainer::putDocument(const std::string &name,
    XmlInputStream *adopted_input,
    XmlUpdateContext &context, u_int32_t flags = 0)

std::string XmlContainer::putDocument(XmlTransaction &txn, 
    const std::string &name, XmlInputStream *adopted_input,
    XmlUpdateContext &context, u_int32_t flags = 0)

std::string XmlContainer::putDocument(const std::string &name,
    const std::string &contents, XmlUpdateContext &context, 
    u_int32_t flags = 0)

std::string XmlContainer::putDocument(XmlTransaction &txn, 
    const std::string &name, const std::string &contents,
    XmlUpdateContext &context, u_int32_t flags = 0)

Inserts an XmlDocument into the container. The value returned by this method is dependent upon the form of the method that you used to perform the insertion.

Note that the name used for the document must be unique in the container or an exception is thrown. The flag, DBXML_GEN_NAME, can be used to generate a name. To change a document that already exists in the container, use XmlContainer::updateDocument.

The document content is indexed according to the container indexing specification. The indexer supports the Xerces content encodings and expects the content to be well-formed , but it need not be valid .

There are four different forms of this method:

Each of these forms are described in the following sections.

Add a document as an XmlDocument object

#include <DbXml.hpp>

void XmlContainer::putDocument(XmlDocument &document,
    XmlUpdateContext &context, u_int32_t flags = 0)

void XmlContainer::putDocument(XmlTransaction &txn, 
    XmlDocument &document, XmlUpdateContext &context, 
    u_int32_t flags = 0)

Inserts the XmlDocument provided on the call to the container. The name provided for the XmlDocument must be unique to the container or an exception is thrown. To set the name, use XmlDocument::setName.

Parameters are:

txn

If the operation is to be transaction-protected, this parameter is an XmlTransaction handle returned from XmlManager::createTransaction.

document

The XmlDocument to be inserted into the XmlContainer

context

The update context to use for the document insertion.

flags

This parameter must be set to 0 or the following values:

  • DBXML_GEN_NAME

    Generate a unique name. If no name is set for this XmlDocument , a system-defined unique name is generated. If a name is specified, a unique string is appended to that name to ensure uniqueness.

  • DBXML_WELL_FORMED_ONLY

    Force the use of a scanner that will neither validate nor read schema or dtds associated with the document during parsing. This is efficient, but can cause parsing errors if the document references information that might have come from a schema or dtd, such as entity references.

Add a document using an XmlEventReader

#include <DbXml.hpp>

std::string XmlContainer::putDocument(const std::string &name,
    XmlEventReader &reader, XmlUpdateContext &context, 
    u_int32_t flags = 0)

std::string XmlContainer::putDocument(XmlTransaction &txn, 
    const std::string &name, XmlEventReader &reader,
    XmlUpdateContext &context, u_int32_t flags = 0)

Inserts the XML document referenced by the XmlEventReader into the container. The name used for the new document is returned by this method.

Parameters are:

txn

If the operation is to be transaction-protected, this parameter is an XmlTransaction handle returned from XmlManager::createTransaction.

name

Provides the name of the document to insert into the container. This name must be unique in the container. If DBXML_GEN_NAME is set, a system-defined string is appended to create a unique name. This applies if the name parameter is provided or empty. If the name is not unique within the container, an exception is thrown.

reader

Identifies the source of information used to create the document. The content will be created by calling methods on this object. When the end of the document is read, the XmlEventReader::close method will be called. The XmlEventReader object must have been created via one of these methods: XmlDocument::getContentAsEventReader, XmlValue::asEventReader, or an application-created derived class of XmlEventReader .

context

The update context to use for the document insertion.

flags

This parameter must be set to 0 or the following values:

  • DBXML_GEN_NAME

    Generate a unique name. If no name is set for this XmlDocument , a system-defined unique name is generated. If a name is specified, a unique string is appended to that name to ensure uniqueness.

Add a document using an XmlInputStream

#include <DbXml.hpp>

std::string XmlContainer::putDocument(const std::string &name,
    XmlInputStream *adopted_input,
    XmlUpdateContext &context, u_int32_t flags = 0)

std::string XmlContainer::putDocument(XmlTransaction &txn, 
    const std::string &name, XmlInputStream *adopted_input,
    XmlUpdateContext &context, u_int32_t flags = 0)

Inserts the XML document contained in the XmlInputStream into the container. The name used for the new document is returned by this method.

Parameters are:

txn

If the operation is to be transaction-protected, this parameter is an XmlTransaction handle returned from XmlManager::createTransaction.

name

Provides the name of the document to insert into the container. This name must be unique in the container. If DBXML_GEN_NAME is set, a system-defined string is appended to create a unique name. This applies if the name parameter is provided or empty. If the name is not unique within the container, an exception is thrown.

adopted_input

Identifies the input stream to use to read the document. Create the input stream using one of XmlManager::createLocalFileInputStream, XmlManager::createMemBufInputStream, XmlManager::createStdInInputStream, XmlManager::createURLInputStream, or XmlDocument::getContentAsXmlInputStream. The content read by the input stream must well-formed XML, or an exception is thrown. The XmlInputStream object provided is consumed (deleted) by this method.

context

The update context to use for the document insertion.

flags

This parameter must be set to 0 or the following values:

  • DBXML_GEN_NAME

    Generate a unique name. If no name is set for this XmlDocument , a system-defined unique name is generated. If a name is specified, a unique string is appended to that name to ensure uniqueness.

Add a document using a string

#include <DbXml.hpp>

std::string XmlContainer::putDocument(const std::string &name,
    const std::string &contents, XmlUpdateContext &context, 
    u_int32_t flags = 0)

std::string XmlContainer::putDocument(XmlTransaction &txn, 
    const std::string &name, const std::string &contents,
    XmlUpdateContext &context, u_int32_t flags = 0)

Inserts the XML document contained in the string into the container. The name used for the new document is returned by this method.

Parameters are:

txn

If the operation is to be transaction-protected, this parameter is an XmlTransaction handle returned from XmlManager::createTransaction.

name

Provides the name of the document to insert into the container. This name must be unique in the container. If DBXML_GEN_NAME is set, a system-defined string is appended to create a unique name. This applies if the name parameter is provided or empty. If the name is not unique within the container, an exception is thrown.

contents

The XML content to insert into the container. The content contained in this string must well-formed XML, or an exception is thrown.

context

The update context to use for the document insertion.

flags

This parameter must be set to 0 or the following values:

  • DBXML_GEN_NAME

    Generate a unique name. If no name is set for this XmlDocument , a system-defined unique name is generated. If a name is specified, a unique string is appended to that name to ensure uniqueness.

Errors

The XmlContainer::putDocument method may fail and throw XmlException , encapsulating one of the following non-zero errors:

DATABASE_ERROR

An error occurred in an underlying Berkeley DB database. The XmlException::getDbErrno method will return the error code for the error.

EVENT_ERROR

event reader

An error occured while adding a document using an XmlEventReader . This error can only be thrown if you are adding documents to your container using an XmlEventReader .

INDEXER_PARSER_ERROR

The XML Indexer could not parse the document. This error can not be thrown if you are using an XmlEventReader to add the document to your container.

UNIQUE_ERROR

The document does not have a name that is unique for the container.

Class

XmlContainer

See Also

XmlContainer Methods

Prev  Up  Next
XmlContainer::lookupStatistics  Home  XmlContainer::putDocumentAsEventWriter