source: icXML/icXML-devel/src/xercesc/dom/DOMConfiguration.hpp @ 2722

Last change on this file since 2722 was 2722, checked in by cameron, 6 years ago

Original Xerces files with import mods for icxercesc

File size: 18.5 KB
Line 
1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *      http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18#if !defined(XERCESC_INCLUDE_GUARD_DOMCONFIGURATION_HPP)
19#define XERCESC_INCLUDE_GUARD_DOMCONFIGURATION_HPP
20
21//------------------------------------------------------------------------------------
22//  Includes
23//------------------------------------------------------------------------------------
24
25#include <icxercesc/util/XMLString.hpp>
26#include <xercesc/util/RefVectorOf.hpp>
27#include <xercesc/dom/DOMStringList.hpp>
28
29XERCES_CPP_NAMESPACE_BEGIN
30
31/**
32 *   The DOMConfiguration interface represents the configuration of
33 *   a document  and  maintains  a  table of recognized parameters.
34 *   Using  the   configuration,   it   is   possible   to   change
35 *   Document.normalizeDocument  behavior,  such  as replacing
36 *   CDATASection   nodes   with   Text  nodes  or
37 *   specifying  the  type  of the schema that must be used when the
38 *   validation of the Document is requested. DOMConfiguration
39 *   objects  are  also used in [DOM Level 3 Load and Save] in
40 *   the DOMLSParser and DOMLSSerializer interfaces.
41 *
42 *   The  DOMConfiguration  distinguish  two  types  of  parameters:
43 *   boolean     (boolean    parameters)    and    DOMUserData
44 *   (parameters). The names used by the DOMConfiguration object are
45 *   defined  throughout  the  DOM Level 3 specifications. Names are
46 *   case-insensitive.   To   avoid   possible   conflicts,   as  a
47 *   convention,   names   referring   to   boolean  parameters  and
48 *   parameters defined outside the DOM specification should be made
49 *   unique.  Names  are  recommended  to  follow the XML name
50 *   production   rule   but   it   is   not  enforced  by  the  DOM
51 *   implementation.  DOM  Level 3 Core Implementations are required
52 *   to  recognize  all boolean parameters and parameters defined in
53 *   this  specification.  Each boolean parameter state or parameter
54 *   value may then be supported or not by the implementation. Refer
55 *   to  their  definition  to  know  if  a state or a value must be
56 *   supported or not.
57 *
58 *   Note: Parameters are similar to features and properties used in
59 *   SAX2 [SAX].
60 *
61 *   The following list of parameters defined in the DOM:
62 *
63 * "error-handler"
64 *         [required]
65 *         A   DOMErrorHandler   object.   If   an   error  is
66 *         encountered in the document, the implementation will call
67 *         back  the  DOMErrorHandler  registered  using  this
68 *         parameter.
69 *         When  called, DOMError.relatedData will contain the
70 *         closest   node   to  where  the  error  occured.  If  the
71 *         implementation  is unable to determine the node where the
72 *         error occurs, DOMError.relatedData will contain the
73 *         Document  node.  Mutations  to  the  document  from
74 *         within  an  error  handler  will result in implementation
75 *         dependent behaviour.
76 *
77 * "schema-type"
78 *         [optional]
79 *         A  DOMString  object containing an absolute URI and
80 *         representing  the  type  of  the  schema language used to
81 *         validate   a  document  against.  Note  that  no  lexical
82 *         checking is done on the absolute URI.
83 *         If  this  parameter  is  not  set, a default value may be
84 *         provided  by  the  implementation,  based  on  the schema
85 *         languages  supported  and  on the schema language used at
86 *         load time.
87 *
88 *         Note:   For   XML   Schema  [XML  Schema  Part  1],
89 *         applications must use the value
90 *         "http://www.w3.org/2001/XMLSchema".     For    XML    DTD
91 *         [XML   1.0],   applications   must  use  the  value
92 *         "http://www.w3.org/TR/REC-xml".  Other  schema  languages
93 *         are  outside  the  scope  of the W3C and therefore should
94 *         recommend an absolute URI in order to use this method.
95 *
96 * "schema-location"
97 *         [optional]
98 *         A  DOMString  object  containing  a  list  of URIs,
99 *         separated   by  white  spaces  (characters  matching  the
100 *         nonterminal  production  S  defined  in section 2.3
101 *         [XML  1.0]),  that  represents  the schemas against
102 *         which  validation  should  occur.  The  types  of schemas
103 *         referenced  in  this  list  must match the type specified
104 *         with   schema-type,   otherwise   the   behaviour  of  an
105 *         implementation  is  undefined.  If the schema type is XML
106 *         Schema  [XML  Schema  Part  1], only one of the XML
107 *         Schemas in the list can be with no namespace.
108 *         If  validation  occurs  against a namespace aware schema,
109 *         i.e.  XML  Schema,  and  the  targetNamespace of a schema
110 *         (specified    using    this    property)    matches   the
111 *         targetNamespace  of  a  schema  occurring in the instance
112 *         document,  i.e  in  schemaLocation  attribute, the schema
113 *         specified  by  the  user using this property will be used
114 *         (i.e.,  in XML Schema the schemaLocation attribute in the
115 *         instance  document  or  on  the  import  element  will be
116 *         effectively ignored).
117 *
118 *         Note:  It is illegal to set the schema-location parameter
119 *         if  the  schema-type  parameter  value  is not set. It is
120 *         strongly  recommended that DOMInputSource.baseURI will be
121 *         set,  so  that an implementation can successfully resolve
122 *         any external entities referenced.
123 *
124 *   The  following list of boolean parameters (features) defined in
125 *   the DOM:
126 *
127 * "canonical-form"
128 *
129 *       true
130 *               [optional]
131 *               Canonicalize  the  document  according to the rules
132 *               specified  in [Canonical XML]. Note that this
133 *               is  limited  to what can be represented in the DOM.
134 *               In particular, there is no way to specify the order
135 *               of the attributes in the DOM.
136 *
137 *       false
138 *               [required] (default)
139 *               Do not canonicalize the document.
140 *
141 * "cdata-sections"
142 *
143 *       true
144 *               [required] (default)
145 *               Keep CDATASection nodes in the document.
146 *
147 *       false
148 *               [required]
149 *               Transform  CDATASection nodes in the document
150 *               into  Text  nodes. The new Text node is
151 *               then combined with any adjacent Text node.
152 *
153 * "comments"
154 *
155 *       true
156 *               [required] (default)
157 *               Keep Comment nodes in the document.
158 *
159 *       false
160 *               [required]
161 *               Discard Comment nodes in the Document.
162 *
163 * "datatype-normalization"
164 *
165 *       true
166 *               [required]
167 *               Exposed normalized values in the tree.
168 *
169 *       false
170 *               [required] (default)
171 *               Do not perform normalization on the tree.
172 *
173 * "discard-default-content"
174 *
175 *       true
176 *               [required] (default)
177 *               Use   whatever   information   available   to   the
178 *               implementation (i.e. XML schema, DTD, the specified
179 *               flag on Attr nodes, and so on) to decide what
180 *               attributes  and content should be discarded or not.
181 *               Note that the specified flag on Attr nodes in
182 *               itself  is not always reliable, it is only reliable
183 *               when  it  is set to false since the only case where
184 *               it  can  be  set  to  false is if the attribute was
185 *               created  by the implementation. The default content
186 *               won't be removed if an implementation does not have
187 *               any information available.
188 *
189 *       false
190 *               [required]
191 *               Keep all attributes and all content.
192 *
193 * "entities"
194 *
195 *       true
196 *               [required]
197 *               Keep  EntityReference  and Entity nodes
198 *               in the document.
199 *
200 *       false
201 *               [required] (default)
202 *               Remove  all  EntityReference and Entity
203 *               nodes   from   the  document,  putting  the  entity
204 *               expansions  directly  in  their  place.  Text
205 *               nodes     are     into    "normal"    form.    Only
206 *               EntityReference nodes to non-defined entities
207 *               are kept in the document.
208 *
209 * "infoset"
210 *
211 *       true
212 *               [required]
213 *               Only  keep  in the document the information defined
214 *               in  the  XML Information Set [XML Information
215 *               set].
216 *               This   forces  the  following  features  to  false:
217 *               namespace-declarations,         validate-if-schema,
218 *               entities, datatype-normalization, cdata-sections.
219 *               This   forces   the  following  features  to  true:
220 *               whitespace-in-element-content,            comments,
221 *               namespaces.
222 *               Other  features  are  not  changed unless explicitly
223 *               specified in the description of the features.
224 *               Note  that  querying  this  feature with getFeature
225 *               returns   true  only  if  the  individual  features
226 *               specified above are appropriately set.
227 *
228 *       false
229 *               Setting infoset to false has no effect.
230 *
231 * "namespaces"
232 *
233 *       true
234 *               [required] (default)
235 *               Perform  the  namespace  processing  as  defined in
236 *               [XML Namespaces].
237 *
238 *       false
239 *               [optional]
240 *               Do not perform the namespace processing.
241 *
242 * "namespace-declarations"
243 *
244 *       true
245 *               [required] (default)
246 *               Include namespace declaration attributes, specified
247 *               or  defaulted  from  the  schema or the DTD, in the
248 *               document.  See  also  the  section  Declaring
249 *               Namespaces in [XML Namespaces].
250 *
251 *       false
252 *               [required]
253 *               Discard  all  namespace declaration attributes. The
254 *               Namespace   prefixes  are  retained  even  if  this
255 *               feature is set to false.
256 *
257 * "normalize-characters"
258 *
259 *       true
260 *               [optional]
261 *               Perform   the   W3C   Text   Normalization  of  the
262 *               characters [CharModel] in the document.
263 *
264 *       false
265 *               [required] (default)
266 *               Do not perform character normalization.
267 *
268 * "split-cdata-sections"
269 *
270 *       true
271 *               [required] (default)
272 *               Split  CDATA  sections containing the CDATA section
273 *               termination  marker  ']]>'. When a CDATA section is
274 *               split a warning is issued.
275 *
276 *       false
277 *               [required]
278 *               Signal an error if a CDATASection contains an
279 *               unrepresentable character.
280 *
281 * "validate"
282 *
283 *       true
284 *               [optional]
285 *               Require  the  validation against a schema (i.e. XML
286 *               schema,  DTD,  any  other type or representation of
287 *               schema)  of  the document as it is being normalized
288 *               as defined by [XML 1.0]. If validation errors
289 *               are  found,  or  no  schema  was  found,  the error
290 *               handler  is  notified.  Note  also  that normalized
291 *               values  will  not  be exposed to the schema in used
292 *               unless the feature datatype-normalization is true.
293 *
294 *               Note:  validate-if-schema and validate are mutually
295 *               exclusive, setting one of them to true will set the
296 *               other one to false.
297 *
298 *       false
299 *               [required] (default)
300 *               Only  XML  1.0  non-validating  processing  must be
301 *               done.  Note  that  validation might still happen if
302 *               validate-if-schema is true.
303 *
304 * "validate-if-schema"
305 *
306 *       true
307 *               [optional]
308 *               Enable  validation  only  if  a declaration for the
309 *               document  element  can  be  found (independently of
310 *               where  it  is  found,  i.e. XML schema, DTD, or any
311 *               other   type   or  representation  of  schema).  If
312 *               validation  errors  are found, the error handler is
313 *               notified. Note also that normalized values will not
314 *               be exposed to the schema in used unless the feature
315 *               datatype-normalization is true.
316 *
317 *               Note:  validate-if-schema and validate are mutually
318 *               exclusive, setting one of them to true will set the
319 *               other one to false.
320 *
321 *       false
322 *               [required] (default)
323 *               No  validation  should be performed if the document
324 *               has  a  schema.  Note  that  validation  must still
325 *               happen if validate is true.
326 *
327 * "element-content-whitespace"
328 *
329 *       true
330 *               [required] (default)
331 *               Keep all white spaces in the document.
332 *
333 *       false
334 *               [optional]
335 *               Discard   white  space  in  element  content  while
336 *               normalizing.  The implementation is expected to use
337 *               the isWhitespaceInElementContent flag on Text
338 *               nodes to determine if a text node should be written
339 *               out or not.
340 *
341 *   The  resolutions  of  entities  is done using Document.baseURI.
342 *   However,  when  the  features "LS-Load" or "LS-Save" defined in
343 *   [DOM  Level  3  Load  and  Save] are supported by the DOM
344 *   implementation,  the  parameter  "entity-resolver"  can also be
345 *   used  on  DOMConfiguration  objects  attached to Document
346 *   nodes. If this parameter is set,
347 *   Document.normalizeDocument   will   invoke   the   entity
348 *   resolver instead of using Document.baseURI.
349 */
350class CDOM_EXPORT DOMConfiguration
351{
352protected:
353    //-----------------------------------------------------------------------------------
354    //  Constructor
355    //-----------------------------------------------------------------------------------
356    /** @name Hidden constructors */
357    //@{
358    DOMConfiguration() {};
359    //@}
360
361private:
362    // -----------------------------------------------------------------------
363    // Unimplemented constructors and operators
364    // -----------------------------------------------------------------------
365    /** @name Unimplemented constructors and operators */
366    //@{
367    DOMConfiguration(const DOMConfiguration &);
368    DOMConfiguration & operator = (const DOMConfiguration &);
369    //@}
370
371public:
372
373    // -----------------------------------------------------------------------
374    //  Setter methods
375    // -----------------------------------------------------------------------
376   
377    /** Set the value of a parameter.
378     * @param name The name of the parameter to set.
379     * @param value The new value or null if the user wishes to unset the
380     * parameter. While the type of the value parameter is defined as
381     * <code>DOMUserData</code>, the object type must match the type defined
382     * by the definition of the parameter. For example, if the parameter is
383     * "error-handler", the value must be of type <code>DOMErrorHandler</code>
384     * @exception DOMException (NOT_SUPPORTED_ERR) Raised when the
385     * parameter name is recognized but the requested value cannot be set.
386     * @exception DOMException (NOT_FOUND_ERR) Raised when the
387     * parameter name is not recognized.
388     * @since DOM level 3
389     **/
390    virtual void setParameter(const XMLCh* name, const void* value) = 0;
391    virtual void setParameter(const XMLCh* name, bool value) = 0;
392
393    // -----------------------------------------------------------------------
394    //  Getter methods
395    // -----------------------------------------------------------------------
396    /** Return the value of a parameter if known.
397     * @param name The name of the parameter.
398     * @return The current object associated with the specified parameter or
399     * null if no object has been associated or if the parameter is not
400     * supported.
401     * @exception DOMException (NOT_FOUND_ERR) Raised when the i
402     * boolean parameter
403     * name is not recognized.
404     * @since DOM level 3
405     **/   
406    virtual const void* getParameter(const XMLCh* name) const = 0;
407
408                                       
409    // -----------------------------------------------------------------------
410    //  Query methods
411    // -----------------------------------------------------------------------
412
413    /** Check if setting a parameter to a specific value is supported.
414     * @param name The name of the parameter to check.
415     * @param value An object. if null, the returned value is true.
416     * @return true if the parameter could be successfully set to the specified
417     * value, or false if the parameter is not recognized or the requested value
418     * is not supported. This does not change the current value of the parameter
419     * itself.
420     * @since DOM level 3
421     **/
422    virtual bool canSetParameter(const XMLCh* name, const void* value) const = 0;
423    virtual bool canSetParameter(const XMLCh* name, bool value) const = 0;
424
425    /**
426     * The list of the parameters supported by this DOMConfiguration object and
427     * for which at least one value can be set by the application.
428     * Note that this list can also contain parameter names defined outside this specification.
429     *
430     * @return The list of parameters that can be used with setParameter/getParameter
431     * @since DOM level 3
432     **/
433    virtual const DOMStringList* getParameterNames() const = 0;
434
435    // -----------------------------------------------------------------------
436    //  All constructors are hidden, just the destructor is available
437    // -----------------------------------------------------------------------
438    /** @name Destructor */
439    //@{
440    /**
441     * Destructor
442     *
443     */
444    virtual ~DOMConfiguration() {};
445    //@}
446};
447       
448XERCES_CPP_NAMESPACE_END
449
450#endif
451
452/**
453 * End of file DOMConfiguration.hpp
454 */
Note: See TracBrowser for help on using the repository browser.