Save This Page
Home » xmlbeans-2.5.0-src » org.apache » xmlbeans » [javadoc | source]
org.apache.xmlbeans
public class: XmlOptions [javadoc | source]
java.lang.Object
   org.apache.xmlbeans.XmlOptions

All Implemented Interfaces:
    java$io$Serializable

Direct Known Subclasses:
    XmlOptionsBean

Used to supply options for loading, saving, and compiling, and validating.

There are two styles for using XmlOptions: multiline setup, and single-line use. Here are two examples. First, multiline style:

XmlOptions opts = new XmlOptions();
opts.setSavePrettyPrint();
opts.setSavePrettyPrintIndent(4);
System.out.println(xobj.xmlText(opts));
The alternative is single-line usage:
System.out.println(xobj.xmlText(
    new XmlOptions().setSavePrettyPrint().setSavePrettyPrintIndent(4)));
Table showing where each option gets used. Note that:
newInstance methods parse methods validate methods compile methods save and xmlTextmethods
setDocumentType
setDocumentSourceName
setValidateOnSet
setUnsynchronized
setLoad***
setEntityResolver
setErrorListener
setValidateTreatLaxAsSkip setValidateStrict
setErrorListener
setCompile***
setEntityResolver
setBaseURI
setGenerateJavaVersion
setSave***
setUseDefaultNamespace
setCharacterEncoding
Field Summary
public static final  String GENERATE_JAVA_14     
public static final  String GENERATE_JAVA_15     
public static final  String SAVE_NAMESPACES_FIRST   
    exclude:
 
public static final  String SAVE_SYNTHETIC_DOCUMENT_ELEMENT   
    exclude:
 
public static final  String SAVE_PRETTY_PRINT   
    exclude:
 
public static final  String SAVE_PRETTY_PRINT_INDENT   
    exclude:
 
public static final  String SAVE_PRETTY_PRINT_OFFSET   
    exclude:
 
public static final  String SAVE_AGGRESSIVE_NAMESPACES   
    exclude:
 
public static final  String SAVE_USE_DEFAULT_NAMESPACE   
    exclude:
 
public static final  String SAVE_IMPLICIT_NAMESPACES   
    exclude:
 
public static final  String SAVE_SUGGESTED_PREFIXES   
    exclude:
 
public static final  String SAVE_FILTER_PROCINST   
    exclude:
 
public static final  String SAVE_USE_OPEN_FRAGMENT   
    exclude:
 
public static final  String SAVE_OUTER   
    exclude:
 
public static final  String SAVE_INNER   
    exclude:
 
public static final  String SAVE_NO_XML_DECL   
    exclude:
 
public static final  String SAVE_SUBSTITUTE_CHARACTERS   
    exclude:
 
public static final  String SAVE_OPTIMIZE_FOR_SPEED   
    exclude:
 
public static final  String SAVE_CDATA_LENGTH_THRESHOLD   
    exclude:
 
public static final  String SAVE_CDATA_ENTITY_COUNT_THRESHOLD   
    exclude:
 
public static final  String SAVE_SAX_NO_NSDECLS_IN_ATTRIBUTES   
    exclude:
 
public static final  String LOAD_REPLACE_DOCUMENT_ELEMENT   
    exclude:
 
public static final  String LOAD_STRIP_WHITESPACE   
    exclude:
 
public static final  String LOAD_STRIP_COMMENTS   
    exclude:
 
public static final  String LOAD_STRIP_PROCINSTS   
    exclude:
 
public static final  String LOAD_LINE_NUMBERS   
    exclude:
 
public static final  String LOAD_LINE_NUMBERS_END_ELEMENT   
    exclude:
 
public static final  String LOAD_SAVE_CDATA_BOOKMARKS   
    exclude:
 
public static final  String LOAD_SUBSTITUTE_NAMESPACES   
    exclude:
 
public static final  String LOAD_TRIM_TEXT_BUFFER   
    exclude:
 
public static final  String LOAD_ADDITIONAL_NAMESPACES   
    exclude:
 
public static final  String LOAD_MESSAGE_DIGEST   
    exclude:
 
public static final  String LOAD_USE_DEFAULT_RESOLVER   
    exclude:
 
public static final  String LOAD_USE_XMLREADER   
    exclude:
 
public static final  String XQUERY_CURRENT_NODE_VAR   
    exclude:
 
public static final  String XQUERY_VARIABLE_MAP   
    exclude:
 
