Context Navigation

DOMConfiguration.hpp @ 358

Revision 358, 21.4 KB checked in by bittner, 19 years ago (diff)
xerces added

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

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: NonGTP/Xerces/xerces/include/xercesc/dom/DOMConfiguration.hpp @ 358

Download in other formats: