# com.bea.xml
XmlOptions Class

public class XmlOptions
extends `Object`
implements `Serializable`

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)));

Hierarchy
  `Object`
  `XmlOptions`

All Implemented Interfaces
  `Serializable`

## Field Summary

## Constructor Summary

XmlOptions() Construct a new blank XmlOptions.
XmlOptions(`XmlOptions` other) Construct a new XmlOptions, copying the options.

## Method Summary

`public `Object`` | `get`(`Object` option) Used to get a generic option
`public boolean` | `hasOption`(`Object` option) Used to test a generic option
`public static `XmlOptions`` | `maskNull`(`XmlOptions` o) If passed null, returns an empty options object.
`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 static `Object`` | `safeGet`(`XmlOptions` o, `Object` option) Used to test a generic option on an options object that may be null
`public `XmlOptions`` | `setCharacterEncoding`(`String` encoding) When parsing or 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.
`public `XmlOptions`` | `setCompileNoPvrRule`() If this option is set, the particle valid (restriciton) rule is not enforced when building a `SchemaTypeSystem`.
`public `XmlOptions`` | `setCompileNoUpaRule`() If this option is set, the unique particle attribution rule is not enforced when building a `SchemaTypeSystem`.
`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.
`public `XmlOptions`` | `setDocumentType`(`SchemaType` type) When parsing a document, this sets the type of the root element.
`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.
`public `XmlOptions`` | `setErrorListener`(`Collection` c) Sets a collection object for collecting `XmlError``` objects during parsing, validation, and compilation.
`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.
`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.
`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.
`public `XmlOptions`` | `setLoadSubstituteNamespaces`(`Map` substNamespaces) This option sets a map of namespace uri substitutions that happen when parsing a document.
`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.
`public `XmlOptions`` | `setSaveAggresiveNamespaces`() Causes the saver to reduce the number of namespace prefix declarations.
`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`` | `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`` | `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.
`public `XmlOptions`` | `setUseDefaultNamespace`() If this option is set, the saver will try to use the default namespace for the most commonly used URI.
`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.
`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.

Methods from class `java.lang.`Object``
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Detail

## Constructor Detail

### XmlOptions

    public XmlOptions()

  Construct a new blank XmlOptions.

### XmlOptions

    public XmlOptions(XmlOptions other)

  Construct a new XmlOptions, copying the options.

## Method Detail

### get(Object) Method

    public Object get(Object option)

Used to get a generic option

### hasOption(Object) Method

    public boolean hasOption(Object option)

Used to test a generic option

### maskNull(XmlOptions) Method

    public static XmlOptions maskNull(XmlOptions o)

If passed null, returns an empty options object. Otherwise, returns its argument.

### put(Object) Method

    public void put(Object option)

Used to set a generic option

### put(Object, Object) Method

    public void put(Object option,
                    Object value)

Used to set a generic option

### put(Object, int) Method

    public void put(Object option,
                    int value)

Used to set a generic option

### safeGet(XmlOptions, Object) Method

    public static Object safeGet(XmlOptions o,
                                 Object option)

Used to test a generic option on an options object that may be null

### setCharacterEncoding(String) Method

    public XmlOptions setCharacterEncoding(String encoding)

When parsing or writing a document, this sets the character encoding to use.

#### Parameters

encoding
  the character encoding

Related Topics

``XmlObject.Factory.parse(File, XmlOptions)``
``XmlTokenSource.save(File, XmlOptions)``

### setCompileDownloadUrls() Method

    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.

Related Topics

``XmlBeans.compileXsd(XmlObject[], SchemaTypeLoader, XmlOptions)``

### setCompileMdefNamespaces(Set) Method

    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.

#### Parameters

mdefNamespaces
  a set of namespace URIs as Strings

Related Topics

``XmlBeans.compileXsd(XmlObject[], SchemaTypeLoader, XmlOptions)``

### setCompileNoPvrRule() Method

    public XmlOptions setCompileNoPvrRule()

If this option is set, the particle valid (restriciton) rule is not enforced when building a `SchemaTypeSystem`. See Section 3.9.6 of the XML Schema specification for information on the PVR rule.

Related Topics

``XmlBeans.compileXsd(XmlObject[], SchemaTypeLoader, XmlOptions)``

### setCompileNoUpaRule() Method

    public XmlOptions setCompileNoUpaRule()

If this option is set, the unique particle attribution rule is not enforced when building a `SchemaTypeSystem`. See Appendix H of the XML Schema specification for information on the UPA rule.

Related Topics

``XmlBeans.compileXsd(XmlObject[], SchemaTypeLoader, XmlOptions)``

### setCompileNoValidation() Method

    public XmlOptions setCompileNoValidation()

If this option is set, validation is not done on the Schema XmlBeans when building a `SchemaTypeSystem`

Related Topics

``XmlBeans.compileXsd(XmlObject[], SchemaTypeLoader, XmlOptions)``

### setCompileSubstituteNames(Map) Method

    public XmlOptions setCompileSubstituteNames(Map nameMap)

This option allows for `QName` substitution during schema compilation.

#### Parameters

nameMap
  a map from `QName`s to substitute `QName`s.

Related Topics

``XmlBeans.compileXsd(XmlObject[], SchemaTypeLoader, XmlOptions)``

### setDocumentSourceName(String) Method

    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.

Related Topics

``XmlObject.Factory.parse(String, XmlOptions)``

### setDocumentType(SchemaType) Method

    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`.

