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