1 /* Copyright 2004 The Apache Software Foundation
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16 package org.apache.xmlbeans;
17
18 import org.xml.sax.EntityResolver;
19 import org.xml.sax.XMLReader;
20
21 import java.net.URI;
22 import java.util.HashMap;
23 import java.util.Map;
24 import java.util.Collection;
25 import java.util.Collections;
26 import java.util.Set;
27 import javax.xml.namespace.QName;
28
29 /**
30 * Used to supply options for loading, saving, and compiling, and validating.
31 * <p>
32 * There are two styles for using XmlOptions: multiline setup, and single-line use.
33 * Here are two examples. First, multiline style:
34 * <pre>
35 * XmlOptions opts = new XmlOptions();
36 * opts.setSavePrettyPrint();
37 * opts.setSavePrettyPrintIndent(4);
38 * System.out.println(xobj.xmlText(opts));
39 * </pre>
40 *
41 * The alternative is single-line usage:
42 * <pre>
43 * System.out.println(xobj.xmlText(
44 * new XmlOptions().setSavePrettyPrint().setSavePrettyPrintIndent(4)));
45 * </pre>
46 *
47 * Table showing where each option gets used.
48 * Note that:
49 * <ul>
50 * <li>options available for <code>newInstance</code> methods will also
51 * apply for <code>parse</code> methods</li>
52 * <li>options used for <code>validate</code> methods are also used for
53 * <code>compile</code> methods, since compilation usually implies
54 * validation against Schema for Schemas</li>
55 * </ul>
56 *
57 * <table border="1">
58 * <tr>
59 * <th align="center"><code>newInstance</code> methods</th>
60 * <th align="center"><code>parse</code> methods</th>
61 * <th align="center"><code>validate</code> methods</th>
62 * <th align="center"><code>compile</code> methods</th>
63 * <th align="center"><code>save</code> and <code>xmlText</code>methods</th>
64 * </tr>
65 * <tr>
66 * <td align="center"><code>setDocumentType</code><br/>
67 * <code>setDocumentSourceName</code><br/>
68 * <code>setValidateOnSet</code><br/>
69 * <code>setUnsynchronized</code></td>
70 * <td align="center"><code>setLoad***</code><br/>
71 * <code>setEntityResolver</code></td>
72 * <td align="center"><code>setErrorListener</code><br/>
73 * <code>setValidateTreatLaxAsSkip</code>
74 * <code>setValidateStrict</code></td>
75 * <td align="center"><code>setErrorListener</code><br/>
76 * <code>setCompile***</code><br/>
77 * <code>setEntityResolver</code><br/>
78 * <code>setBaseURI</code><br/>
79 * <code>setGenerateJavaVersion</code></td>
80 * <td align="center"><code>setSave***</code><br/>
81 * <code>setUseDefaultNamespace</code><br/>
82 * <code>setCharacterEncoding</code></td>
83 * </tr>
84 * </table>
85 */
86 public class XmlOptions implements java.io.Serializable
87 {
88 private static final long serialVersionUID = 1L;
89
90 private Map _map = new HashMap();
91
92
93 /**
94 * Construct a new blank XmlOptions.
95 */
96 public XmlOptions ( ) { }
97
98 /**
99 * Construct a new XmlOptions, copying the options.
100 */
101 public XmlOptions (XmlOptions other) {
102 if (other != null) _map.putAll(other._map);
103 }
104
105 //
106 // Handy-dandy helper methods for setting some options
107 //
108
109 /**
110 * This option will cause the saver to save namespace attributes first.
111 *
112 * @see XmlTokenSource#save(java.io.File, XmlOptions)
113 * @see XmlTokenSource#xmlText(XmlOptions)
114 */
115 public XmlOptions setSaveNamespacesFirst() {
116 return set( SAVE_NAMESPACES_FIRST );
117 }
118 /**
119 * This option will cause the saver to reformat white space for easier reading.
120 *
121 * @see XmlTokenSource#save(java.io.File, XmlOptions)
122 * @see XmlTokenSource#xmlText(XmlOptions)
123 */
124 public XmlOptions setSavePrettyPrint() {
125 return set( SAVE_PRETTY_PRINT );
126 }
127
128 /**
129 * When used with <code>setSavePrettyPrint</code> this sets the indent
130 * amount to use.
131 *
132 * @param indent the indent amount to use
133 * @see #setSavePrettyPrint
134 * @see XmlTokenSource#save(java.io.File, XmlOptions)
135 * @see XmlTokenSource#xmlText(XmlOptions)
136 */
137 public XmlOptions setSavePrettyPrintIndent(int indent) {
138 return set( SAVE_PRETTY_PRINT_INDENT, indent );
139 }
140
141 /**
142 * When used with <code>setSavePrettyPrint</code> this sets the offset
143 * amount to use.
144 *
145 * @param offset the offset amount to use
146 * @see #setSavePrettyPrint
147 * @see XmlTokenSource#save(java.io.File, XmlOptions)
148 * @see XmlTokenSource#xmlText(XmlOptions)
149 */
150 public XmlOptions setSavePrettyPrintOffset(int offset) {
151 return set( SAVE_PRETTY_PRINT_OFFSET, offset );
152 }
153
154 /**
155 * When writing a document, this sets the character
156 * encoding to use.
157 *
158 * @param encoding the character encoding
159 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
160 * @see XmlTokenSource#save(java.io.File, XmlOptions)
161 */
162 public XmlOptions setCharacterEncoding(String encoding) {
163 return set( CHARACTER_ENCODING, encoding );
164 }
165
166 /**
167 * When parsing a document, this sets the type of the root
168 * element. If this is set, the parser will not try to guess
169 * the type based on the document's <code>QName</code>.
170 *
171 * @param type The root element's document type.
172 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
173 */
174 public XmlOptions setDocumentType(SchemaType type) {
175 return set( DOCUMENT_TYPE, type );
176 }
177
178 /**
179 * <p>Sets a collection object for collecting {@link XmlError} objects
180 * during parsing, validation, and compilation. When set, the collection
181 * will contain all the errors after the operation takes place. Notice that
182 * the errors will only have line numbers if the document was
183 * loaded with line numbers enabled.</p>
184 *
185 * <p>The following simple example illustrates using an error listener
186 * during validation.</p>
187 *
188 * <pre>
189 * // Create an XmlOptions instance and set the error listener.
190 * XmlOptions validateOptions = new XmlOptions();
191 * ArrayList errorList = new ArrayList();
192 * validateOptions.setErrorListener(errorList);
193 *
194 * // Validate the XML.
195 * boolean isValid = newEmp.validate(validateOptions);
196 *
197 * // If the XML isn't valid, loop through the listener's contents,
198 * // printing contained messages.
199 * if (!isValid)
200 * {
201 * for (int i = 0; i < errorList.size(); i++)
202 * {
203 * XmlError error = (XmlError)errorList.get(i);
204 *
205 * System.out.println("\n");
206 * System.out.println("Message: " + error.getMessage() + "\n");
207 * System.out.println("Location of invalid XML: " +
208 * error.getCursorLocation().xmlText() + "\n");
209 * }
210 * }
211 * </pre>
212 *
213 * @param c A collection that will be filled with {@link XmlError} objects
214 * via {@link Collection#add}
215 *
216 * @see XmlError
217 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
218 * @see XmlObject#validate(XmlOptions)
219 * @see XmlBeans#compileXsd
220 * @see XmlOptions#setLoadLineNumbers
221 */
222 public XmlOptions setErrorListener (Collection c) {
223 return set( ERROR_LISTENER, c );
224 }
225
226 /**
227 * Causes the saver to reduce the number of namespace prefix declarations.
228 * The saver will do this by passing over the document twice, first to
229 * collect the set of needed namespace declarations, and then second
230 * to actually save the document with the declarations collected
231 * at the root.
232 *
233 * @see XmlTokenSource#save(java.io.File, XmlOptions)
234 * @see XmlTokenSource#xmlText(XmlOptions)
235 */
236 public XmlOptions setSaveAggressiveNamespaces() {
237 return set( SAVE_AGGRESSIVE_NAMESPACES );
238 }
239
240 /**
241 * @deprecated replaced by {@link #setSaveAggressiveNamespaces}
242 */
243 public XmlOptions setSaveAggresiveNamespaces() {
244 return setSaveAggressiveNamespaces();
245 }
246
247 /**
248 * This option causes the saver to wrap the current fragment in
249 * an element with the given name.
250 *
251 * @param name the name to use for the top level element
252 *
253 * @see XmlTokenSource#save(java.io.File, XmlOptions)
254 * @see XmlTokenSource#xmlText(XmlOptions)
255 */
256 public XmlOptions setSaveSyntheticDocumentElement (QName name) {
257 return set( SAVE_SYNTHETIC_DOCUMENT_ELEMENT, name );
258 }
259
260 /**
261 * If this option is set, the saver will try to use the default
262 * namespace for the most commonly used URI. If it is not set
263 * the saver will always created named prefixes.
264 *
265 * @see XmlTokenSource#save(java.io.File, XmlOptions)
266 * @see XmlTokenSource#xmlText(XmlOptions)
267 */
268 public XmlOptions setUseDefaultNamespace () {
269 return set( SAVE_USE_DEFAULT_NAMESPACE );
270 }
271
272 /**
273 * If namespaces have already been declared outside the scope of the
274 * fragment being saved, this allows those mappings to be passed
275 * down to the saver, so the prefixes are not re-declared.
276 *
277 * @param implicitNamespaces a map of prefixes to uris that can be
278 * used by the saver without being declared
279 *
280 * @see XmlTokenSource#save(java.io.File, XmlOptions)
281 * @see XmlTokenSource#xmlText(XmlOptions)
282 */
283 public XmlOptions setSaveImplicitNamespaces (Map implicitNamespaces) {
284 return set( SAVE_IMPLICIT_NAMESPACES, implicitNamespaces );
285 }
286
287 /**
288 * A map of hints to pass to the saver for which prefixes to use
289 * for which namespace URI.
290 *
291 * @param suggestedPrefixes a map from URIs to prefixes
292 *
293 * @see XmlTokenSource#save(java.io.File, XmlOptions)
294 * @see XmlTokenSource#xmlText(XmlOptions)
295 */
296 public XmlOptions setSaveSuggestedPrefixes (Map suggestedPrefixes) {
297 return set( SAVE_SUGGESTED_PREFIXES, suggestedPrefixes );
298 }
299
300 /**
301 * This option causes the saver to filter a Processing Instruction
302 * with the given target
303 *
304 * @param filterProcinst the name of a Processing Instruction to filter
305 * on save
306 *
307 * @see XmlTokenSource#save(java.io.File, XmlOptions)
308 * @see XmlTokenSource#xmlText(XmlOptions)
309 */
310 public XmlOptions setSaveFilterProcinst (String filterProcinst) {
311 return set( SAVE_FILTER_PROCINST, filterProcinst );
312 }
313
314 /**
315 * This option causes the saver to replace characters with other values in
316 * the output stream. It is intended to be used for escaping non-standard
317 * characters during output.
318 *
319 * @param characterReplacementMap is an XmlOptionCharEscapeMap containing
320 * the characters to be escaped.
321 *
322 * @see XmlTokenSource#save(java.io.File, XmlOptions)
323 * @see XmlTokenSource#xmlText(XmlOptions)
324 * @see XmlOptionCharEscapeMap
325 */
326 public XmlOptions setSaveSubstituteCharacters (
327 XmlOptionCharEscapeMap characterReplacementMap) {
328 return set( SAVE_SUBSTITUTE_CHARACTERS, characterReplacementMap );
329 }
330
331 /**
332 * When saving a fragment, this option changes the qname of the synthesized
333 * root element. Normally <xml-fragment> is used.
334 *
335 * @see XmlTokenSource#save(java.io.File, XmlOptions)
336 * @see XmlTokenSource#xmlText(XmlOptions)
337 */
338 public XmlOptions setSaveUseOpenFrag () {
339 return set( SAVE_USE_OPEN_FRAGMENT );
340 }
341
342 /**
343 * This option controls whether saving begins on the element or its contents
344 *
345 * @see XmlTokenSource#save(java.io.File, XmlOptions)
346 * @see XmlTokenSource#xmlText(XmlOptions)
347 */
348 public XmlOptions setSaveOuter () {
349 return set( SAVE_OUTER );
350 }
351
352 /**
353 * This option controls whether saving begins on the element or its contents
354 *
355 * @see XmlTokenSource#save(java.io.File, XmlOptions)
356 * @see XmlTokenSource#xmlText(XmlOptions)
357 */
358 public XmlOptions setSaveInner () {
359 return set( SAVE_INNER );
360 }
361
362 /**
363 * This option controls whether saving saves out the XML
364 * declaration (<?xml ... ?>
365 *
366 * @see XmlTokenSource#save(java.io.File, XmlOptions)
367 * @see XmlTokenSource#xmlText(XmlOptions)
368 */
369 public XmlOptions setSaveNoXmlDecl () {
370 return set( SAVE_NO_XML_DECL );
371 }
372
373 /**
374 * This option controls when saving will use CDATA blocks.
375 * CDATA will be used if the folowing condition is true:
376 * <br/>textLength > cdataLengthThreshold && entityCount > cdataEntityCountThreshold
377 * <br/>The default value of cdataLengthThreshold is 32.
378 * <br/>
379 * <br/>Use the folowing values for these cases:
380 * <table border=1>
381 * <tr><th>Scenario</th> <th>cdataLengthThreshold</th> <th>cdataEntityCountThreshold</th></tr>
382 * <tr><td>Every text is CDATA</td> <td>0</td> <td>-1</td></tr>
383 * <tr><td>Only text that has an entity is CDATA</td> <td>0</td> <td>0</td></tr>
384 * <tr><td>Only text longer than x chars is CDATA</td> <td>x</td> <td>-1</td></tr>
385 * <tr><td>Only text that has y entitazable chars is CDATA</td> <td>0</td> <td>y</td></tr>
386 * <tr><td>Only text longer than x chars and has y entitazable chars is CDATA</td> <td>x</td> <td>y</td></tr>
387 * </table>
388 * @see XmlOptions#setSaveCDataEntityCountThreshold(int)
389 */
390 public XmlOptions setSaveCDataLengthThreshold (int cdataLengthThreshold) {
391 return set( SAVE_CDATA_LENGTH_THRESHOLD, cdataLengthThreshold );
392 }
393
394 /**
395 * This option controls when saving will use CDATA blocks.
396 * CDATA will be used if the folowing condition is true:
397 * <br/>textLength > cdataLengthThreshold && entityCount > cdataEntityCountThreshold
398 * <br/>The default value of cdataEntityCountThreshold is 5.
399 *
400 * @see XmlOptions#setSaveCDataLengthThreshold(int)
401 */
402 public XmlOptions setSaveCDataEntityCountThreshold (int cdataEntityCountThreshold) {
403 return set( SAVE_CDATA_ENTITY_COUNT_THRESHOLD, cdataEntityCountThreshold );
404 }
405
406 /**
407 * <p>Use this option when parsing and saving XML documents.</p>
408 *
409 * <p>For parsing this option will annotate the text fields in the store with CDataBookmark.</p>
410 *
411 * <p>For saving this option will save the text fields annotated with CDataBookmark as
412 * CDATA XML text.<br>
413 * Note: The SaveCDataEntityCountThreshold and SaveCDataLengthThreshold options and
414 * their default values still apply.</p>
415 *
416 * <p><b>Note: Due to the store representation, a CDATA will not be recognized
417 * if it is imediately after non CDATA text and all text following it will
418 * be considered CDATA.</b><br/>
419 * Example:<br>
420 * <pre>
421 * <a><![CDATA[cdata text]]></a> - is considered as: <a><![CDATA[cdata text]]></a>
422 * <b><![CDATA[cdata text]]> regular text</b> - is considered as: <b><![CDATA[cdata text regular text]]></b>
423 * <c>text <![CDATA[cdata text]]></c> - is considered as: <c>text cdata text</c>
424 * </pre>
425 * </p>
426 *
427 * <p>Sample code:
428 * <pre>
429 String xmlText = "<a>\n" +
430 "<a><![CDATA[cdata text]]></a>\n" +
431 "<b><![CDATA[cdata text]]> regular text</b>\n" +
432 "<c>text <![CDATA[cdata text]]></c>\n" +
433 "</a>";
434 System.out.println(xmlText);
435
436 XmlOptions opts = new XmlOptions();
437 opts.setUseCDataBookmarks();
438
439 XmlObject xo = XmlObject.Factory.parse( xmlText , opts);
440
441 System.out.println("xo1:\n" + xo.xmlText(opts));
442 System.out.println("\n");
443
444 opts.setSavePrettyPrint();
445 System.out.println("xo2:\n" + xo.xmlText(opts));
446 * </pre>
447 * </p>
448 *
449 * @see CDataBookmark
450 * @see CDataBookmark#CDATA_BOOKMARK
451 */
452 public XmlOptions setUseCDataBookmarks()
453 {
454 return set( LOAD_SAVE_CDATA_BOOKMARKS );
455 }
456
457 /**
458 * This option controls whether namespace declarations are included as attributes in the
459 * startElement event. By default, up to and including XMLBeans 2.3.0 they were included, in
460 * subsequent versions, they are no longer included.
461 */
462 public XmlOptions setSaveSaxNoNSDeclsInAttributes () {
463 return set( SAVE_SAX_NO_NSDECLS_IN_ATTRIBUTES );
464 }
465
466 /**
467 * If this option is set, the document element is replaced with the
468 * given QName when parsing. If null is supplied, the document element
469 * is removed.
470 *
471 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
472 */
473 public XmlOptions setLoadReplaceDocumentElement ( QName replacement ) {
474 return set( LOAD_REPLACE_DOCUMENT_ELEMENT, replacement );
475 }
476
477 /**
478 * If this option is set, all insignificant whitespace is stripped
479 * when parsing a document. Can be used to save memory on large
480 * documents when you know there is no mixed content.
481 *
482 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
483 */
484 public XmlOptions setLoadStripWhitespace () {
485 return set( LOAD_STRIP_WHITESPACE);
486 }
487
488 /**
489 * If this option is set, all comments are stripped when parsing
490 * a document.
491 *
492 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
493 */
494 public XmlOptions setLoadStripComments() {
495 return set( LOAD_STRIP_COMMENTS );
496 }
497
498 /**
499 * If this option is set, all processing instructions
500 * are stripped when parsing a document.
501 *
502 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
503 */
504 public XmlOptions setLoadStripProcinsts () {
505 return set( LOAD_STRIP_PROCINSTS );
506 }
507
508 /**
509 * If this option is set, line number annotations are placed
510 * in the store when parsing a document. This is particularly
511 * useful when you want {@link XmlError} objects to contain
512 * line numbers.
513 * <br/>Note: This adds line numbers info only for start tags.
514 * For line number info on end tags use:
515 * {@link XmlOptions#setLoadLineNumbers(java.lang.String)}
516 * <br/>Example: xmlOptions.setLoadLineNumbers(XmlOptions.LOAD_LINE_NUMBERS_END_ELEMENT)
517 *
518 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
519 * @see XmlError
520 */
521 public XmlOptions setLoadLineNumbers () {
522 return set( LOAD_LINE_NUMBERS );
523 }
524
525 /**
526 * If this option is set, line number annotations are placed
527 * in the store when parsing a document. This is particularly
528 * useful when you want {@link XmlError} objects to contain
529 * line numbers. Use the option to load line numbers at the end of an element.
530 * <br/>Example: xmlOptions.setLoadLineNumbers(XmlOptions.LOAD_LINE_NUMBERS_END_ELEMENT)
531 *
532 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
533 * @see XmlError
534 */
535 public XmlOptions setLoadLineNumbers (String option) {
536 XmlOptions temp = setLoadLineNumbers();
537 temp = temp.set( option );
538 return temp;
539 }
540
541 /**
542 * This option sets a map of namespace uri substitutions that happen
543 * when parsing a document.
544 * <p>
545 * This is particularly useful if you
546 * have documents that use no namespace, but you wish to avoid
547 * the name collision problems that occur when you introduce
548 * schema definitions without a target namespace.
549 * <p>
550 * By mapping the empty string "" (the absence of a URI) to a specific
551 * namespace, you can force the parser to behave as if a no-namespace
552 * document were actually in the specified namespace. This allows you
553 * to type the instance according to a schema in a nonempty namespace,
554 * and therefore avoid the problematic practice of using schema
555 * definitions without a target namespace.
556 *
557 * @param substNamespaces a map of document URIs to replacement URIs
558 *
559 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
560 */
561 public XmlOptions setLoadSubstituteNamespaces (Map substNamespaces) {
562 return set( LOAD_SUBSTITUTE_NAMESPACES, substNamespaces );
563 }
564
565 /**
566 * If this option is set, the underlying xml text buffer is trimmed
567 * immediately after parsing a document resulting in a smaller memory
568 * footprint. Use this option if you are loading a large number
569 * of unchanging documents that will stay in memory for some time.
570 *
571 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
572 */
573 public XmlOptions setLoadTrimTextBuffer () {
574 return set( LOAD_TRIM_TEXT_BUFFER );
575 }
576
577 /**
578 * Set additional namespace mappings to be added when parsing
579 * a document.
580 *
581 * @param nses additional namespace mappings
582 *
583 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
584 */
585 public XmlOptions setLoadAdditionalNamespaces (Map nses) {
586 return set( LOAD_ADDITIONAL_NAMESPACES, nses );
587 }
588
589 /**
590 * If this option is set when loading from an InputStream or File, then
591 * the loader will compute a 160-bit SHA-1 message digest of the XML
592 * file while loading it and make it available via
593 * XmlObject.documentProperties().getMessageDigest();
594 * <br>
595 * The schema compiler uses message digests to detect and eliminate
596 * duplicate imported xsd files.
597 *
598 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
599 */
600 public XmlOptions setLoadMessageDigest () {
601 return set( LOAD_MESSAGE_DIGEST );
602 }
603
604 /**
605 * By default, XmlBeans does not resolve entities when parsing xml
606 * documents (unless an explicit entity resolver is specified).
607 * Use this option to turn on entity resolving by default.
608 *
609 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
610 */
611 public XmlOptions setLoadUseDefaultResolver () {
612 return set( LOAD_USE_DEFAULT_RESOLVER );
613 }
614
615 /**
616 * By default, XmlBeans uses an internal Piccolo parser,
617 * other parsers can be used by providing an XMLReader.
618 * For using the default JDK's SAX parser use:
619 * xmlOptions.setLoadUseXMLReader( SAXParserFactory.newInstance().newSAXParser().getXMLReader() );
620 *
621 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
622 */
623 public XmlOptions setLoadUseXMLReader (XMLReader xmlReader) {
624 return set( LOAD_USE_XMLREADER, xmlReader );
625 }
626
627 /**
628 * Sets the name of the variable that represents
629 * the current node in a query expression.
630 *
631 * @param varName The new variable name to use for the query.
632 *
633 * @see XmlObject#execQuery
634 * @see XmlCursor#execQuery
635 */
636 public XmlOptions setXqueryCurrentNodeVar (String varName) {
637 return set( XQUERY_CURRENT_NODE_VAR, varName );
638 }
639
640 /**
641 * Map the names and values of external variables in an xquery
642 * expression. The keys of the map are the variable names
643 * in the query without the '$' prefix. The values of the map
644 * are objects and can be any of the primitive wrapper classes,
645 * String, XmlObject, or XmlCursor. The mapping only applies to
646 * xquery and has no effect on xpath expressions.
647 *
648 * @param varMap a map from Strings to variable instances.
649 *
650 * @see XmlObject#execQuery
651 * @see XmlCursor#execQuery
652 */
653 public XmlOptions setXqueryVariables (Map varMap) {
654 return set( XQUERY_VARIABLE_MAP, varMap );
655 }
656
657 /**
658 * This option sets the document source name into the xml store
659 * when parsing a document. If a document is parsed from a
660 * File or URI, it is automatically set to the URI of the
661 * source; otherwise, for example, when parsing a String,
662 * you can use this option to specify the source name yourself.
663 *
664 * @see XmlObject.Factory#parse(java.lang.String, XmlOptions)
665 */
666 public XmlOptions setDocumentSourceName (String documentSourceName) {
667 return set( DOCUMENT_SOURCE_NAME, documentSourceName );
668 }
669
670 /**
671 * This option allows for <code>QName</code> substitution during schema compilation.
672 *
673 * @param nameMap a map from <code>QName</code>s to substitute <code>QName</code>s.
674 *
675 * @see XmlBeans#compileXsd
676 */
677 public XmlOptions setCompileSubstituteNames (Map nameMap) {
678 return set( COMPILE_SUBSTITUTE_NAMES, nameMap );
679 }
680
681 /**
682 * If this option is set, validation is not done on the Schema XmlBeans
683 * when building a <code>SchemaTypeSystem</code>
684 *
685 * @see XmlBeans#compileXsd
686 */
687 public XmlOptions setCompileNoValidation () {
688 return set( COMPILE_NO_VALIDATION );
689 }
690
691 /**
692 * If this option is set, the unique particle attribution rule is not
693 * enforced when building a <code>SchemaTypeSystem</code>. See
694 * <a target="_blank" href="http://www.w3.org/TR/xmlschema-1/#non-ambig">Appendix H of the XML Schema specification</a>
695 * for information on the UPA rule.
696 *
697 * @see XmlBeans#compileXsd
698 */
699 public XmlOptions setCompileNoUpaRule () {
700 return set( COMPILE_NO_UPA_RULE );
701 }
702
703 /**
704 * If this option is set, the particle valid (restriciton) rule is not
705 * enforced when building a <code>SchemaTypeSystem</code>. See
706 * <a target="_blank" href="http://www.w3.org/TR/xmlschema-1/#cos-particle-restrict">Section 3.9.6 of the XML Schema specification</a>
707 * for information on the PVR rule.
708 *
709 * @see XmlBeans#compileXsd
710 */
711 public XmlOptions setCompileNoPvrRule () {
712 return set( COMPILE_NO_PVR_RULE );
713 }
714
715 /**
716 * if this option is set, the schema compiler will skip annotations when
717 * processing Schema components.
718 *
719 * @see XmlBeans#compileXsd
720 */
721 public XmlOptions setCompileNoAnnotations() {
722 return set( COMPILE_NO_ANNOTATIONS );
723 }
724
725 /**
726 * If this option is set, then the schema compiler will try to download
727 * schemas that appear in imports and includes from network based URLs.
728 *
729 * @see XmlBeans#compileXsd
730 */
731 public XmlOptions setCompileDownloadUrls () {
732 return set( COMPILE_DOWNLOAD_URLS);
733 }
734
735 /**
736 * If this option is set, then the schema compiler will permit and
737 * ignore multiple definitions of the same component (element, attribute,
738 * type, etc) names in the given namespaces. If multiple definitions
739 * with the same name appear, the definitions that happen to be processed
740 * last will be ignored.
741 *
742 * @param mdefNamespaces a set of namespace URIs as Strings
743 *
744 * @see XmlBeans#compileXsd
745 */
746 public XmlOptions setCompileMdefNamespaces(Set mdefNamespaces)
747 {
748 return set( COMPILE_MDEF_NAMESPACES, mdefNamespaces );
749 }
750
751 /**
752 * If this option is set when an instance is created, then value
753 * facets will be checked on each call to a setter or getter
754 * method on instances of XmlObject within the instance document.
755 * If the facets are not satisfied, then an unchecked exception is
756 * thrown immediately. This option is useful for finding code that
757 * is introducing invalid values in an XML document, but it
758 * slows performance.
759 *
760 * @see XmlObject.Factory#parse(java.io.File, XmlOptions)
761 */
762 public XmlOptions setValidateOnSet() {
763 return set( VALIDATE_ON_SET );
764 }
765
766 /**
767 * Instructs the validator to skip elements matching an <any>
768 * particle with contentModel="lax". This is useful because,
769 * in certain situations, XmlBeans will find types on the
770 * classpath that the document author did not anticipate.
771 */
772 public XmlOptions setValidateTreatLaxAsSkip() {
773 return set ( VALIDATE_TREAT_LAX_AS_SKIP );
774 }
775
776 /**
777 * Performs additional validation checks that are disabled by
778 * default for better compatibility.
779 */
780 public XmlOptions setValidateStrict() {
781 return set ( VALIDATE_STRICT );
782 }
783
784 /**
785 * This option controls whether or not operations on XmlBeans are
786 * thread safe. When not on, all XmlBean operations will be syncronized.
787 * This provides for multiple thread the ability to access a single
788 * XmlBeans simultainously, but has a perf impact. If set, then
789 * only one thread may access an XmlBean.
790 */
791 public XmlOptions setUnsynchronized ( )
792 {
793 return set( UNSYNCHRONIZED );
794 }
795
796 /**
797 * If this option is set when compiling a schema, then the given
798 * EntityResolver will be consulted in order to resolve any
799 * URIs while downloading imported schemas.
800 *
801 * EntityResolvers are currently only used by compileXsd; they
802 * are not consulted by other functions, for example, parse.
803 * This will likely change in the future.
804 *
805 * @see XmlBeans#compileXsd
806 */
807 public XmlOptions setEntityResolver(EntityResolver resolver) {
808 return set( ENTITY_RESOLVER, resolver );
809 }
810
811 /**
812 * If this option is set when compiling a schema, then the given
813 * URI will be considered as base URI when deciding the directory
814 * structure for saving the sources inside the generated JAR file.
815 * @param baseURI the URI to be considered as "base"
816 * @see XmlBeans#compileXsd
817 */
818 public XmlOptions setBaseURI(URI baseURI) {
819 return set( BASE_URI, baseURI );
820 }
821
822 /**
823 * If this option is set when compiling a schema, then the given
824 * SchemaTypeCodePrinter.Printer will be used to generate the
825 * Java code.
826 *
827 * @see XmlBeans#compileXsd
828 */
829 public XmlOptions setSchemaCodePrinter(SchemaCodePrinter printer) {
830 return set( SCHEMA_CODE_PRINTER, printer );
831 }
832
833 /**
834 * If this option is set, then the schema compiler will print java code
835 * that is compatible with the desired Java version. If not set, the
836 * current Java version is used. Currently, only "1.4" and "1.5" are
837 * supported.
838 *
839 * @param source A Java version number
840 *
841 * @see #GENERATE_JAVA_14
842 * @see #GENERATE_JAVA_15
843 * @see XmlBeans#compileXmlBeans
844 */
845 public XmlOptions setGenerateJavaVersion (String source) {
846 return set( GENERATE_JAVA_VERSION, source );
847 }
848
849 public static final String GENERATE_JAVA_14 = "1.4";
850 public static final String GENERATE_JAVA_15 = "1.5";
851
852
853 //
854 // Complete set of XmlOption's
855 //
856
857 // TODO - Add selectPath option to track the seletion (deault is to clean selections fast).
858
859 /** @exclude */
860 public static final String SAVE_NAMESPACES_FIRST = "SAVE_NAMESPACES_FIRST";
861 /** @exclude */
862 public static final String SAVE_SYNTHETIC_DOCUMENT_ELEMENT = "SAVE_SYNTHETIC_DOCUMENT_ELEMENT";
863 /** @exclude */
864 public static final String SAVE_PRETTY_PRINT = "SAVE_PRETTY_PRINT";
865 /** @exclude */
866 public static final String SAVE_PRETTY_PRINT_INDENT = "SAVE_PRETTY_PRINT_INDENT";
867 /** @exclude */
868 public static final String SAVE_PRETTY_PRINT_OFFSET = "SAVE_PRETTY_PRINT_OFFSET";
869 /** @exclude */
870 public static final String SAVE_AGGRESSIVE_NAMESPACES = "SAVE_AGGRESSIVE_NAMESPACES";
871 /** @exclude */
872 public static final String SAVE_USE_DEFAULT_NAMESPACE = "SAVE_USE_DEFAULT_NAMESPACE";
873 /** @exclude */
874 public static final String SAVE_IMPLICIT_NAMESPACES = "SAVE_IMPLICIT_NAMESPACES";
875 /** @exclude */
876 public static final String SAVE_SUGGESTED_PREFIXES = "SAVE_SUGGESTED_PREFIXES";
877 /** @exclude */
878 public static final String SAVE_FILTER_PROCINST = "SAVE_FILTER_PROCINST";
879 /** @exclude */
880 public static final String SAVE_USE_OPEN_FRAGMENT = "SAVE_USE_OPEN_FRAGMENT";
881 /** @exclude */
882 public static final String SAVE_OUTER = "SAVE_OUTER";
883 /** @exclude */
884 public static final String SAVE_INNER = "SAVE_INNER";
885 /** @exclude */
886 public static final String SAVE_NO_XML_DECL = "SAVE_NO_XML_DECL";
887 /** @exclude */
888 public static final String SAVE_SUBSTITUTE_CHARACTERS = "SAVE_SUBSTITUTE_CHARACTERS";
889 /** @exclude */
890 public static final String SAVE_OPTIMIZE_FOR_SPEED = "SAVE_OPTIMIZE_FOR_SPEED";
891 /** @exclude */
892 public static final String SAVE_CDATA_LENGTH_THRESHOLD = "SAVE_CDATA_LENGTH_THRESHOLD";
893 /** @exclude */
894 public static final String SAVE_CDATA_ENTITY_COUNT_THRESHOLD = "SAVE_CDATA_ENTITY_COUNT_THRESHOLD";
895 /** @exclude */
896 public static final String SAVE_SAX_NO_NSDECLS_IN_ATTRIBUTES = "SAVE_SAX_NO_NSDECLS_IN_ATTRIBUTES";
897 /** @exclude */
898 public static final String LOAD_REPLACE_DOCUMENT_ELEMENT = "LOAD_REPLACE_DOCUMENT_ELEMENT";
899 /** @exclude */
900 public static final String LOAD_STRIP_WHITESPACE = "LOAD_STRIP_WHITESPACE";
901 /** @exclude */
902 public static final String LOAD_STRIP_COMMENTS = "LOAD_STRIP_COMMENTS";
903 /** @exclude */
904 public static final String LOAD_STRIP_PROCINSTS = "LOAD_STRIP_PROCINSTS";
905 /** @exclude */
906 public static final String LOAD_LINE_NUMBERS = "LOAD_LINE_NUMBERS";
907 /** @exclude */
908 public static final String LOAD_LINE_NUMBERS_END_ELEMENT = "LOAD_LINE_NUMBERS_END_ELEMENT";
909 /** @exclude */
910 public static final String LOAD_SAVE_CDATA_BOOKMARKS = "LOAD_SAVE_CDATA_BOOKMARKS";
911 /** @exclude */
912 public static final String LOAD_SUBSTITUTE_NAMESPACES = "LOAD_SUBSTITUTE_NAMESPACES";
913 /** @exclude */
914 public static final String LOAD_TRIM_TEXT_BUFFER = "LOAD_TRIM_TEXT_BUFFER";
915 /** @exclude */
916 public static final String LOAD_ADDITIONAL_NAMESPACES = "LOAD_ADDITIONAL_NAMESPACES";
917 /** @exclude */
918 public static final String LOAD_MESSAGE_DIGEST = "LOAD_MESSAGE_DIGEST";
919 /** @exclude */
920 public static final String LOAD_USE_DEFAULT_RESOLVER = "LOAD_USE_DEFAULT_RESOLVER";
921 /** @exclude */
922 public static final String LOAD_USE_XMLREADER = "LOAD_USE_XMLREADER";
923
924 /** @exclude */
925 public static final String XQUERY_CURRENT_NODE_VAR = "XQUERY_CURRENT_NODE_VAR";
926 /** @exclude */
927 public static final String XQUERY_VARIABLE_MAP = "XQUERY_VARIABLE_MAP";
928
929 /** @exclude */
930 public static final String CHARACTER_ENCODING = "CHARACTER_ENCODING";
931 /** @exclude */
932 public static final String ERROR_LISTENER = "ERROR_LISTENER";
933 /** @exclude */
934 public static final String DOCUMENT_TYPE = "DOCUMENT_TYPE";
935 /** @exclude */
936 public static final String DOCUMENT_SOURCE_NAME = "DOCUMENT_SOURCE_NAME";
937 /** @exclude */
938 public static final String COMPILE_SUBSTITUTE_NAMES = "COMPILE_SUBSTITUTE_NAMES";
939 /** @exclude */
940 public static final String COMPILE_NO_VALIDATION = "COMPILE_NO_VALIDATION";
941 /** @exclude */
942 public static final String COMPILE_NO_UPA_RULE = "COMPILE_NO_UPA_RULE";
943 /** @exclude */
944 public static final String COMPILE_NO_PVR_RULE = "COMPILE_NO_PVR_RULE";
945 /** @exclude */
946 public static final String COMPILE_NO_ANNOTATIONS = "COMPILE_NO_ANNOTATIONS";
947 /** @exclude */
948 public static final String COMPILE_DOWNLOAD_URLS = "COMPILE_DOWNLOAD_URLS";
949 /** @exclude */
950 public static final String COMPILE_MDEF_NAMESPACES = "COMPILE_MDEF_NAMESPACES";
951 /** @exclude */
952 public static final String VALIDATE_ON_SET = "VALIDATE_ON_SET";
953 /** @exclude */
954 public static final String VALIDATE_TREAT_LAX_AS_SKIP = "VALIDATE_TREAT_LAX_AS_SKIP";
955 /** @exclude */
956 public static final String VALIDATE_STRICT = "VALIDATE_STRICT";
957 /** @exclude */
958 public static final String VALIDATE_TEXT_ONLY = "VALIDATE_TEXT_ONLY";
959 /** @exclude */
960 public static final String UNSYNCHRONIZED = "UNSYNCHRONIZED";
961 /** @exclude */
962 public static final String ENTITY_RESOLVER = "ENTITY_RESOLVER";
963 /** @exclude */
964 public static final String BASE_URI = "BASE_URI";
965 /** @exclude */
966 public static final String SCHEMA_CODE_PRINTER = "SCHEMA_CODE_PRINTER";
967 /** @exclude */
968 public static final String GENERATE_JAVA_VERSION = "GENERATE_JAVA_VERSION";
969
970 private static final XmlOptions EMPTY_OPTIONS;
971 static {
972 EMPTY_OPTIONS = new XmlOptions();
973 EMPTY_OPTIONS._map = Collections.unmodifiableMap(EMPTY_OPTIONS._map);
974 }
975
976 /** If passed null, returns an empty options object. Otherwise, returns its argument. */
977 public static XmlOptions maskNull(XmlOptions o) {
978 return (o == null) ? EMPTY_OPTIONS : o;
979 }
980
981
982 /** Used to set a generic option */
983 public void put ( Object option ) { put( option, null ); }
984 /** Used to set a generic option */
985 public void put ( Object option, Object value ) { _map.put(option, value); }
986 /** Used to set a generic option */
987 public void put ( Object option, int value ) { put( option, new Integer( value ) ); }
988
989 private XmlOptions set(Object option) { return set(option, null); }
990 private XmlOptions set(Object option, Object value) { _map.put(option, value); return this;}
991 private XmlOptions set(Object option, int value) { return set(option, new Integer(value)); }
992
993 /** Used to test a generic option */
994 public boolean hasOption ( Object option ) { return _map.containsKey( option ); }
995 public static boolean hasOption ( XmlOptions options, Object option ) { return options == null ? false : options.hasOption( option ); }
996
997 /** Used to get a generic option */
998 public Object get ( Object option ) { return _map.get( option ); }
999 public void remove ( Object option ) { _map.remove( option ); }
1000
1001 /** Used to test a generic option on an options object that may be null */
1002 public static Object safeGet(XmlOptions o, Object option) {
1003 return o == null ? null : o.get(option);
1004 }
1005
1006 }