/*

* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

/*

 * 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 <xercesc/util/XMLString.hpp>

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 

     * <code>DOMUserData</code>, 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 <code>DOMErrorHandler</code>

     * @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

 */