#### Parameters

type
  The root element's document type.

Related Topics

``XmlObject.Factory.parse(File, XmlOptions)``

### setEntityResolver(EntityResolver) Method

    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.

Related Topics

``XmlBeans.compileXsd(XmlObject[], SchemaTypeLoader, XmlOptions)``

### setErrorListener(Collection) Method

    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");
          }
     }

#### Parameters

c
  A collection that will be filled with `XmlError``` objects via `Collection.add(Object)```

Related Topics

``XmlError``
``XmlObject.Factory.parse(File, XmlOptions)``
``XmlObject.validate(XmlOptions)``
``XmlBeans.compileXsd(XmlObject[], SchemaTypeLoader, XmlOptions)``
``XmlOptions.setLoadLineNumbers()``

### setLoadAdditionalNamespaces(Map) Method

    public XmlOptions setLoadAdditionalNamespaces(Map nses)

Set additional namespace mappings to be added when parsing a document.

#### Parameters

nses
  additional namespace mappings

Related Topics

``XmlObject.Factory.parse(File, XmlOptions)``

### setLoadLineNumbers() Method

    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.

Related Topics

``XmlObject.Factory.parse(File, XmlOptions)``
``XmlError``

### setLoadMessageDigest() Method

    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.

Related Topics

``XmlObject.Factory.parse(File, XmlOptions)``

### setLoadReplaceDocumentElement(QName) Method

    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.

Related Topics

``XmlObject.Factory.parse(File, XmlOptions)``

### setLoadStripComments() Method

    public XmlOptions setLoadStripComments()

If this option is set, all comments are stripped when parsing a document.

Related Topics

``XmlObject.Factory.parse(File, XmlOptions)``

### setLoadStripProcinsts() Method

    public XmlOptions setLoadStripProcinsts()

If this option is set, all processing instructions are stripped when parsing a document.

Related Topics

``XmlObject.Factory.parse(File, XmlOptions)``

### setLoadStripWhitespace() Method

    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.

Related Topics

``XmlObject.Factory.parse(File, XmlOptions)``

### setLoadSubstituteNamespaces(Map) Method

    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.

#### Parameters

substNamespaces
  a map of document URIs to replacement URIs

Related Topics

``XmlObject.Factory.parse(File, XmlOptions)``

### setLoadTrimTextBuffer() Method

    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.

Related Topics

``XmlObject.Factory.parse(File, XmlOptions)``

### setSaveAggresiveNamespaces() Method

    public XmlOptions setSaveAggresiveNamespaces()

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.

Related Topics

``XmlTokenSource.save(File, XmlOptions)``
``XmlTokenSource.xmlText(XmlOptions)``

### setSaveFilterProcinst(String) Method

    public XmlOptions setSaveFilterProcinst(String filterProcinst)

This option causes the saver to filter a Processing Instruction with the given target

#### Parameters

filterProcinst
  the name of a Processing Instruction to filter on save

Related Topics

``XmlTokenSource.save(File, XmlOptions)``
``XmlTokenSource.xmlText(XmlOptions)``