public static final  String CHARACTER_ENCODING   
    exclude:
 
public static final  String ERROR_LISTENER   
    exclude:
 
public static final  String DOCUMENT_TYPE   
    exclude:
 
public static final  String DOCUMENT_SOURCE_NAME   
    exclude:
 
public static final  String COMPILE_SUBSTITUTE_NAMES   
    exclude:
 
public static final  String COMPILE_NO_VALIDATION   
    exclude:
 
public static final  String COMPILE_NO_UPA_RULE   
    exclude:
 
public static final  String COMPILE_NO_PVR_RULE   
    exclude:
 
public static final  String COMPILE_NO_ANNOTATIONS   
    exclude:
 
public static final  String COMPILE_DOWNLOAD_URLS   
    exclude:
 
public static final  String COMPILE_MDEF_NAMESPACES   
    exclude:
 
public static final  String VALIDATE_ON_SET   
    exclude:
 
public static final  String VALIDATE_TREAT_LAX_AS_SKIP   
    exclude:
 
public static final  String VALIDATE_STRICT   
    exclude:
 
public static final  String VALIDATE_TEXT_ONLY   
    exclude:
 
public static final  String UNSYNCHRONIZED   
    exclude:
 
public static final  String ENTITY_RESOLVER   
    exclude:
 
public static final  String BASE_URI   
    exclude:
 
public static final  String SCHEMA_CODE_PRINTER   
    exclude:
 
public static final  String GENERATE_JAVA_VERSION   
    exclude:
 
Constructor:
 public XmlOptions() 
 public XmlOptions(XmlOptions other) 
    Construct a new XmlOptions, copying the options.
