Home » xmlbeans-2.5.0-src » org.apache » xmlbeans » [javadoc | source]

    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 &lt;xml-fragment&gt; 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        * &lt;a>&lt;![CDATA[cdata text]]>&lt;/a>               - is considered as: &lt;a>&lt;![CDATA[cdata text]]>&lt;/a>
  422        * &lt;b>&lt;![CDATA[cdata text]]> regular text&lt;/b>  - is considered as: &lt;b>&lt;![CDATA[cdata text regular text]]>&lt;/b>
  423        * &lt;c>text &lt;![CDATA[cdata text]]>&lt;/c>          - is considered as: &lt;c>text cdata text&lt;/c>
  424        * </pre>
  425        * </p>
  426        *
  427        * <p>Sample code:
  428        * <pre>
  429           String xmlText = "&lt;a>\n" +
  430                   "&lt;a>&lt;![CDATA[cdata text]]>&lt;/a>\n" +
  431                   "&lt;b>&lt;![CDATA[cdata text]]> regular text&lt;/b>\n" +
  432                   "&lt;c>text &lt;![CDATA[cdata text]]>&lt;/c>\n" +
  433                   "&lt;/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   }

Home » xmlbeans-2.5.0-src » org.apache » xmlbeans » [javadoc | source]