### setSaveImplicitNamespaces(Map) Method

    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.

#### Parameters

implicitNamespaces
  a map of prefixes to uris that can be used by the saver without being declared

Related Topics

``XmlTokenSource.save(File, XmlOptions)``
``XmlTokenSource.xmlText(XmlOptions)``

### setSaveInner() Method

    public XmlOptions setSaveInner()

This option controls whether saving begins on the element or its contents

Related Topics

``XmlTokenSource.save(File, XmlOptions)``
``XmlTokenSource.xmlText(XmlOptions)``

### setSaveNamespacesFirst() Method

    public XmlOptions setSaveNamespacesFirst()

This option will cause the saver to save namespace attributes first.

Related Topics

``XmlTokenSource.save(File, XmlOptions)``
``XmlTokenSource.xmlText(XmlOptions)``

### setSaveOuter() Method

    public XmlOptions setSaveOuter()

This option controls whether saving begins on the element or its contents

Related Topics

``XmlTokenSource.save(File, XmlOptions)``
``XmlTokenSource.xmlText(XmlOptions)``

### setSavePrettyPrint() Method

    public XmlOptions setSavePrettyPrint()

This option will cause the saver to reformat white space for easier reading.

Related Topics

``XmlTokenSource.save(File, XmlOptions)``
``XmlTokenSource.xmlText(XmlOptions)``

### setSavePrettyPrintIndent(int) Method

    public XmlOptions setSavePrettyPrintIndent(int indent)

When used with `setSavePrettyPrint` this sets the indent amount to use.

#### Parameters

indent
  the indent amount to use

Related Topics

``XmlOptions.setSavePrettyPrint()``
``XmlTokenSource.save(File, XmlOptions)``
``XmlTokenSource.xmlText(XmlOptions)``

### setSavePrettyPrintOffset(int) Method

    public XmlOptions setSavePrettyPrintOffset(int offset)

When used with `setSavePrettyPrint` this sets the offset amount to use.

#### Parameters

offset
  the offset amount to use

Related Topics

``XmlOptions.setSavePrettyPrint()``
``XmlTokenSource.save(File, XmlOptions)``
``XmlTokenSource.xmlText(XmlOptions)``

### setSaveSuggestedPrefixes(Map) Method

    public XmlOptions setSaveSuggestedPrefixes(Map suggestedPrefixes)

A map of hints to pass to the saver for which prefixes to use for which namespace URI.

#### Parameters

suggestedPrefixes
  a map from URIs to prefixes

Related Topics

``XmlTokenSource.save(File, XmlOptions)``
``XmlTokenSource.xmlText(XmlOptions)``

### setSaveSyntheticDocumentElement(QName) Method

    public XmlOptions setSaveSyntheticDocumentElement(QName name)

This option causes the saver to wrap the current fragment in an element with the given name.

#### Parameters

name
  the name to use for the top level element

Related Topics

``XmlTokenSource.save(File, XmlOptions)``
``XmlTokenSource.xmlText(XmlOptions)``

### setSaveUseOpenFrag() Method

    public XmlOptions setSaveUseOpenFrag()

When saving a fragment, this option changes the qname of the synthesized root element. Normally <xml-fragment> is used.

Related Topics

``XmlTokenSource.save(File, XmlOptions)``
``XmlTokenSource.xmlText(XmlOptions)``

### setUseDefaultNamespace() Method

    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.

Related Topics

``XmlTokenSource.save(File, XmlOptions)``
``XmlTokenSource.xmlText(XmlOptions)``

### setValidateOnSet() Method

    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.

Related Topics

``XmlObject.Factory.parse(File, XmlOptions)``

### setXqueryCurrentNodeVar(String) Method

    public XmlOptions setXqueryCurrentNodeVar(String varName)

Sets the name of the variable that represents the current node in a query expression.

#### Parameters

varName
  The new variable name to use for the query.

Related Topics

``XmlObject.execQuery(String)``
``XmlCursor.execQuery(String)``

### setXqueryVariables(Map) Method

    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.

#### Parameters

varMap
  a map from `String`s to variable instances.

Related Topics

``XmlObject.execQuery(String)``
``XmlCursor.execQuery(String)``