Method from org.apache.xmlbeans.XmlOptions Summary:
get,   hasOption,   hasOption,   maskNull,   put,   put,   put,   remove,   safeGet,   setBaseURI,   setCharacterEncoding,   setCompileDownloadUrls,   setCompileMdefNamespaces,   setCompileNoAnnotations,   setCompileNoPvrRule,   setCompileNoUpaRule,   setCompileNoValidation,   setCompileSubstituteNames,   setDocumentSourceName,   setDocumentType,   setEntityResolver,   setErrorListener,   setGenerateJavaVersion,   setLoadAdditionalNamespaces,   setLoadLineNumbers,   setLoadLineNumbers,   setLoadMessageDigest,   setLoadReplaceDocumentElement,   setLoadStripComments,   setLoadStripProcinsts,   setLoadStripWhitespace,   setLoadSubstituteNamespaces,   setLoadTrimTextBuffer,   setLoadUseDefaultResolver,   setLoadUseXMLReader,   setSaveAggresiveNamespaces,   setSaveAggressiveNamespaces,   setSaveCDataEntityCountThreshold,   setSaveCDataLengthThreshold,   setSaveFilterProcinst,   setSaveImplicitNamespaces,   setSaveInner,   setSaveNamespacesFirst,   setSaveNoXmlDecl,   setSaveOuter,   setSavePrettyPrint,   setSavePrettyPrintIndent,   setSavePrettyPrintOffset,   setSaveSaxNoNSDeclsInAttributes,   setSaveSubstituteCharacters,   setSaveSuggestedPrefixes,   setSaveSyntheticDocumentElement,   setSaveUseOpenFrag,   setSchemaCodePrinter,   setUnsynchronized,   setUseCDataBookmarks,   setUseDefaultNamespace,   setValidateOnSet,   setValidateStrict,   setValidateTreatLaxAsSkip,   setXqueryCurrentNodeVar,   setXqueryVariables
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from org.apache.xmlbeans.XmlOptions Detail:
 public Object get(Object option) 
    Used to get a generic option
 public boolean hasOption(Object option) 
    Used to test a generic option
 public static boolean hasOption(XmlOptions options,
    Object option) 
 public static XmlOptions maskNull(XmlOptions o) 
    If passed null, returns an empty options object. Otherwise, returns its argument.
 public  void put(Object option) 
    Used to set a generic option
 public  void put(Object option,
    Object value) 
    Used to set a generic option
 public  void put(Object option,
    int value) 
    Used to set a generic option
 public  void remove(Object option) 
 public static Object safeGet(XmlOptions o,
    Object option) 
    Used to test a generic option on an options object that may be null
 public XmlOptions setBaseURI(URI baseURI) 
    If this option is set when compiling a schema, then the given URI will be considered as base URI when deciding the directory structure for saving the sources inside the generated JAR file.
 public XmlOptions setCharacterEncoding(String encoding) 
    When writing a document, this sets the character encoding to use.
 public XmlOptions setCompileDownloadUrls() 
    If this option is set, then the schema compiler will try to download schemas that appear in imports and includes from network based URLs.
 public XmlOptions setCompileMdefNamespaces(Set mdefNamespaces) 
    If this option is set, then the schema compiler will permit and ignore multiple definitions of the same component (element, attribute, type, etc) names in the given namespaces. If multiple definitions with the same name appear, the definitions that happen to be processed last will be ignored.
 public XmlOptions setCompileNoAnnotations() 
    if this option is set, the schema compiler will skip annotations when processing Schema components.
 public XmlOptions setCompileNoPvrRule() 
 public XmlOptions setCompileNoUpaRule() 
 public XmlOptions setCompileNoValidation() 
    If this option is set, validation is not done on the Schema XmlBeans when building a SchemaTypeSystem
 public XmlOptions setCompileSubstituteNames(Map nameMap) 
    This option allows for QName substitution during schema compilation.
 public XmlOptions setDocumentSourceName(String documentSourceName) 
    This option sets the document source name into the xml store when parsing a document. If a document is parsed from a File or URI, it is automatically set to the URI of the source; otherwise, for example, when parsing a String, you can use this option to specify the source name yourself.
 public XmlOptions setDocumentType(SchemaType type) 
    When parsing a document, this sets the type of the root element. If this is set, the parser will not try to guess the type based on the document's QName.
 public XmlOptions setEntityResolver(EntityResolver resolver) 
    If this option is set when compiling a schema, then the given EntityResolver will be consulted in order to resolve any URIs while downloading imported schemas. EntityResolvers are currently only used by compileXsd; they are not consulted by other functions, for example, parse. This will likely change in the future.
 public XmlOptions setErrorListener(Collection c) 

    Sets a collection object for collecting XmlError objects during parsing, validation, and compilation. When set, the collection will contain all the errors after the operation takes place. Notice that the errors will only have line numbers if the document was loaded with line numbers enabled.

    The following simple example illustrates using an error listener during validation.

    // Create an XmlOptions instance and set the error listener.
    XmlOptions validateOptions = new XmlOptions();
    ArrayList errorList = new ArrayList();
    validateOptions.setErrorListener(errorList);
    
    // Validate the XML.
    boolean isValid = newEmp.validate(validateOptions);
    
    // If the XML isn't valid, loop through the listener's contents,
    // printing contained messages.
    if (!isValid)
    {
         for (int i = 0; i < errorList.size(); i++)
         {
             XmlError error = (XmlError)errorList.get(i);
             
             System.out.println("\n");
             System.out.println("Message: " + error.getMessage() + "\n");
             System.out.println("Location of invalid XML: " + 
                 error.getCursorLocation().xmlText() + "\n");
         }
    }
    
 public XmlOptions setGenerateJavaVersion(String source) 
    If this option is set, then the schema compiler will print java code that is compatible with the desired Java version. If not set, the current Java version is used. Currently, only "1.4" and "1.5" are supported.
 public XmlOptions setLoadAdditionalNamespaces(Map nses) 
    Set additional namespace mappings to be added when parsing a document.
 public XmlOptions setLoadLineNumbers() 
    If this option is set, line number annotations are placed in the store when parsing a document. This is particularly useful when you want XmlError objects to contain line numbers.
    Note: This adds line numbers info only for start tags. For line number info on end tags use: XmlOptions#setLoadLineNumbers(java.lang.String)
    Example: xmlOptions.setLoadLineNumbers(XmlOptions.LOAD_LINE_NUMBERS_END_ELEMENT)
 public XmlOptions setLoadLineNumbers(String option) 
    If this option is set, line number annotations are placed in the store when parsing a document. This is particularly useful when you want XmlError objects to contain line numbers. Use the option to load line numbers at the end of an element.
    Example: xmlOptions.setLoadLineNumbers(XmlOptions.LOAD_LINE_NUMBERS_END_ELEMENT)
 public XmlOptions setLoadMessageDigest() 
    If this option is set when loading from an InputStream or File, then the loader will compute a 160-bit SHA-1 message digest of the XML file while loading it and make it available via XmlObject.documentProperties().getMessageDigest();
    The schema compiler uses message digests to detect and eliminate duplicate imported xsd files.
 public XmlOptions setLoadReplaceDocumentElement(QName replacement) 
    If this option is set, the document element is replaced with the given QName when parsing. If null is supplied, the document element is removed.
 public XmlOptions setLoadStripComments() 
    If this option is set, all comments are stripped when parsing a document.
 public XmlOptions setLoadStripProcinsts() 
    If this option is set, all processing instructions are stripped when parsing a document.
 public XmlOptions setLoadStripWhitespace() 
    If this option is set, all insignificant whitespace is stripped when parsing a document. Can be used to save memory on large documents when you know there is no mixed content.
 public XmlOptions setLoadSubstituteNamespaces(Map substNamespaces) 
    This option sets a map of namespace uri substitutions that happen when parsing a document.

    This is particularly useful if you have documents that use no namespace, but you wish to avoid the name collision problems that occur when you introduce schema definitions without a target namespace.

    By mapping the empty string "" (the absence of a URI) to a specific namespace, you can force the parser to behave as if a no-namespace document were actually in the specified namespace. This allows you to type the instance according to a schema in a nonempty namespace, and therefore avoid the problematic practice of using schema definitions without a target namespace.

 public XmlOptions setLoadTrimTextBuffer() 
    If this option is set, the underlying xml text buffer is trimmed immediately after parsing a document resulting in a smaller memory footprint. Use this option if you are loading a large number of unchanging documents that will stay in memory for some time.
 public XmlOptions setLoadUseDefaultResolver() 
    By default, XmlBeans does not resolve entities when parsing xml documents (unless an explicit entity resolver is specified). Use this option to turn on entity resolving by default.
 public XmlOptions setLoadUseXMLReader(XMLReader xmlReader) 
    By default, XmlBeans uses an internal Piccolo parser, other parsers can be used by providing an XMLReader. For using the default JDK's SAX parser use: xmlOptions.setLoadUseXMLReader( SAXParserFactory.newInstance().newSAXParser().getXMLReader() );
 public XmlOptions setSaveAggresiveNamespaces() 
