Context Navigation

DOMConfiguration.hpp @ 119

Revision 111, 21.0 kB (checked in by mido, 17 years ago)
pridana knihovna XSD (a jeji chlebodarkyne XERCES), v ramci Win32 zprovoznen priklad tests/test_xsd_hello.cxx

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

Note: See TracBrowser for help on using the browser.

Context Navigation

root/win32/xerces-c_2_8_0-x86/include/xercesc/dom/DOMConfiguration.hpp @ 119

Download in other formats: