/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You 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. */ #if !defined(DOMCONFIGURATION_HPP) #define DOMCONFIGURATION_HPP //------------------------------------------------------------------------------------ // Includes //------------------------------------------------------------------------------------ #include XERCES_CPP_NAMESPACE_BEGIN /** * The DOMConfiguration interface represents the configuration of * a document and maintains a table of recognized parameters. * using the configuration, it is possible to change * Document.normalizeDocument behavior, such as replacing * CDATASection nodes with Text nodes or * specifying the type of the schema that must be used when the * validation of the Document is requested. DOMConfiguration * objects are also used in [DOM Level 3 Load and Save] in * the DOMBuilder and DOMWriter interfaces. * * The DOMConfiguration distinguish two types of parameters: * boolean (boolean parameters) and DOMUserData * (parameters). The names used by the DOMConfiguration object are * defined throughout the DOM Level 3 specifications. Names are * case-insensitives. To avoid possible conflicts, as a * convention, names referring to boolean parameters and * parameters defined outside the DOM specification should be made * unique. Names are recommended to follow the XML name * production rule but it is not enforced by the DOM * implementation. DOM Level 3 Core Implementations are required * to recognize all boolean parameters and parameters defined in * this specification. Each boolean parameter state or parameter * value may then be supported or not by the implementation. Refer * to their definition to know if a state or a value must be * supported or not. * * Note: Parameters are similar to features and properties used in * SAX2 [SAX]. * * Issue DOMConfiguration-1: * Can we rename boolean parameters to "flags"? * * Issue DOMConfiguration-2: * Are boolean parameters and parameters within the same * scope for uniqueness? Which exception should be raised by * setBooleanParameter("error-handler", true)? * * The following list of parameters defined in the DOM: * * "error-handler" * [required] * A DOMErrorHandler object. If an error is * encountered in the document, the implementation will call * back the DOMErrorHandler registered using this * parameter. * When called, DOMError.relatedData will contain the * closest node to where the error occured. If the * implementation is unable to determine the node where the * error occurs, DOMError.relatedData will contain the * Document node. Mutations to the document from * within an error handler will result in implementation * dependent behaviour. * * Issue DOMConfiguration-4: * Should we say non "readonly" operations are * implementation dependent instead? * Resolution: Removed: "or re-invoking a validation * operation". * * "schema-type" * [optional] * A DOMString object containing an absolute URI and * representing the type of the schema language used to * validate a document against. Note that no lexical * checking is done on the absolute URI. * If this parameter is not set, a default value may be * provided by the implementation, based on the schema * languages supported and on the schema language used at * load time. * * Note: For XML Schema [XML Schema Part 1], * applications must use the value * "http://www.w3.org/2001/XMLSchema". For XML DTD * [XML 1.0], applications must use the value * "http://www.w3.org/TR/REC-xml". Other schema languages * are outside the scope of the W3C and therefore should * recommend an absolute URI in order to use this method. * * "schema-location" * [optional] * A DOMString object containing a list of URIs, * separated by white spaces (characters matching the * nonterminal production S defined in section 2.3 * [XML 1.0]), that represents the schemas against * which validation should occur. The types of schemas * referenced in this list must match the type specified * with schema-type, otherwise the behaviour of an * implementation is undefined. If the schema type is XML * Schema [XML Schema Part 1], only one of the XML * Schemas in the list can be with no namespace. * If validation occurs against a namespace aware schema, * i.e. XML Schema, and the targetNamespace of a schema * (specified using this property) matches the * targetNamespace of a schema occurring in the instance * document, i.e in schemaLocation attribute, the schema * specified by the user using this property will be used * (i.e., in XML Schema the schemaLocation attribute in the * instance document or on the import element will be * effectively ignored). * * Note: It is illegal to set the schema-location parameter * if the schema-type parameter value is not set. It is * strongly recommended that DOMInputSource.baseURI will be * set, so that an implementation can successfully resolve * any external entities referenced. * * The following list of boolean parameters (features) defined in * the DOM: * * "canonical-form" * * true * [optional] * Canonicalize the document according to the rules * specified in [Canonical XML]. Note that this * is limited to what can be represented in the DOM. * In particular, there is no way to specify the order * of the attributes in the DOM. * * Issue normalizationFeature-14: * What happen to other features? are they * ignored? if yes, how do you know if a feature * is ignored? * * false * [required] (default) * Do not canonicalize the document. * * "cdata-sections" * * true * [required] (default) * Keep CDATASection nodes in the document. * * Issue normalizationFeature-11: * Name does not work really well in this case. * ALH suggests renaming this to * "cdata-sections". It works for both load and * save. * Resolution: Renamed as suggested. (Telcon 27 * Jan 2002). * * false * [required] * Transform CDATASection nodes in the document * into Text nodes. The new Text node is * then combined with any adjacent Text node. * * "comments" * * true * [required] (default) * Keep Comment nodes in the document. * * false * [required] * Discard Comment nodes in the Document. * * "datatype-normalization" * * true * [required] * Exposed normalized values in the tree. * * Issue normalizationFeature-8: * We should define "datatype normalization". * Resolution: DTD normalization always apply * because it's part of XML 1.0. Clarify the * spec. (Telcon 27 Jan 2002). * * false * [required] (default) * Do not perform normalization on the tree. * * "discard-default-content" * * true * [required] (default) * Use whatever information available to the * implementation (i.e. XML schema, DTD, the specified * flag on Attr nodes, and so on) to decide what * attributes and content should be discarded or not. * Note that the specified flag on Attr nodes in * itself is not always reliable, it is only reliable * when it is set to false since the only case where * it can be set to false is if the attribute was * created by the implementation. The default content * won't be removed if an implementation does not have * any information available. * * Issue normalizationFeature-2: * How does exactly work? What's the comment * about level 1 implementations? * Resolution: Remove "Level 1" (Telcon 16 Jan * 2002). * * false * [required] * Keep all attributes and all content. * * "entities" * * true * [required] * Keep EntityReference and Entity nodes * in the document. * * Issue normalizationFeature-9: * How does that interact with * expand-entity-references? ALH suggests * consolidating the two to a single feature * called "entity-references" that is used both * for load and save. * Resolution: Consolidate both features into a * single feature called 'entities'. (Telcon 27 * Jan 2002). * * false * [required] (default) * Remove all EntityReference and Entity * nodes from the document, putting the entity * expansions directly in their place. Text * nodes are into "normal" form. Only * EntityReference nodes to non-defined entities * are kept in the document. * * "infoset" * * true * [required] * Only keep in the document the information defined * in the XML Information Set [XML Information * set]. * This forces the following features to false: * namespace-declarations, validate-if-schema, * entities, datatype-normalization, cdata-sections. * This forces the following features to true: * whitespace-in-element-content, comments, * namespaces. * Other features are not changed unless explicity * specified in the description of the features. * Note that querying this feature with getFeature * returns true only if the individual features * specified above are appropriately set. * * Issue normalizationFeature-12: * Name doesn't work well here. ALH suggests * renaming this to limit-to-infoset or * match-infoset, something like that. * Resolution: Renamed 'infoset' (Telcon 27 Jan * 2002). * * false * Setting infoset to false has no effect. * * Issue normalizationFeature-13: * Shouldn't we change this to setting the * relevant options back to their default value? * Resolution: No, this is more like a * convenience function, it's better to keep it * simple. (F2F 28 Feb 2002). * * "namespaces" * * true * [required] (default) * Perform the namespace processing as defined in * [XML Namespaces]. * * false * [optional] * Do not perform the namespace processing. * * "namespace-declarations" * * true * [required] (default) * Include namespace declaration attributes, specified * or defaulted from the schema or the DTD, in the * document. See also the section Declaring * Namespaces in [XML Namespaces]. * * false * [required] * Discard all namespace declaration attributes. The * Namespace prefixes are retained even if this * feature is set to false. * * "normalize-characters" * * true * [optional] * Perform the W3C Text Normalization of the * characters [CharModel] in the document. * * false * [required] (default) * Do not perform character normalization. * * "split-cdata-sections" * * true * [required] (default) * Split CDATA sections containing the CDATA section * termination marker ']]>'. When a CDATA section is * split a warning is issued. * * false * [required] * Signal an error if a CDATASection contains an * unrepresentable character. * * "validate" * * true * [optional] * Require the validation against a schema (i.e. XML * schema, DTD, any other type or representation of * schema) of the document as it is being normalized * as defined by [XML 1.0]. If validation errors * are found, or no schema was found, the error * handler is notified. Note also that normalized * values will not be exposed to the schema in used * unless the feature datatype-normalization is true. * * Note: validate-if-schema and validate are mutually * exclusive, setting one of them to true will set the * other one to false. * * false * [required] (default) * Only XML 1.0 non-validating processing must be * done. Note that validation might still happen if * validate-if-schema is true. * * "validate-if-schema" * * true * [optional] * Enable validation only if a declaration for the * document element can be found (independently of * where it is found, i.e. XML schema, DTD, or any * other type or representation of schema). If * validation errors are found, the error handler is * notified. Note also that normalized values will not * be exposed to the schema in used unless the feature * datatype-normalization is true. * * Note: validate-if-schema and validate are mutually * exclusive, setting one of them to true will set the * other one to false. * * false * [required] (default) * No validation should be performed if the document * has a schema. Note that validation must still * happen if validate is true. * * "whitespace-in-element-content" * * true * [required] (default) * Keep all white spaces in the document. * * Issue normalizationFeature-15: * How does this feature interact with * "validate" and * Text.isWhitespaceInElementContent. * Resolution: issue no longer relevant (f2f * october 2002). * * false * [optional] * Discard white space in element content while * normalizing. The implementation is expected to use * the isWhitespaceInElementContent flag on Text * nodes to determine if a text node should be written * out or not. * * The resolutions of entities is done using Document.baseURI. * However, when the features "LS-Load" or "LS-Save" defined in * [DOM Level 3 Load and Save] are supported by the DOM * implementation, the parameter "entity-resolver" can also be * used on DOMConfiguration objects attached to Document * nodes. If this parameter is set, * Document.normalizeDocument will invoke the entity * resolver instead of using Document.baseURI. */ class CDOM_EXPORT DOMConfiguration { protected: //----------------------------------------------------------------------------------- // Constructor //----------------------------------------------------------------------------------- /** @name Hidden constructors */ //@{ DOMConfiguration() {}; //@} private: // ----------------------------------------------------------------------- // Unimplemented constructors and operators // ----------------------------------------------------------------------- /** @name Unimplemented constructors and operators */ //@{ DOMConfiguration(const DOMConfiguration &); DOMConfiguration & operator = (const DOMConfiguration &); //@} public: // ----------------------------------------------------------------------- // Setter methods // ----------------------------------------------------------------------- /** Set the value of a parameter. * @param name The name of the parameter to set. * @param value The new value or null if the user wishes to unset the * parameter. While the type of the value parameter is defined as * DOMUserData, the object type must match the type defined * by the definition of the parameter. For example, if the parameter is * "error-handler", the value must be of type DOMErrorHandler * @exception DOMException (NOT_SUPPORTED_ERR) Raised when the * parameter name is recognized but the requested value cannot be set. * @exception DOMException (NOT_FOUND_ERR) Raised when the * parameter name is not recognized. * @since DOM level 3 **/ virtual void setParameter(const XMLCh* name, const void* value) = 0; // ----------------------------------------------------------------------- // Getter methods // ----------------------------------------------------------------------- /** Return the value of a parameter if known. * @param name The name of the parameter. * @return The current object associated with the specified parameter or * null if no object has been associated or if the parameter is not * supported. * @exception DOMException (NOT_FOUND_ERR) Raised when the i * boolean parameter * name is not recognized. * @since DOM level 3 **/ virtual const void* getParameter(const XMLCh* name) const = 0; // ----------------------------------------------------------------------- // Query methods // ----------------------------------------------------------------------- /** Check if setting a parameter to a specific value is supported. * @param name The name of the parameter to check. * @param value An object. if null, the returned value is true. * @return true if the parameter could be successfully set to the specified * value, or false if the parameter is not recognized or the requested value * is not supported. This does not change the current value of the parameter * itself. * @since DOM level 3 **/ virtual bool canSetParameter(const XMLCh* name, const void* value) const = 0; // ----------------------------------------------------------------------- // All constructors are hidden, just the destructor is available // ----------------------------------------------------------------------- /** @name Destructor */ //@{ /** * Destructor * */ virtual ~DOMConfiguration() {}; //@} }; XERCES_CPP_NAMESPACE_END #endif /** * End of file DOMConfiguration.hpp */