You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xerces.apache.org by am...@apache.org on 2005/07/23 23:13:13 UTC
svn commit: r224543 [3/5] - in /xerces/c/trunk:
Projects/Win32/BCC.551/Xerces-all/XercesLib/
Projects/Win32/VC6/xerces-all/XercesLib/
Projects/Win32/VC7.1/xerces-all/CreateDOMDocument/
Projects/Win32/VC7.1/xerces-all/DOMCount/ Projects/Win32/VC7.1/xerc...
Copied: xerces/c/trunk/src/xercesc/dom/DOMLSParser.hpp (from r201963, xerces/c/trunk/src/xercesc/dom/DOMBuilder.hpp)
URL: http://svn.apache.org/viewcvs/xerces/c/trunk/src/xercesc/dom/DOMLSParser.hpp?p2=xerces/c/trunk/src/xercesc/dom/DOMLSParser.hpp&p1=xerces/c/trunk/src/xercesc/dom/DOMBuilder.hpp&r1=201963&r2=224543&rev=224543&view=diff
==============================================================================
--- xerces/c/trunk/src/xercesc/dom/DOMBuilder.hpp (original)
+++ xerces/c/trunk/src/xercesc/dom/DOMLSParser.hpp Sat Jul 23 14:11:41 2005
@@ -1,5 +1,5 @@
-#ifndef DOMBuilder_HEADER_GUARD_
-#define DOMBuilder_HEADER_GUARD_
+#ifndef DOMLSParser_HEADER_GUARD_
+#define DOMLSParser_HEADER_GUARD_
/*
* Copyright 2002,2004 The Apache Software Foundation.
@@ -24,29 +24,28 @@
#include <xercesc/util/XercesDefs.hpp>
+#include <xercesc/dom/DOMConfiguration.hpp>
XERCES_CPP_NAMESPACE_BEGIN
class DOMErrorHandler;
class DOMEntityResolver;
-class DOMInputSource;
-class DOMBuilderFilter;
+class DOMLSInput;
+class DOMLSParserFilter;
class DOMNode;
class DOMDocument;
class Grammar;
/**
- * DOMBuilder provides an API for parsing XML documents and building the
- * corresponding DOM document tree. A DOMBuilder instance is obtained from
- * the DOMImplementationLS interface by invoking its createDOMBuilder method.
- * This implementation also allows the applications to install an error and
- * an entity handler (useful extensions to the DOM specification).
+ * DOMLSParser provides an API for parsing XML documents and building the
+ * corresponding DOM document tree. A DOMLSParser instance is obtained from
+ * the DOMImplementationLS interface by invoking its createLSParser method.
*
* @since DOM Level 3
*
*/
-class CDOM_EXPORT DOMBuilder
+class CDOM_EXPORT DOMLSParser
{
protected :
// -----------------------------------------------------------------------
@@ -54,7 +53,7 @@
// -----------------------------------------------------------------------
/** @name Hidden constructors */
//@{
- DOMBuilder() {};
+ DOMLSParser() {};
//@}
private:
@@ -63,8 +62,8 @@
// -----------------------------------------------------------------------
/** @name Unimplemented constructors and operators */
//@{
- DOMBuilder(const DOMBuilder &);
- DOMBuilder & operator = (const DOMBuilder &);
+ DOMLSParser(const DOMLSParser &);
+ DOMLSParser & operator = (const DOMLSParser &);
//@}
public:
@@ -77,7 +76,7 @@
* Destructor
*
*/
- virtual ~DOMBuilder() {};
+ virtual ~DOMLSParser() {};
//@}
// -----------------------------------------------------------------------
@@ -86,43 +85,48 @@
/** @name Public Constants */
//@{
/**
- * Action types for use in parseWithContext.
+ * A set of possible actions for the parseWithContext method.
*
- * <p> <code>ACTION_REPLACE</code>:
- * Replace the context node with the result of parsing the input source.
- * For this action to work the context node must be an
- * <code>DOMElement</code>, <code>DOMText</code>, <code>DOMCDATASection</code>,
- * <code>DOMComment</code>, <code>DOMProcessingInstruction</code>, or
- * <code>DOMEntityReference</code> node.</p>
+ * <p><code>ACTION_APPEND_AS_CHILDREN</code>:
+ * Append the result of the parse operation as children of the context node.
+ * For this action to work, the context node must be a <code>DOMElement</code>
+ * or a <code>DOMDocumentFragment</code>. </p>
*
- * <p> <code>ACTION_APPEND</code>:
- * Append the result of parsing the input source to the context node. For
- * this action to work, the context node must be an <code>DOMElement</code>.</p>
+ * <p><code>ACTION_INSERT_AFTER</code>:
+ * Insert the result of the parse operation as the immediately following sibling
+ * of the context node. For this action to work the context node's parent must
+ * be a <code>DOMElement</code> or a <code>DOMDocumentFragment</code>. </p>
*
- * <p> <code>ACTION_INSERT_AFTER</code>:
- * Insert the result of parsing the input source after the context node.
- * For this action to work the context nodes parent must be an
- * <code>DOMElement</code>.</p>
+ * <p><code>ACTION_INSERT_BEFORE</code>:
+ * Insert the result of the parse operation as the immediately preceding sibling
+ * of the context node. For this action to work the context node's parent must
+ * be a <code>DOMElement</code> or a <code>DOMDocumentFragment</code>. </p>
*
- * <p> <code>ACTION_INSERT_BEFORE</code>:
- * Insert the result of parsing the input source before the context node.
- * For this action to work the context nodes parent must be an
- * <code>DOMElement</code>.</p>
+ * <p><code>ACTION_REPLACE</code>:
+ * Replace the context node with the result of the parse operation. For this
+ * action to work, the context node must have a parent, and the parent must be
+ * a <code>DOMElement</code> or a <code>DOMDocumentFragment</code>. </p>
+ *
+ * <p><code>ACTION_REPLACE_CHILDREN</code>:
+ * Replace all the children of the context node with the result of the parse
+ * operation. For this action to work, the context node must be a <code>DOMElement</code>,
+ * a <code>DOMDocument</code>, or a <code>DOMDocumentFragment</code>. </p>
*
* @see parseWithContext(...)
* @since DOM Level 3
*/
enum ActionType
{
- ACTION_REPLACE = 1,
- ACTION_APPEND_AS_CHILDREN = 2,
- ACTION_INSERT_AFTER = 3,
- ACTION_INSERT_BEFORE = 4
+ ACTION_APPEND_AS_CHILDREN = 1,
+ ACTION_REPLACE_CHILDREN = 2,
+ ACTION_INSERT_BEFORE = 3,
+ ACTION_INSERT_AFTER = 4,
+ ACTION_REPLACE = 5
};
//@}
// -----------------------------------------------------------------------
- // Virtual DOMBuilder interface
+ // Virtual DOMLSParser interface
// -----------------------------------------------------------------------
/** @name Functions introduced in DOM Level 3 */
//@{
@@ -132,69 +136,238 @@
// -----------------------------------------------------------------------
/**
- * Get a pointer to the error handler
- *
- * This method returns the installed error handler. If no handler
- * has been installed, then it will be a zero pointer.
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @return The pointer to the installed error handler object.
- * @since DOM Level 3
- */
- virtual DOMErrorHandler* getErrorHandler() = 0;
-
- /**
- * Get a const pointer to the error handler
- *
- * This method returns the installed error handler. If no handler
- * has been installed, then it will be a zero pointer.
- *
- * <p><b>"Experimental - subject to change"</b></p>
+ * Get a pointer to the <code>DOMConfiguration</code> object used when parsing
+ * an input source.
+ * This <code>DOMConfiguration</code> is specific to the parse operation.
+ * No parameter values from this <code>DOMConfiguration</code> object are passed
+ * automatically to the <code>DOMConfiguration</code> object on the
+ * <code>DOMDocument</code> that is created, or used, by the parse operation.
+ * The DOM application is responsible for passing any needed parameter values
+ * from this <code>DOMConfiguration</code> object to the <code>DOMConfiguration</code>
+ * object referenced by the <code>DOMDocument</code> object.
+ *
+ * In addition to the parameters recognized in on the <code>DOMConfiguration</code>
+ * interface defined in [DOM Level 3 Core], the <code>DOMConfiguration</code> objects
+ * for <code>DOMLSParser</code> add or modify the following parameters:
+ *
+ * "charset-overrides-xml-encoding"
+ * true [optional] (default)
+ * If a higher level protocol such as HTTP [IETF RFC 2616] provides an
+ * indication of the character encoding of the input stream being processed,
+ * that will override any encoding specified in the XML declaration or the
+ * Text declaration (see also section 4.3.3, "Character Encoding in Entities",
+ * in [XML 1.0]). Explicitly setting an encoding in the <code>DOMLSInput</code>
+ * overrides any encoding from the protocol.
+ * false [required]
+ * The parser ignores any character set encoding information from higher-level
+ * protocols.
+ *
+ * "disallow-doctype"
+ * true [optional]
+ * Throw a fatal "doctype-not-allowed" error if a doctype node is found while
+ * parsing the document. This is useful when dealing with things like SOAP
+ * envelopes where doctype nodes are not allowed.
+ * false [required] (default)
+ * Allow doctype nodes in the document.
+ *
+ * "ignore-unknown-character-denormalizations"
+ * true [required] (default)
+ * If, while verifying full normalization when [XML 1.1] is supported, a
+ * processor encounters characters for which it cannot determine the normalization
+ * properties, then the processor will ignore any possible denormalizations
+ * caused by these characters.
+ * This parameter is ignored for [XML 1.0].
+ * false [optional]
+ * Report an fatal "unknown-character-denormalization" error if a character
+ * is encountered for which the processor cannot determine the normalization
+ * properties.
+ *
+ * "infoset"
+ * See the definition of DOMConfiguration for a description of this parameter.
+ * Unlike in [DOM Level 3 Core], this parameter will default to true for DOMLSParser.
+ *
+ * "namespaces"
+ * true [required] (default)
+ * Perform the namespace processing as defined in [XML Namespaces] and
+ * [XML Namespaces 1.1].
+ * false [optional]
+ * Do not perform the namespace processing.
+ *
+ * "resource-resolver" [required]
+ * A pointer to a DOMLSResourceResolver object, or NULL. If the value of this parameter
+ * is not null when an external resource (such as an external XML entity or an XML schema
+ * location) is encountered, the implementation will request that the DOMLSResourceResolver
+ * referenced in this parameter resolves the resource.
+ *
+ * "supported-media-types-only"
+ * true [optional]
+ * Check that the media type of the parsed resource is a supported media type. If
+ * an unsupported media type is encountered, a fatal error of type "unsupported-media-type"
+ * will be raised. The media types defined in [IETF RFC 3023] must always be accepted.
+ * false [required] (default)
+ * Accept any media type.
+ *
+ * "validate"
+ * See the definition of <code>DOMConfiguration</code> for a description of this parameter.
+ * Unlike in [DOM Level 3 Core], the processing of the internal subset is always accomplished, even
+ * if this parameter is set to false.
+ *
+ * "validate-if-schema"
+ * See the definition of <code>DOMConfiguration</code> for a description of this parameter.
+ * Unlike in [DOM Level 3 Core], the processing of the internal subset is always accomplished, even
+ * if this parameter is set to false.
+ *
+ * "well-formed"
+ * See the definition of <code>DOMConfiguration</code> for a description of this parameter.
+ * Unlike in [DOM Level 3 Core], this parameter cannot be set to false.
+ *
+ * In addition to these, Xerces adds these non standard parameters:
+ *
+ * "http://apache.org/xml/properties/entity-resolver"
+ * A pointer to a XMLEntityResolver object, or NULL. If the value of this parameter
+ * is not null when an external resource (such as an external XML entity or an XML schema
+ * location) is encountered, the implementation will request that the XMLEntityResolver
+ * referenced in this parameter resolves the resource.
+ *
+ * "http://apache.org/xml/properties/schema/external-schemaLocation"
+ * A string holding a set of [namespaceUri schemaLocation] entries that will be treated as
+ * the content of the attribute xsi:schemaLocation of the root element
+ *
+ * "http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation"
+ * A string holding the schemaLocation for the empty namespace URI that will be treated as
+ * the content of the attribute xsi:noNamespaceSchemaLocation of the root element
+ *
+ * "http://apache.org/xml/properties/security-manager"
+ * A pointer to a SecurityManager object that will control how many entity references will be
+ * expanded during parsing
+ *
+ * "http://apache.org/xml/properties/scannerName"
+ * A string holding the type of scanner used while parsing. The valid names are:
+ * <li>IGXMLScanner: the default one, capable of both XMLSchema and DTD validation</li>
+ * <li>SGXMLScanner: a scanner that can only perform XMLSchema validation</li>
+ * <li>DGXMLScanner: a scanner that can only perform DTD validation</li>
+ * <li>WFXMLScanner: a scanner that cannot perform any type validation, only well-formedness</li>
+ *
+ * "http://apache.org/xml/properties/parser-use-DOMDocument-from-Implementation"
+ * A string holding the capabilities of the DOM implementation to be used to create the DOMDocument
+ * resulting from the parse operation. For instance, "LS" or "Core"
+ *
+ * "http://apache.org/xml/features/validation/schema"
+ * true
+ * Enable XMLSchema validation (note that also namespace processing should be enabled)
+ * false (default)
+ * Don't perform XMLSchema validation
+ *
+ * "http://apache.org/xml/features/validation/schema-full-checking"
+ * true
+ * Turn on full XMLSchema checking (e.g. Unique Particle Attribution)
+ * false (default)
+ * Don't perform full XMLSchema checking
+ *
+ * "http://apache.org/xml/features/dom/user-adopts-DOMDocument"
+ * true
+ * The DOMDocument objects returned by <code>parse</code> will be owned by the caller
+ * false (default)
+ * The DOMDocument objects returned by <code>parse</code> will be owned by this <code>DOMLSParser</code>
+ * and deleted when released
+ *
+ * "http://apache.org/xml/features/nonvalidating/load-external-dtd"
+ * true (default)
+ * Allow the parser to load external DTDs
+ * false
+ * References to external DTDs will be ignored
+ *
+ * "http://apache.org/xml/features/continue-after-fatal-error"
+ * true
+ * Parsing should try to continue even if a fatal error has been triggered, trying to generate a DOM tree
+ * from a non well-formed XML
+ * false (default)
+ * Violation of XML rules will abort parsing
+ *
+ * "http://apache.org/xml/features/validation-error-as-fatal"
+ * true
+ * Validation errors are treated as fatal errors, and abort parsing (unless "continue-after-fatal-error"
+ * has been specified)
+ * false (default)
+ * Validation errors are normal errors
+ *
+ * "http://apache.org/xml/features/validation/cache-grammarFromParse"
+ * true
+ * XMLSchemas referenced by an XML file are cached in order to be reused by other parse operations
+ * false (default)
+ * XMLSchemas loaded during a parse operation will be discarded before the next one
+ *
+ * "http://apache.org/xml/features/validation/use-cachedGrammarInParse"
+ * true
+ * During this parse operation, reuse the XMLSchemas found in the cache
+ * false (default)
+ * Don't reuse the XMLSchemas found in the cache
+ *
+ * "http://apache.org/xml/features/calculate-src-ofs"
+ * true
+ * During parsing update the position in the source stream
+ * false (default)
+ * Don't waste time computing the position in the source stream
+ *
+ * "http://apache.org/xml/features/standard-uri-conformant"
+ * true
+ * Require that every URL being resolved is made of valid URL characters only
+ * false (default)
+ * Allow invalid URL characters in URL (e.g. spaces)
+ *
+ * "http://apache.org/xml/features/dom-has-psvi-info"
+ * true
+ * Add schema informations to DOMElement and DOMAttr nodes in the output DOM tree
+ * false (default)
+ * Don't store schema informations in the output DOM tree
+ *
+ * "http://apache.org/xml/features/generate-synthetic-annotations"
+ * true
+ * Create annotation objects in the representation of the loaded XMLSchemas
+ * false (default)
+ * Discard annotations found in the loaded XMLSchemas
+ *
+ * "http://apache.org/xml/features/validate-annotations"
+ * true
+ * Check that annotations are valid according to their XMLSchema definition
+ * false (default)
+ * Don't validate annotations
+ *
+ * "http://apache.org/xml/features/validation/identity-constraint-checking"
+ * true (default)
+ * Enforce identity constraints specified in the XMLSchema
+ * false
+ * Don't enforce identity constraints
+ *
+ * "http://apache.org/xml/features/validation/ignoreCachedDTD"
+ * true
+ * Don't reuse DTDs found in the cache, even if use-cachedGrammarInParse is <code>true</code>
+ * false (default)
+ * Reuse DTDs found in the cache, if use-cachedGrammarInParse is <code>true</code>
+ *
+ * "http://apache.org/xml/features/schema/ignore-annotations"
+ * true
+ * Don't process annotations found in an XMLSchema
+ * false (default)
+ * Process the annotations found in an XMLSchema
+ *
+ * "http://apache.org/xml/features/disable-default-entity-resolution"
+ * true
+ * Entities will be resolved only by a resolver installed by the user
+ * false (default)
+ * If the entity resolver has not been installed, or it refuses to resolve the given entity, the
+ * parser will try to locate it himself
+ *
+ * "http://apache.org/xml/features/validation/schema/skip-dtd-validation"
+ * true
+ * If XMLSchema validation is <code>true</code>, DTD validation will not be performed
+ * false (default)
+ * If a DTD is found, it will be used to validate the XML
*
- * @return A const pointer to the installed error handler object.
+ * @return The pointer to the configuration object.
* @since DOM Level 3
*/
- virtual const DOMErrorHandler* getErrorHandler() const = 0;
-
- /**
- * Get a pointer to the entity resolver
- *
- * This method returns the installed entity resolver. If no resolver
- * has been installed, then it will be a zero pointer.
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @return The pointer to the installed entity resolver object.
- * @since DOM Level 3
- */
- virtual DOMEntityResolver* getEntityResolver() = 0;
-
- /**
- * Get a const pointer to the entity resolver
- *
- * This method returns the installed entity resolver. If no resolver
- * has been installed, then it will be a zero pointer.
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @return A const pointer to the installed entity resolver object.
- * @since DOM Level 3
- */
- virtual const DOMEntityResolver* getEntityResolver() const = 0;
-
- /**
- * Get a pointer to the application filter
- *
- * This method returns the installed application filter. If no filter
- * has been installed, then it will be a zero pointer.
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @return The pointer to the installed application filter.
- * @since DOM Level 3
- */
- virtual DOMBuilderFilter* getFilter() = 0;
+ virtual DOMConfiguration* getDomConfig() = 0;
/**
* Get a const pointer to the application filter
@@ -202,268 +375,222 @@
* This method returns the installed application filter. If no filter
* has been installed, then it will be a zero pointer.
*
- * <p><b>"Experimental - subject to change"</b></p>
- *
* @return A const pointer to the installed application filter
* @since DOM Level 3
*/
- virtual const DOMBuilderFilter* getFilter() const = 0;
+ virtual const DOMLSParserFilter* getFilter() const = 0;
- // -----------------------------------------------------------------------
- // Setter methods
- // -----------------------------------------------------------------------
/**
- * Set the error handler
- *
- * This method allows applications to install their own error handler
- * to trap error and warning messages.
- *
- * <i>Any previously set handler is merely dropped, since the parser
- * does not own them.</i>
- *
- * <p><b>"Experimental - subject to change"</b></p>
+ * Return whether the parser is asynchronous
*
- * @param handler A const pointer to the user supplied error
- * handler.
- *
- * @see #getErrorHandler
+ * @return <code>true</code> if the <code>DOMLSParser</code> is asynchronous,
+ * <code>false</code> if it is synchronous
* @since DOM Level 3
*/
- virtual void setErrorHandler(DOMErrorHandler* const handler) = 0;
+ virtual bool getAsync() const = 0;
/**
- * Set the entity resolver
- *
- * This method allows applications to install their own entity
- * resolver. By installing an entity resolver, the applications
- * can trap and potentially redirect references to external
- * entities.
+ * Return whether the parser is busy parsing
*
- * <i>Any previously set resolver is merely dropped, since the parser
- * does not own them.</i>
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @param handler A const pointer to the user supplied entity
- * resolver.
- *
- * @see #getEntityResolver
+ * @return <code>true</code> if the <code>DOMLSParser</code> is currently busy
+ * loading a document, otherwise <code>false</code>.
* @since DOM Level 3
*/
- virtual void setEntityResolver(DOMEntityResolver* const handler) = 0;
+ virtual bool getBusy() const = 0;
+ // -----------------------------------------------------------------------
+ // Setter methods
+ // -----------------------------------------------------------------------
/**
* Set the application filter
*
* When the application provides a filter, the parser will call out to
- * the filter at the completion of the construction of each Element node.
- * The filter implementation can choose to remove the element from the
- * document being constructed (unless the element is the document element)
- * or to terminate the parse early. If the document is being validated
- * when it's loaded the validation happens before the filter is called.
+ * the filter at the completion of the construction of each <code>DOMElement</code>
+ * node. The filter implementation can choose to remove the element from the
+ * document being constructed or to terminate the parse early.
+ * The filter is invoked after the operations requested by the DOMConfiguration
+ * parameters have been applied. For example, if "validate" is set to true,
+ * the validation is done before invoking the filter.
*
* <i>Any previously set filter is merely dropped, since the parser
* does not own them.</i>
*
- * <p><b>"Experimental - subject to change"</b></p>
- *
* @param filter A const pointer to the user supplied application
* filter.
*
* @see #getFilter
* @since DOM Level 3
*/
- virtual void setFilter(DOMBuilderFilter* const filter) = 0;
-
- // -----------------------------------------------------------------------
- // Feature methods
- // -----------------------------------------------------------------------
- /**
- * Set the state of a feature
- *
- * It is possible for a DOMBuilder to recognize a feature name but to be
- * unable to set its value.
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * See http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderFeatures for
- * the list of supported features.
- *
- * @param name The feature name.
- * @param state The requested state of the feature (true or false).
- * @exception DOMException
- * NOT_SUPPORTED_ERR: Raised when the DOMBuilder recognizes the
- * feature name but cannot set the requested value.
- * <br>NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize
- * the feature name.
- *
- * @see #setFeature
- * @see #canSetFeature
- * @since DOM Level 3
- */
- virtual void setFeature(const XMLCh* const name, const bool state) = 0;
-
- /**
- * Look up the value of a feature.
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @param name The feature name.
- * @return The current state of the feature (true or false)
- * @exception DOMException
- * NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize
- * the feature name.
- *
- * @see #getFeature
- * @see #canSetFeature
- * @since DOM Level 3
- */
- virtual bool getFeature(const XMLCh* const name) const = 0;
-
- /**
- * Query whether setting a feature to a specific value is supported.
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @param name The feature name.
- * @param state The requested state of the feature (true or false).
- * @return <code>true</code> if the feature could be successfully set
- * to the specified value, or <code>false</code> if the feature
- * is not recognized or the requested value is not supported. The
- * value of the feature itself is not changed.
- *
- * @see #getFeature
- * @see #setFeature
- * @since DOM Level 3
- */
- virtual bool canSetFeature(const XMLCh* const name, const bool state) const = 0;
+ virtual void setFilter(DOMLSParserFilter* const filter) = 0;
// -----------------------------------------------------------------------
// Parsing methods
// -----------------------------------------------------------------------
/**
- * Parse via an input source object
- *
- * This method invokes the parsing process on the XML file specified
- * by the DOMInputSource parameter. This API is borrowed from the
- * SAX Parser interface.
+ * Parse an XML document from a resource identified by a <code>DOMLSInput</code>.
*
* The parser owns the returned DOMDocument. It will be deleted
* when the parser is released.
*
- * <p><b>"Experimental - subject to change"</b></p>
+ * @param source The <code>DOMLSInput</code> from which the source of the document
+ * is to be read.
+ * @return If the <code>DOMLSParser</code> is a synchronous <code>DOMLSParser</code>
+ * the newly created and populated <code>DOMDocument</code> is returned.
+ * If the <code>DOMLSParser</code> is asynchronous then <code>NULL</code>
+ * is returned since the document object may not yet be constructed when
+ * this method returns.
+ * @exception DOMException INVALID_STATE_ERR: Raised if the <code>DOMLSParser::busy</code>
+ * attribute is true.
+ * @exception DOMLSException PARSE_ERR: Raised if the <code>DOMLSParser</code> was unable
+ * to load the XML document. DOM applications should
+ * attach a <code>DOMErrorHandler</code> using the
+ * parameter "error-handler" if they wish to get details
+ * on the error.
*
- * @param source A const reference to the DOMInputSource object which
- * points to the XML file to be parsed.
- * @return If the DOMBuilder is a synchronous DOMBuilder the newly created
- * and populated DOMDocument is returned. If the DOMBuilder is
- * asynchronous then <code>null</code> is returned since the
- * document object is not yet parsed when this method returns.
- * @exception SAXException Any SAX exception, possibly
- * wrapping another exception.
- * @exception XMLException An exception from the parser or client
- * handler code.
- * @exception DOMException A DOM exception as per DOM spec.
- *
- * @see DOMInputSource#DOMInputSource
- * @see #setEntityResolver
- * @see #setErrorHandler
+ * @see DOMLSInput#DOMLSInput
+ * @see DOMConfiguration
* @see resetDocumentPool
* @since DOM Level 3
*/
- virtual DOMDocument* parse(const DOMInputSource& source) = 0;
+ virtual DOMDocument* parse(const DOMLSInput& source) = 0;
/**
- * Parse via a file path or URL
- *
- * This method invokes the parsing process on the XML file specified by
- * the Unicode string parameter 'systemId'.
+ * Parse an XML document from a location identified by a URI reference [IETF RFC 2396].
+ * If the URI contains a fragment identifier (see section 4.1 in [IETF RFC 2396]),
+ * the behavior is not defined by this specification, future versions of this
+ * specification may define the behavior.
*
* The parser owns the returned DOMDocument. It will be deleted
* when the parser is released.
*
- * <p><b>"Experimental - subject to change"</b></p>
+ * @param uri The location of the XML document to be read (in Unicode)
+ * @return If the <code>DOMLSParser</code> is a synchronous <code>DOMLSParser</code>
+ * the newly created and populated <code>DOMDocument</code> is returned.
+ * If the <code>DOMLSParser</code> is asynchronous then <code>NULL</code>
+ * is returned since the document object is not yet parsed when this method returns.
+ * @exception DOMException INVALID_STATE_ERR: Raised if the <code>DOMLSParser::busy</code>
+ * attribute is true.
+ * @exception DOMLSException PARSE_ERR: Raised if the <code>DOMLSParser</code> was unable
+ * to load the XML document. DOM applications should
+ * attach a <code>DOMErrorHandler</code> using the
+ * parameter "error-handler" if they wish to get details
+ * on the error.
*
- * @param systemId A const XMLCh pointer to the Unicode string which
- * contains the path to the XML file to be parsed.
- * @return If the DOMBuilder is a synchronous DOMBuilder the newly created
- * and populated DOMDocument is returned. If the DOMBuilder is
- * asynchronous then <code>null</code> is returned since the
- * document object is not yet parsed when this method returns.
- * @exception SAXException Any SAX exception, possibly
- * wrapping another exception.
- * @exception XMLException An exception from the parser or client
- * handler code.
- * @exception DOMException A DOM exception as per DOM spec.
- *
- * @see #parse(DOMInputSource,...)
+ * @see #parse(DOMLSInput,...)
* @see resetDocumentPool
* @since DOM Level 3
*/
- virtual DOMDocument* parseURI(const XMLCh* const systemId) = 0;
+ virtual DOMDocument* parseURI(const XMLCh* const uri) = 0;
/**
- * Parse via a file path or URL (in the local code page)
- *
- * This method invokes the parsing process on the XML file specified by
- * the native char* string parameter 'systemId'.
+ * Parse an XML document from a location identified by a URI reference [IETF RFC 2396].
+ * If the URI contains a fragment identifier (see section 4.1 in [IETF RFC 2396]),
+ * the behavior is not defined by this specification, future versions of this
+ * specification may define the behavior.
*
* The parser owns the returned DOMDocument. It will be deleted
* when the parser is released.
*
- * <p><b>"Experimental - subject to change"</b></p>
+ * @param uri The location of the XML document to be read (in the local code page)
+ * @return If the <code>DOMLSParser</code> is a synchronous <code>DOMLSParser</code>
+ * the newly created and populated <code>DOMDocument</code> is returned.
+ * If the <code>DOMLSParser</code> is asynchronous then <code>NULL</code>
+ * is returned since the document object is not yet parsed when this method returns.
+ * @exception DOMException INVALID_STATE_ERR: Raised if the <code>DOMLSParser::busy</code>
+ * attribute is true.
+ * @exception DOMLSException PARSE_ERR: Raised if the <code>DOMLSParser</code> was unable
+ * to load the XML document. DOM applications should
+ * attach a <code>DOMErrorHandler</code> using the
+ * parameter "error-handler" if they wish to get details
+ * on the error.
*
- * @param systemId A const char pointer to a native string which
- * contains the path to the XML file to be parsed.
- * @return If the DOMBuilder is a synchronous DOMBuilder the newly created
- * and populated DOMDocument is returned. If the DOMBuilder is
- * asynchronous then <code>null</code> is returned since the
- * document object is not yet parsed when this method returns.
- * @exception SAXException Any SAX exception, possibly
- * wrapping another exception.
- * @exception XMLException An exception from the parser or client
- * handler code.
- * @exception DOMException A DOM exception as per DOM spec.
- *
- * @see #parse(DOMInputSource,...)
+ * @see #parse(DOMLSInput,...)
* @see resetDocumentPool
+ * @since DOM Level 3
*/
- virtual DOMDocument* parseURI(const char* const systemId) = 0;
+ virtual DOMDocument* parseURI(const char* const uri) = 0;
/**
- * Parse via an input source object
- *
- * This method invokes the parsing process on the XML file specified
- * by the DOMInputSource parameter, and inserts the content into an
- * existing document at the position specified with the contextNode
- * and action arguments. When parsing the input stream the context node
- * is used for resolving unbound namespace prefixes.
- *
- * <p><b>"Experimental - subject to change"</b></p>
+ * Parse an XML fragment from a resource identified by a <code>DOMLSInput<code>
+ * and insert the content into an existing document at the position specified
+ * with the context and action arguments. When parsing the input stream, the
+ * context node (or its parent, depending on where the result will be inserted)
+ * is used for resolving unbound namespace prefixes. The context node's
+ * <code>ownerDocument</code> node (or the node itself if the node of type
+ * <code>DOCUMENT_NODE</code>) is used to resolve default attributes and entity
+ * references.
+ * As the new data is inserted into the document, at least one mutation event
+ * is fired per new immediate child or sibling of the context node.
+ * If the context node is a <code>DOMDocument</code> node and the action is
+ * <code>ACTION_REPLACE_CHILDREN</code>, then the document that is passed as
+ * the context node will be changed such that its <code>xmlEncoding</code>,
+ * <code>documentURI</code>, <code>xmlVersion</code>, <code>inputEncoding</code>,
+ * <code>xmlStandalone</code>, and all other such attributes are set to what they
+ * would be set to if the input source was parsed using <code>DOMLSParser::parse()</code>.
+ * This method is always synchronous, even if the <code>DOMLSParser</code> is
+ * asynchronous (<code>DOMLSParser::getAsync()</code> returns true).
+ * If an error occurs while parsing, the caller is notified through the <code>ErrorHandler</code>
+ * instance associated with the "error-handler" parameter of the <code>DOMConfiguration</code>.
+ * When calling <code>parseWithContext</code>, the values of the following configuration
+ * parameters will be ignored and their default values will always be used instead:
+ * "validate",
+ * "validate-if-schema"
+ * "element-content-whitespace".
+ * Other parameters will be treated normally, and the parser is expected to call
+ * the <code>DOMLSParserFilter</code> just as if a whole document was parsed.
+ *
+ * @param source The <code>DOMLSInput</code> from which the source document is
+ * to be read. The source document must be an XML fragment, i.e.
+ * anything except a complete XML document (except in the case where
+ * the context node of type <code>DOCUMENT_NODE</code>, and the action is
+ * <code>ACTION_REPLACE_CHILDREN</code>), a <code>DOCTYPE</code>
+ * (internal subset), entity declaration(s), notation declaration(s),
+ * or XML or text declaration(s).
+ * @param contextNode The node that is used as the context for the data that is being
+ * parsed. This node must be a <code>DOMDocument<code> node, a
+ * <code>DOMDocumentFragment</code> node, or a node of a type that
+ * is allowed as a child of an <code>DOMElement</code> node, e.g.
+ * it cannot be an <code>DOMAttribute</code> node.
+ * @param action This parameter describes which action should be taken between the new
+ * set of nodes being inserted and the existing children of the context node.
+ * The set of possible actions is defined in <code>ACTION_TYPES</code> above.
+ * @return Return the node that is the result of the parse operation. If the result is more
+ * than one top-level node, the first one is returned.
*
- * @param source A const reference to the DOMInputSource object which
- * points to the XML file to be parsed.
- * @param contextNode The node that is used as the context for the data
- * that is being parsed. This node must be a Document
- * node, a DocumentFragment node, or a node of a type
- * that is allowed as a child of an element, e.g. it
- * can not be an attribute node.
- * @param action This parameter describes which action should be taken
- * between the new set of node being inserted and the
- * existing children of the context node.
* @exception DOMException
- * NOT_SUPPORTED_ERR: Raised when the DOMBuilder doesn't support
- * this method.
- * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is
- * readonly.
+ * HIERARCHY_REQUEST_ERR: Raised if the content cannot replace, be inserted before, after,
+ * or as a child of the context node (see also <code>DOMNode::insertBefore</code>
+ * or <code>DOMNode::replaceChild</code> in [DOM Level 3 Core]).
+ * NOT_SUPPORTED_ERR: Raised if the <code>DOMLSParser</code> doesn't support this method,
+ * or if the context node is of type <code>DOMDocument</code> and the DOM
+ * implementation doesn't support the replacement of the <code>DOMDocumentType</code>
+ * child or <code>DOMElement</code> child.
+ * NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is a read only node and the content
+ * is being appended to its child list, or if the parent node of
+ * the context node is read only node and the content is being
+ * inserted in its child list.
+ * INVALID_STATE_ERR: Raised if the <code>DOMLSParser::getBusy()</code> returns true.
+ *
+ * @exception DOMLSException PARSE_ERR: Raised if the <code>DOMLSParser</code> was unable to load
+ * the XML fragment. DOM applications should attach a
+ * <code>DOMErrorHandler</code> using the parameter "error-handler"
+ * if they wish to get details on the error.
* @since DOM Level 3
*/
virtual void parseWithContext
(
- const DOMInputSource& source
- , DOMNode* const contextNode
- , const short action
+ const DOMLSInput& source
+ , DOMNode* contextNode
+ , const unsigned short action
) = 0;
+
+ /**
+ * Abort the loading of the document that is currently being loaded by the <code>DOMLSParser</code>.
+ * If the <code>DOMLSParser</code> is currently not busy, a call to this method does nothing.
+ *
+ * @since DOM Level 3
+ */
+ virtual void abort() = 0;
//@}
// -----------------------------------------------------------------------
@@ -471,55 +598,8 @@
// -----------------------------------------------------------------------
/** @name Non-standard Extension */
//@{
-
- /**
- * Query the current value of a property in a DOMBuilder.
- *
- * The builder owns the returned pointer. The memory allocated for
- * the returned pointer will be destroyed when the builder is deleted.
- *
- * To ensure assessiblity of the returned information after the builder
- * is deleted, callers need to copy and store the returned information
- * somewhere else; otherwise you may get unexpected result. Since the returned
- * pointer is a generic void pointer, see
- * http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderProperties to learn
- * exactly what type of property value each property returns for replication.
- *
- * @param name The unique identifier (URI) of the property being set.
- * @return The current value of the property. The pointer spans the same
- * life-time as the parser. A null pointer is returned if nothing
- * was specified externally.
- * @exception DOMException
- * <br>NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize
- * the requested property.
- */
- virtual void* getProperty(const XMLCh* const name) const = 0 ;
-
- /**
- * Set the value of any property in a DOMBuilder.
- * See http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderProperties for
- * the list of supported properties.
- *
- * It takes a void pointer as the property value. Application is required to initialize this void
- * pointer to a correct type. See http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderProperties
- * to learn exactly what type of property value each property expects for processing.
- * Passing a void pointer that was initialized with a wrong type will lead to unexpected result.
- * If the same property is set more than once, the last one takes effect.
- *
- * @param name The unique identifier (URI) of the property being set.
- * @param value The requested value for the property.
- * See http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderProperties to learn
- * exactly what type of property value each property expects for processing.
- * Passing a void pointer that was initialized with a wrong type will lead
- * to unexpected result.
- * @exception DOMException
- * <br>NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize
- * the requested property.
- */
- virtual void setProperty(const XMLCh* const name, void* value) = 0 ;
-
/**
- * Called to indicate that this DOMBuilder is no longer in use
+ * Called to indicate that this DOMLSParser is no longer in use
* and that the implementation may relinquish any resources associated with it.
*
* Access to a released object will lead to unexpected result.
@@ -556,13 +636,13 @@
* object.
*
* This method invokes the preparsing process on a schema grammar XML
- * file specified by the DOMInputSource parameter. If the 'toCache' flag
+ * file specified by the DOMLSInput parameter. If the 'toCache' flag
* is enabled, the parser will cache the grammars for re-use. If a grammar
* key is found in the pool, no caching of any grammar will take place.
*
* <p><b>"Experimental - subject to change"</b></p>
*
- * @param source A const reference to the DOMInputSource object which
+ * @param source A const reference to the DOMLSInput object which
* points to the schema grammar file to be preparsed.
* @param grammarType The grammar type (Schema or DTD).
* @param toCache If <code>true</code>, we cache the preparsed grammar,
@@ -576,9 +656,9 @@
* handler code.
* @exception DOMException A DOM exception as per DOM spec.
*
- * @see DOMInputSource#DOMInputSource
+ * @see DOMLSInput#DOMLSInput
*/
- virtual Grammar* loadGrammar(const DOMInputSource& source,
+ virtual Grammar* loadGrammar(const DOMLSInput& source,
const short grammarType,
const bool toCache = false) = 0;
Added: xerces/c/trunk/src/xercesc/dom/DOMLSParserFilter.hpp
URL: http://svn.apache.org/viewcvs/xerces/c/trunk/src/xercesc/dom/DOMLSParserFilter.hpp?rev=224543&view=auto
==============================================================================
--- xerces/c/trunk/src/xercesc/dom/DOMLSParserFilter.hpp (added)
+++ xerces/c/trunk/src/xercesc/dom/DOMLSParserFilter.hpp Sat Jul 23 14:11:41 2005
@@ -0,0 +1,163 @@
+#ifndef DOMLSParserFilter_HEADER_GUARD_
+#define DOMLSParserFilter_HEADER_GUARD_
+
+/*
+ * Copyright 2002,2004 The Apache Software Foundation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * $Id$
+ */
+
+/**
+ *
+ * DOMLSParserFilter.hpp: interface for the DOMLSParserFilter class.
+ *
+ * DOMLSParserFilter provide applications the ability to examine nodes
+ * as they are being created during the parse process.
+ *
+ * DOMLSParserFilter lets the application decide what nodes should be
+ * in the output DOM tree or not.
+ *
+ * @since DOM Level 3
+ */
+
+
+XERCES_CPP_NAMESPACE_BEGIN
+
+
+class CDOM_EXPORT DOMLSParserFilter {
+protected:
+ // -----------------------------------------------------------------------
+ // Hidden constructors
+ // -----------------------------------------------------------------------
+ /** @name Hidden constructors */
+ //@{
+ DOMLSParserFilter() {};
+ //@}
+
+private:
+ // -----------------------------------------------------------------------
+ // Unimplemented constructors and operators
+ // -----------------------------------------------------------------------
+ /** @name Unimplemented constructors and operators */
+ //@{
+ DOMLSParserFilter(const DOMLSParserFilter &);
+ DOMLSParserFilter & operator = (const DOMLSParserFilter &);
+ //@}
+
+
+public:
+ // -----------------------------------------------------------------------
+ // All constructors are hidden, just the destructor is available
+ // -----------------------------------------------------------------------
+ /** @name Destructor */
+ //@{
+ /**
+ * Destructor
+ *
+ */
+ virtual ~DOMLSParserFilter() {};
+ //@}
+
+ // -----------------------------------------------------------------------
+ // Class Types
+ // -----------------------------------------------------------------------
+ /** @name Public Contants */
+ //@{
+ /**
+ * Constants returned by acceptNode.
+ *
+ * <p><code>FILTER_ACCEPT:</code>
+ * Accept the node.</p>
+ *
+ * <p><code>FILTER_REJECT:</code>
+ * Reject the node and its children.</p>
+ *
+ * <p><code>FILTER_SKIP:</code>
+ * Skip this single node. The children of this node will still be considered.</p>
+ *
+ * <p><code>FILTER_INTERRUPT:</code>
+ * Interrupt the normal processing of the document.</p>
+ *
+ * @since DOM Level 3
+ */
+ enum FilterAction {FILTER_ACCEPT = 1,
+ FILTER_REJECT = 2,
+ FILTER_SKIP = 3,
+ FILTER_INTERRUPT = 4};
+
+ // -----------------------------------------------------------------------
+ // Virtual DOMLSParserFilter interface
+ // -----------------------------------------------------------------------
+ /** @name Functions introduced in DOM Level 3 */
+ //@{
+ /**
+ * This method will be called by the parser at the completion of the parsing of each node.
+ * The node and all of its descendants will exist and be complete. The parent node will also exist,
+ * although it may be incomplete, i.e. it may have additional children that have not yet been parsed.
+ * Attribute nodes are never passed to this function.
+ * From within this method, the new node may be freely modified - children may be added or removed,
+ * text nodes modified, etc. The state of the rest of the document outside this node is not defined,
+ * and the affect of any attempt to navigate to, or to modify any other part of the document is undefined.
+ * For validating parsers, the checks are made on the original document, before any modification by the
+ * filter. No validity checks are made on any document modifications made by the filter.
+ * If this new node is rejected, the parser might reuse the new node and any of its descendants.
+ *
+ * @param node The newly constructed element. At the time this method is called, the element is complete -
+ * it has all of its children (and their children, recursively) and attributes, and is attached
+ * as a child to its parent.
+ * @return One of the FilterAction enum
+ */
+ virtual short acceptNode(DOMNode* node) = 0;
+
+ /**
+ * The parser will call this method after each <code>DOMElement</code> start tag has been scanned,
+ * but before the remainder of the <code>DOMElement</code> is processed. The intent is to allow the element,
+ * including any children, to be efficiently skipped. Note that only element nodes are passed to the
+ * startElement function.
+ * The element node passed to startElement for filtering will include all of the attributes, but none
+ * of the children nodes. The <code>DOMElement</code> may not yet be in place in the document being
+ * constructed (it may not have a parent node.)
+ * A startElement filter function may access or change the attributes for the <code>DOMElement</code>.
+ * Changing namespace declarations will have no effect on namespace resolution by the parser.
+ *
+ * @param node The newly encountered element. At the time this method is called, the element is incomplete -
+ * it will have its attributes, but no children.
+ * @return One of the FilterAction enum
+ */
+ virtual short startElement(DOMElement* node) = 0;
+
+ /**
+ * Tells the <code>DOMLSParser</code> what types of nodes to show to the method <code>DOMLSParserFilter::acceptNode</code>.
+ * If a node is not shown to the filter using this attribute, it is automatically included in the DOM document being built.
+ * See <code>DOMNodeFilter</code> for definition of the constants. The constants SHOW_ATTRIBUTE, SHOW_DOCUMENT,
+ * SHOW_DOCUMENT_TYPE, SHOW_NOTATION, SHOW_ENTITY, and SHOW_DOCUMENT_FRAGMENT are meaningless here.
+ * Those nodes will never be passed to DOMLSParserFilter::acceptNode.
+ *
+ * @return The constants of what types of nodes to show.
+ * @since DOM Level 3
+ */
+ virtual unsigned long getWhatToShow() const = 0;
+
+ //@}
+
+private:
+
+};
+
+XERCES_CPP_NAMESPACE_END
+
+#endif
Propchange: xerces/c/trunk/src/xercesc/dom/DOMLSParserFilter.hpp
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: xerces/c/trunk/src/xercesc/dom/DOMLSParserFilter.hpp
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Copied: xerces/c/trunk/src/xercesc/dom/DOMLSSerializer.hpp (from r201963, xerces/c/trunk/src/xercesc/dom/DOMWriter.hpp)
URL: http://svn.apache.org/viewcvs/xerces/c/trunk/src/xercesc/dom/DOMLSSerializer.hpp?p2=xerces/c/trunk/src/xercesc/dom/DOMLSSerializer.hpp&p1=xerces/c/trunk/src/xercesc/dom/DOMWriter.hpp&r1=201963&r2=224543&rev=224543&view=diff
==============================================================================
--- xerces/c/trunk/src/xercesc/dom/DOMWriter.hpp (original)
+++ xerces/c/trunk/src/xercesc/dom/DOMLSSerializer.hpp Sat Jul 23 14:11:41 2005
@@ -1,5 +1,5 @@
-#ifndef DOMWriter_HEADER_GUARD_
-#define DOMWriter_HEADER_GUARD_
+#ifndef DOMLSSerializer_HEADER_GUARD_
+#define DOMLSSerializer_HEADER_GUARD_
/*
* Copyright 2002,2004 The Apache Software Foundation.
@@ -23,11 +23,11 @@
/**
*
- * DOMWriter provides an API for serializing (writing) a DOM document out in
+ * DOMLSSerializer provides an API for serializing (writing) a DOM document out in
* an XML document. The XML data is written to an output stream, the type of
* which depends on the specific language bindings in use. During
* serialization of XML data, namespace fixup is done when possible.
- * <p> <code>DOMWriter</code> accepts any node type for serialization. For
+ * <p> <code>DOMLSSerializer</code> accepts any node type for serialization. For
* nodes of type <code>Document</code> or <code>Entity</code>, well formed
* XML will be created if possible. The serialized output for these node
* types is either as a Document or an External Entity, respectively, and is
@@ -40,7 +40,7 @@
* follows Documents are written including an XML declaration and a DTD
* subset, if one exists in the DOM. Writing a document node serializes the
* entire document. Entity nodes, when written directly by
- * <code>writeNode</code> defined in the <code>DOMWriter</code> interface,
+ * <code>write</code> defined in the <code>DOMLSSerializer</code> interface,
* output the entity expansion but no namespace fixup is done. The resulting
* output will be valid as an external entity. Entity References nodes are
* serializes as an entity reference of the form
@@ -77,7 +77,7 @@
* as an error. An example would be serializing the element
* <LaCa�ada/> with the encoding="us-ascii".
* <p> When requested by setting the <code>normalize-characters</code> feature
- * on <code>DOMWriter</code>, all data to be serialized, both markup and
+ * on <code>DOMLSSerializer</code>, all data to be serialized, both markup and
* character data, is W3C Text normalized according to the rules defined in
* . The W3C Text normalization process affects only the data as it is being
* written; it does not alter the DOM's view of the document after
@@ -108,17 +108,17 @@
* description about warning about unbound entity refs. Entity refs are
* always serialized as &foo;, also mention this in the load part of
* this spec.
- * <p> When serializing a document the DOMWriter checks to see if the document
+ * <p> When serializing a document the DOMLSSerializer checks to see if the document
* element in the document is a DOM Level 1 element or a DOM Level 2 (or
* higher) element (this check is done by looking at the localName of the
* root element). If the root element is a DOM Level 1 element then the
- * DOMWriter will issue an error if a DOM Level 2 (or higher) element is
+ * DOMLSSerializer will issue an error if a DOM Level 2 (or higher) element is
* found while serializing. Likewise if the document element is a DOM Level
- * 2 (or higher) element and the DOMWriter sees a DOM Level 1 element an
+ * 2 (or higher) element and the DOMLSSerializer sees a DOM Level 1 element an
* error is issued. Mixing DOM Level 1 elements with DOM Level 2 (or higher)
* is not supported.
- * <p> <code>DOMWriter</code>s have a number of named features that can be
- * queried or set. The name of <code>DOMWriter</code> features must be valid
+ * <p> <code>DOMLSSerializer</code>s have a number of named features that can be
+ * queried or set. The name of <code>DOMLSSerializer</code> features must be valid
* XML names. Implementation specific features (extensions) should choose an
* implementation dependent prefix to avoid name collisions.
* <p>Here is a list of properties that must be recognized by all
@@ -242,20 +242,21 @@
#include <xercesc/dom/DOMNode.hpp>
-#include <xercesc/dom/DOMWriterFilter.hpp>
+#include <xercesc/dom/DOMLSSerializerFilter.hpp>
#include <xercesc/dom/DOMErrorHandler.hpp>
+#include <xercesc/dom/DOMConfiguration.hpp>
#include <xercesc/framework/XMLFormatter.hpp>
XERCES_CPP_NAMESPACE_BEGIN
-class CDOM_EXPORT DOMWriter {
+class CDOM_EXPORT DOMLSSerializer {
protected :
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
/** @name Hidden constructors */
//@{
- DOMWriter() {};
+ DOMLSSerializer() {};
//@}
private:
// -----------------------------------------------------------------------
@@ -263,8 +264,8 @@
// -----------------------------------------------------------------------
/** @name Unimplemented constructors and operators */
//@{
- DOMWriter(const DOMWriter &);
- DOMWriter & operator = (const DOMWriter &);
+ DOMLSSerializer(const DOMLSSerializer &);
+ DOMLSSerializer & operator = (const DOMLSSerializer &);
//@}
@@ -278,11 +279,11 @@
* Destructor
*
*/
- virtual ~DOMWriter() {};
+ virtual ~DOMLSSerializer() {};
//@}
// -----------------------------------------------------------------------
- // Virtual DOMWriter interface
+ // Virtual DOMLSSerializer interface
// -----------------------------------------------------------------------
/** @name Functions introduced in DOM Level 3 */
//@{
@@ -290,61 +291,80 @@
// Feature methods
// -----------------------------------------------------------------------
/**
- * Query whether setting a feature to a specific value is supported.
- * <br>The feature name has the same form as a DOM hasFeature string.
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @param featName The feature name, which is a DOM has-feature style string.
- * @param state The requested state of the feature (<code>true</code> or
- * <code>false</code>).
- * @return <code>true</code> if the feature could be successfully set to
- * the specified value, or <code>false</code> if the feature is not
- * recognized or the requested value is not supported. The value of
- * the feature itself is not changed.
- * @since DOM Level 3
- */
- virtual bool canSetFeature(const XMLCh* const featName
- , bool state) const = 0;
- /**
- * Set the state of a feature.
- * <br>The feature name has the same form as a DOM hasFeature string.
- * <br>It is possible for a <code>DOMWriter</code> to recognize a feature
- * name but to be unable to set its value.
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @param featName The feature name.
- * @param state The requested state of the feature (<code>true</code> or
- * <code>false</code>).
- * @exception DOMException
- * Raise a NOT_SUPPORTED_ERR exception when the <code>DOMWriter</code>
- * recognizes the feature name but cannot set the requested value.
- * <br>Raise a NOT_FOUND_ERR When the <code>DOMWriter</code> does not
- * recognize the feature name.
- * @see getFeature
- * @since DOM Level 3
- */
- virtual void setFeature(const XMLCh* const featName
- , bool state) = 0;
-
- /**
- * Look up the value of a feature.
- * <br>The feature name has the same form as a DOM hasFeature string
- * @param featName The feature name, which is a string with DOM has-feature
- * syntax.
- * @return The current state of the feature (<code>true</code> or
- * <code>false</code>).
- * @exception DOMException
- * Raise a NOT_FOUND_ERR When the <code>DOMWriter</code> does not
- * recognize the feature name.
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @see setFeature
- * @since DOM Level 3
- */
- virtual bool getFeature(const XMLCh* const featName) const = 0;
+ * The DOMConfiguration object used by the LSSerializer when serializing a DOM node.
+ *
+ * In addition to the parameters recognized in on the <code>DOMConfiguration</code>
+ * interface defined in [DOM Level 3 Core], the <code>DOMConfiguration</code> objects
+ * for <code>DOMLSSerializer</code> add or modify the following parameters:
+ *
+ * "canonical-form"
+ * true [optional]
+ * Writes the document according to the rules specified in [Canonical XML]. In addition to
+ * the behavior described in "canonical-form" [DOM Level 3 Core], setting this parameter to
+ * true will set the parameters "format-pretty-print", "discard-default-content", and
+ * "xml-declaration", to false. Setting one of those parameters to true will set this
+ * parameter to false. Serializing an XML 1.1 document when "canonical-form" is true will
+ * generate a fatal error.
+ * false [required] (default)
+ * Do not canonicalize the output.
+ *
+ * "discard-default-content"
+ * true [required] (default)
+ * Use the DOMAttr::getSpecified attribute to decide what attributes should be discarded.
+ * Note that some implementations might use whatever information available to the implementation
+ * (i.e. XML schema, DTD, the DOMAttr::getSpecified attribute, and so on) to determine what
+ * attributes and content to discard if this parameter is set to true.
+ * false [required]
+ * Keep all attributes and all content.
+ *
+ * "format-pretty-print"
+ * true [optional]
+ * Formatting the output by adding whitespace to produce a pretty-printed, indented,
+ * human-readable form. The exact form of the transformations is not specified by this specification.
+ * Pretty-printing changes the content of the document and may affect the validity of the document,
+ * validating implementations should preserve validity.
+ * false [required] (default)
+ * Don't pretty-print the result.
+ *
+ * "ignore-unknown-character-denormalizations"
+ * true [required] (default)
+ * If, while verifying full normalization when [XML 1.1] is supported, a character is encountered
+ * for which the normalization properties cannot be determined, then raise a "unknown-character-denormalization"
+ * warning (instead of raising an error, if this parameter is not set) and ignore any possible
+ * denormalizations caused by these characters.
+ * false [optional]
+ * Report a fatal error if a character is encountered for which the processor cannot determine the
+ * normalization properties.
+ *
+ * "normalize-characters"
+ * This parameter is equivalent to the one defined by <code>DOMConfiguration</code> in [DOM Level 3 Core].
+ * Unlike in the Core, the default value for this parameter is true. While DOM implementations are not
+ * required to support fully normalizing the characters in the document according to appendix E of [XML 1.1],
+ * this parameter must be activated by default if supported.
+ *
+ * "xml-declaration"
+ * true [required] (default)
+ * If a DOMDocument, DOMElement, or DOMEntity node is serialized, the XML declaration, or text declaration,
+ * should be included. The version (DOMDocument::xmlVersion if the document is a Level 3 document and the
+ * version is non-null, otherwise use the value "1.0"), and the output encoding (see DOMLSSerializer::write
+ * for details on how to find the output encoding) are specified in the serialized XML declaration.
+ * false [required]
+ * Do not serialize the XML and text declarations. Report a "xml-declaration-needed" warning if this will
+ * cause problems (i.e. the serialized data is of an XML version other than [XML 1.0], or an encoding would
+ * be needed to be able to re-parse the serialized data).
+ *
+ * "error-handler"
+ * Contains a DOMErrorHandler object. If an error is encountered in the document, the implementation will call back
+ * the DOMErrorHandler registered using this parameter. The implementation may provide a default DOMErrorHandler
+ * object. When called, DOMError::relatedData will contain the closest node to where the error occurred.
+ * If the implementation is unable to determine the node where the error occurs, DOMError::relatedData will contain
+ * the DOMDocument node. Mutations to the document from within an error handler will result in implementation
+ * dependent behavior.
+ *
+ * @return The pointer to the configuration object.
+ * @since DOM Level 3
+ */
+ virtual DOMConfiguration* getDomConfig() = 0;
// -----------------------------------------------------------------------
// Setter methods
@@ -389,8 +409,6 @@
* </dl>
* <br>The default value for this attribute is <code>null</code>.
*
- * <p><b>"Experimental - subject to change"</b></p>
- *
* @param newLine The end-of-line sequence of characters to be used.
* @see getNewLine
* @since DOM Level 3
@@ -398,33 +416,16 @@
virtual void setNewLine(const XMLCh* const newLine) = 0;
/**
- * The error handler that will receive error notifications during
- * serialization. The node where the error occured is passed to this
- * error handler, any modification to nodes from within an error
- * callback should be avoided since this will result in undefined,
- * implementation dependent behavior.
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @param errorHandler The error handler to be used.
- * @see getErrorHandler
- * @since DOM Level 3
- */
- virtual void setErrorHandler(DOMErrorHandler *errorHandler) = 0;
-
- /**
* When the application provides a filter, the serializer will call out
* to the filter before serializing each Node. Attribute nodes are never
* passed to the filter. The filter implementation can choose to remove
* the node from the stream or to terminate the serialization early.
*
- * <p><b>"Experimental - subject to change"</b></p>
- *
* @param filter The writer filter to be used.
* @see getFilter
* @since DOM Level 3
*/
- virtual void setFilter(DOMWriterFilter *filter) = 0;
+ virtual void setFilter(DOMLSSerializerFilter *filter) = 0;
// -----------------------------------------------------------------------
// Getter methods
@@ -453,45 +454,29 @@
virtual const XMLCh* getNewLine() const = 0;
/**
- * Return the error handler that will receive error notifications during
- * serialization.
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @return The error handler to be used.
- * @see setErrorHandler
- * @since DOM Level 3
- */
- virtual DOMErrorHandler* getErrorHandler() const = 0;
-
- /**
* Return the WriterFilter used.
*
- * <p><b>"Experimental - subject to change"</b></p>
- *
* @return The writer filter used.
* @see setFilter
* @since DOM Level 3
*/
- virtual DOMWriterFilter* getFilter() const = 0;
+ virtual DOMLSSerializerFilter* getFilter() const = 0;
// -----------------------------------------------------------------------
// Write methods
// -----------------------------------------------------------------------
/**
* Write out the specified node as described above in the description of
- * <code>DOMWriter</code>. Writing a Document or Entity node produces a
+ * <code>DOMLSSerializer</code>. Writing a Document or Entity node produces a
* serialized form that is well formed XML. Writing other node types
* produces a fragment of text in a form that is not fully defined by
* this document, but that should be useful to a human for debugging or
* diagnostic purposes.
*
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @param destination The destination for the data to be written.
* @param nodeToWrite The <code>Document</code> or <code>Entity</code> node to
* be written. For other node types, something sensible should be
* written, but the exact serialized form is not specified.
+ * @param destination The destination for the data to be written.
* @return Returns <code>true</code> if <code>node</code> was
* successfully serialized and <code>false</code> in case a failure
* occured and the failure wasn't canceled by the error handler.
@@ -501,28 +486,49 @@
* underlying system exception.
* @since DOM Level 3
*/
- virtual bool writeNode(XMLFormatTarget* const destination
- , const DOMNode &nodeToWrite) = 0;
+ virtual bool write(const DOMNode* nodeToWrite,
+ XMLFormatTarget* const destination) = 0;
/**
+ * Write out the specified node as described above in the description of
+ * <code>DOMLSSerializer</code>. Writing a Document or Entity node produces a
+ * serialized form that is well formed XML. Writing other node types
+ * produces a fragment of text in a form that is not fully defined by
+ * this document, but that should be useful to a human for debugging or
+ * diagnostic purposes.
+ *
+ * @param nodeToWrite The <code>Document</code> or <code>Entity</code> node to
+ * be written. For other node types, something sensible should be
+ * written, but the exact serialized form is not specified.
+ * @param uri The destination for the data to be written.
+ * @return Returns <code>true</code> if <code>node</code> was
+ * successfully serialized and <code>false</code> in case a failure
+ * occured and the failure wasn't canceled by the error handler.
+ * @exception DOMSystemException
+ * This exception will be raised in response to any sort of IO or system
+ * error that occurs while writing to the destination. It may wrap an
+ * underlying system exception.
+ * @since DOM Level 3
+ */
+ virtual bool writeToURI(const DOMNode* nodeToWrite,
+ const XMLCh* uri) = 0;
+ /**
* Serialize the specified node as described above in the description of
- * <code>DOMWriter</code>. The result of serializing the node is
+ * <code>DOMLSSerializer</code>. The result of serializing the node is
* returned as a string. Writing a Document or Entity node produces a
* serialized form that is well formed XML. Writing other node types
* produces a fragment of text in a form that is not fully defined by
* this document, but that should be useful to a human for debugging or
* diagnostic purposes.
*
- * <p><b>"Experimental - subject to change"</b></p>
- *
* @param nodeToWrite The node to be written.
* @return Returns the serialized data, or <code>null</code> in case a
* failure occured and the failure wasn't canceled by the error
* handler. The returned string is always in UTF-16.
- * The encoding information available in DOMWriter is ignored in writeToString().
+ * The encoding information available in DOMLSSerializer is ignored in writeToString().
* @since DOM Level 3
*/
- virtual XMLCh* writeToString(const DOMNode &nodeToWrite) = 0;
+ virtual XMLCh* writeToString(const DOMNode* nodeToWrite) = 0;
//@}
Copied: xerces/c/trunk/src/xercesc/dom/DOMLSSerializerFilter.hpp (from r201963, xerces/c/trunk/src/xercesc/dom/DOMWriterFilter.hpp)
URL: http://svn.apache.org/viewcvs/xerces/c/trunk/src/xercesc/dom/DOMLSSerializerFilter.hpp?p2=xerces/c/trunk/src/xercesc/dom/DOMLSSerializerFilter.hpp&p1=xerces/c/trunk/src/xercesc/dom/DOMWriterFilter.hpp&r1=201963&r2=224543&rev=224543&view=diff
==============================================================================
--- xerces/c/trunk/src/xercesc/dom/DOMWriterFilter.hpp (original)
+++ xerces/c/trunk/src/xercesc/dom/DOMLSSerializerFilter.hpp Sat Jul 23 14:11:41 2005
@@ -1,5 +1,5 @@
-#ifndef DOMWriterFilter_HEADER_GUARD_
-#define DOMWriterFilter_HEADER_GUARD_
+#ifndef DOMLSSerializerFilter_HEADER_GUARD_
+#define DOMLSSerializerFilter_HEADER_GUARD_
/*
* Copyright 2002,2004 The Apache Software Foundation.
@@ -23,12 +23,12 @@
/**
*
- * DOMWriterFilter.hpp: interface for the DOMWriterFilter class.
+ * DOMLSSerializerFilter.hpp: interface for the DOMLSSerializerFilter class.
*
- * DOMWriterFilter provide applications the ability to examine nodes
+ * DOMLSSerializerFilter provide applications the ability to examine nodes
* as they are being serialized.
*
- * DOMWriterFilter lets the application decide what nodes should be
+ * DOMLSSerializerFilter lets the application decide what nodes should be
* serialized or not.
*
* The DOMDocument, DOMDocumentType, DOMNotation, and DOMEntity nodes are not passed
@@ -43,14 +43,14 @@
XERCES_CPP_NAMESPACE_BEGIN
-class CDOM_EXPORT DOMWriterFilter : public DOMNodeFilter {
+class CDOM_EXPORT DOMLSSerializerFilter : public DOMNodeFilter {
protected:
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
/** @name Hidden constructors */
//@{
- DOMWriterFilter() {};
+ DOMLSSerializerFilter() {};
//@}
private:
@@ -59,8 +59,8 @@
// -----------------------------------------------------------------------
/** @name Unimplemented constructors and operators */
//@{
- DOMWriterFilter(const DOMWriterFilter &);
- DOMWriterFilter & operator = (const DOMWriterFilter &);
+ DOMLSSerializerFilter(const DOMLSSerializerFilter &);
+ DOMLSSerializerFilter & operator = (const DOMLSSerializerFilter &);
//@}
@@ -74,11 +74,11 @@
* Destructor
*
*/
- virtual ~DOMWriterFilter() {};
+ virtual ~DOMLSSerializerFilter() {};
//@}
// -----------------------------------------------------------------------
- // Virtual DOMWriterFilter interface
+ // Virtual DOMLSSerializerFilter interface
// -----------------------------------------------------------------------
/** @name Functions introduced in DOM Level 3 */
//@{
@@ -89,30 +89,15 @@
virtual short acceptNode(const DOMNode* node) const = 0;
/**
- * Tells the DOMWriter what types of nodes to show to the filter.
+ * Tells the DOMLSSerializer what types of nodes to show to the filter.
* See <code>DOMNodeFilter</code> for definition of the constants.
* The constant SHOW_ATTRIBUTE is meaningless here, attribute nodes will
- * never be passed to a DOMWriterFilter.
- *
- * <p><b>"Experimental - subject to change"</b></p>
+ * never be passed to a DOMLSSerializerFilter.
*
* @return The constants of what types of nodes to show.
- * @see setWhatToShow
* @since DOM Level 3
*/
virtual unsigned long getWhatToShow() const =0;
-
- /**
- * Set what types of nodes are to be presented.
- * See <code>DOMNodeFilter</code> for definition of the constants.
- *
- * <p><b>"Experimental - subject to change"</b></p>
- *
- * @param toShow The constants of what types of nodes to show.
- * @see getWhatToShow
- * @since DOM Level 3
- */
- virtual void setWhatToShow(unsigned long toShow) =0;
//@}
private:
@@ -123,7 +108,7 @@
// fWhatToShow
//
// The whatToShow mask.
- // Tells the DOMWriter what types of nodes to show to the filter.
+ // Tells the DOMLSSerializer what types of nodes to show to the filter.
// See NodeFilter for definition of the constants.
// The constants
// SHOW_ATTRIBUTE,
@@ -133,7 +118,7 @@
// SHOW_DOCUMENT_FRAGMENT are meaningless here,
// Entity nodes are not passed to the filter.
//
- // Those nodes will never be passed to a DOMWriterFilter.
+ // Those nodes will never be passed to a DOMLSSerializerFilter.
//
// Derived class shall add this data member:
//
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xerces.apache.org
For additional commands, e-mail: commits-help@xerces.apache.org