Deprecated! replaced - by #setSaveAggressiveNamespaces

 public XmlOptions setSaveAggressiveNamespaces() 
    Causes the saver to reduce the number of namespace prefix declarations. The saver will do this by passing over the document twice, first to collect the set of needed namespace declarations, and then second to actually save the document with the declarations collected at the root.
 public XmlOptions setSaveCDataEntityCountThreshold(int cdataEntityCountThreshold) 
    This option controls when saving will use CDATA blocks. CDATA will be used if the folowing condition is true:
    textLength > cdataLengthThreshold && entityCount > cdataEntityCountThreshold
    The default value of cdataEntityCountThreshold is 5.
 public XmlOptions setSaveCDataLengthThreshold(int cdataLengthThreshold) 
    This option controls when saving will use CDATA blocks. CDATA will be used if the folowing condition is true:
    textLength > cdataLengthThreshold && entityCount > cdataEntityCountThreshold
    The default value of cdataLengthThreshold is 32.

    Use the folowing values for these cases:
    Scenario cdataLengthThreshold cdataEntityCountThreshold
    Every text is CDATA 0 -1
    Only text that has an entity is CDATA 0 0
    Only text longer than x chars is CDATA x -1
    Only text that has y entitazable chars is CDATA 0 y
    Only text longer than x chars and has y entitazable chars is CDATA x y
 public XmlOptions setSaveFilterProcinst(String filterProcinst) 
    This option causes the saver to filter a Processing Instruction with the given target
 public XmlOptions setSaveImplicitNamespaces(Map implicitNamespaces) 
    If namespaces have already been declared outside the scope of the fragment being saved, this allows those mappings to be passed down to the saver, so the prefixes are not re-declared.
 public XmlOptions setSaveInner() 
    This option controls whether saving begins on the element or its contents
 public XmlOptions setSaveNamespacesFirst() 
    This option will cause the saver to save namespace attributes first.
 public XmlOptions setSaveNoXmlDecl() 
    This option controls whether saving saves out the XML declaration (
 public XmlOptions setSaveOuter() 
    This option controls whether saving begins on the element or its contents
 public XmlOptions setSavePrettyPrint() 
    This option will cause the saver to reformat white space for easier reading.
 public XmlOptions setSavePrettyPrintIndent(int indent) 
    When used with setSavePrettyPrint this sets the indent amount to use.
 public XmlOptions setSavePrettyPrintOffset(int offset) 
    When used with setSavePrettyPrint this sets the offset amount to use.
 public XmlOptions setSaveSaxNoNSDeclsInAttributes() 
    This option controls whether namespace declarations are included as attributes in the startElement event. By default, up to and including XMLBeans 2.3.0 they were included, in subsequent versions, they are no longer included.
 public XmlOptions setSaveSubstituteCharacters(XmlOptionCharEscapeMap characterReplacementMap) 
    This option causes the saver to replace characters with other values in the output stream. It is intended to be used for escaping non-standard characters during output.
 public XmlOptions setSaveSuggestedPrefixes(Map suggestedPrefixes) 
    A map of hints to pass to the saver for which prefixes to use for which namespace URI.
 public XmlOptions setSaveSyntheticDocumentElement(QName name) 
    This option causes the saver to wrap the current fragment in an element with the given name.
 public XmlOptions setSaveUseOpenFrag() 
    When saving a fragment, this option changes the qname of the synthesized root element. Normally <xml-fragment> is used.
 public XmlOptions setSchemaCodePrinter(SchemaCodePrinter printer) 
    If this option is set when compiling a schema, then the given SchemaTypeCodePrinter.Printer will be used to generate the Java code.
 public XmlOptions setUnsynchronized() 
    This option controls whether or not operations on XmlBeans are thread safe. When not on, all XmlBean operations will be syncronized. This provides for multiple thread the ability to access a single XmlBeans simultainously, but has a perf impact. If set, then only one thread may access an XmlBean.
 public XmlOptions setUseCDataBookmarks() 

    Use this option when parsing and saving XML documents.

    For parsing this option will annotate the text fields in the store with CDataBookmark.

    For saving this option will save the text fields annotated with CDataBookmark as CDATA XML text.
    Note: The SaveCDataEntityCountThreshold and SaveCDataLengthThreshold options and their default values still apply.

    Note: Due to the store representation, a CDATA will not be recognized if it is imediately after non CDATA text and all text following it will be considered CDATA.
    Example:

    <a><![CDATA[cdata text]]></a>               - is considered as: <a><![CDATA[cdata text]]></a>
    <b><![CDATA[cdata text]]> regular text</b>  - is considered as: <b><![CDATA[cdata text regular text]]></b>
    <c>text <![CDATA[cdata text]]></c>          - is considered as: <c>text cdata text</c>
    

    Sample code:

    String xmlText = "<a>\n" +
    "<a><![CDATA[cdata text]]></a>\n" +
    "<b><![CDATA[cdata text]]> regular text</b>\n" +
    "<c>text <![CDATA[cdata text]]></c>\n" +
    "</a>";
    System.out.println(xmlText);
    XmlOptions opts = new XmlOptions();
    opts.setUseCDataBookmarks();
    XmlObject xo = XmlObject.Factory.parse( xmlText , opts);
    System.out.println("xo1:\n" + xo.xmlText(opts));
    System.out.println("\n");
    opts.setSavePrettyPrint();
    System.out.println("xo2:\n" + xo.xmlText(opts));
    

 public XmlOptions setUseDefaultNamespace() 
    If this option is set, the saver will try to use the default namespace for the most commonly used URI. If it is not set the saver will always created named prefixes.
 public XmlOptions setValidateOnSet() 
    If this option is set when an instance is created, then value facets will be checked on each call to a setter or getter method on instances of XmlObject within the instance document. If the facets are not satisfied, then an unchecked exception is thrown immediately. This option is useful for finding code that is introducing invalid values in an XML document, but it slows performance.
 public XmlOptions setValidateStrict() 
    Performs additional validation checks that are disabled by default for better compatibility.
 public XmlOptions setValidateTreatLaxAsSkip() 
    Instructs the validator to skip elements matching an particle with contentModel="lax". This is useful because, in certain situations, XmlBeans will find types on the classpath that the document author did not anticipate.
 public XmlOptions setXqueryCurrentNodeVar(String varName) 
    Sets the name of the variable that represents the current node in a query expression.
 public XmlOptions setXqueryVariables(Map varMap) 
    Map the names and values of external variables in an xquery expression. The keys of the map are the variable names in the query without the '$' prefix. The values of the map are objects and can be any of the primitive wrapper classes, String, XmlObject, or XmlCursor. The mapping only applies to xquery and has no effect on xpath expressions.