Package net.sf.saxon.lib

## Class AugmentedSource

- java.lang.Object
- - net.sf.saxon.lib.AugmentedSource

- All Implemented Interfaces:
    `javax.xml.transform.Source`

      public class AugmentedSource
      extends java.lang.Object
      implements javax.xml.transform.Source

  This class is an extension of the JAXP Source interface. The class can be used wherever a JAXP Source object can be used, and it provides additional information about the way that the Source is to be processed: for example, it indicates whether or not it should be validated against a schema. Other options that can be set include the SAX XMLReader to be used, and the choice of whether a source in the form of an existing tree should be copied or wrapped.

  Internally, an AugmentedSource combines an underlying Source object with a `ParseOptions` object holding the selected options. Many Saxon interfaces allow the ParseOptions to be supplied directly, making this class unnecessary; but it is useful when passing a Source to a JAXP interface that does not allow further options to be supplied.

  Note that in general a `Source` object can only be used once; it is consumed by use. An augmentedSource object is consumed by use if the underlying source object is consumed by use.

  Since:
    8.8

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `AugmentedSource​(javax.xml.transform.Source source, ParseOptions options)` | Create an AugmentedSource that wraps a given Source object (which must not itself be an AugmentedSource), with supplied ParseOptions

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addFilter​(FilterFactory filter)` | Add a filter to the list of filters to be applied to the raw input
    `void` | `close()` | Close any resources held by this Source.
    `javax.xml.transform.Source` | `getContainedSource()` | Get the Source object wrapped by this AugmentedSource
    `int` | `getDTDValidation()` | Get whether or not DTD validation of this source is required
    `org.xml.sax.EntityResolver` | `getEntityResolver()` | Get the EntityResolver that will be used when parsing
    `ErrorReporter` | `getErrorReporter()` | Get the ErrorReporter that will be used when parsing
    `java.util.List<FilterFactory>` | `getFilters()` | Get the list of filters to be applied to the input.
    `TreeModel` | `getModel()` | Get the tree model that will be used.
    `ParseOptions` | `getParseOptions()` | Get the ParseOptions defined in this AugmentedSource
    `int` | `getSchemaValidation()` | Get whether or not schema validation of this source is required
    `java.lang.String` | `getSystemId()` | Get the System ID.
    `StructuredQName` | `getTopLevelElement()` | Get the name of the top-level element for validation.
    `SchemaType` | `getTopLevelType()` | Get the type of the document element for validation.
    `java.lang.Boolean` | `getWrapDocument()` | Assuming that the contained Source is a node in a tree, determine whether a tree will be created as a view of this supplied tree, or as a copy.
    `org.xml.sax.XMLReader` | `getXMLReader()` | Get the SAX parser (XMLReader) to be used
    `boolean` | `isLineNumbering()` | Get whether line numbers are to be maintained in the constructed document
    `boolean` | `isLineNumberingSet()` | Determine whether setLineNumbering() has been called
    `boolean` | `isPleaseCloseAfterUse()` | Determine whether or not the user of this Source is encouraged to close it as soon as reading is finished.
    `boolean` | `isXIncludeAware()` | Get state of XInclude processing.
    `boolean` | `isXIncludeAwareSet()` | Determine whether setXIncludeAware() has been called.
    `static AugmentedSource` | `makeAugmentedSource​(javax.xml.transform.Source source)` | Create an AugmentedSource that wraps a given Source object.
    `void` | `setDTDValidationMode​(int option)` | Set whether or not DTD validation of this source is required
    `void` | `setEntityResolver​(org.xml.sax.EntityResolver resolver)` | Set an EntityResolver to be used when parsing.
    `void` | `setErrorReporter​(ErrorReporter listener)` | Set an ErrorReporter to be used when parsing
    `void` | `setLineNumbering​(boolean lineNumbering)` | Set whether line numbers are to be maintained in the constructed document
    `void` | `setModel​(TreeModel model)` | Set the tree model to use.
    `void` | `setPleaseCloseAfterUse​(boolean close)` | Set whether or not the user of this Source is encouraged to close it as soon as reading is finished.
    `void` | `setSchemaValidationMode​(int option)` | Set whether or not schema validation of this source is required
    `void` | `setSystemId​(java.lang.String id)` | Set the System ID.
    `void` | `setTopLevelElement​(StructuredQName elementName)` | Set the name of the top-level element for validation.
    `void` | `setTopLevelType​(SchemaType type)` | Set the type of the top-level element for validation.
    `void` | `setWrapDocument​(java.lang.Boolean wrap)` | Assuming that the contained Source is a node in a tree, indicate whether a tree should be created as a view of this supplied tree, or as a copy.
    `void` | `setXIncludeAware​(boolean state)` | Set state of XInclude processing.
    `void` | `setXMLReader​(org.xml.sax.XMLReader parser)` | Set the SAX parser (XMLReader) to be used

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface javax.xml.transform.Source

      `isEmpty`

- - ### Constructor Detail

    - #### AugmentedSource

          public AugmentedSource​(javax.xml.transform.Source source,
                                 ParseOptions options)

      Create an AugmentedSource that wraps a given Source object (which must not itself be an AugmentedSource), with supplied ParseOptions
      Parameters:
        `source` - the Source object to be wrapped. This must be an implementation of Source that Saxon recognizes, or an implementation for which a `SourceResolver` has been registered with the `Configuration`. The source must not itself be an AugmentedSource.

        As an alternative to this constructor, consider using the factory method `makeAugmentedSource(javax.xml.transform.Source)`, which does accept any kind of Source including an AugmentedSource as input.

        `options` - the ParseOptions to be used. This object may be subsequently modified and the changes will be effective; furthermore, methods on the AugumentedSource will modify the supplied ParseOptions.
      Throws:
        `java.lang.IllegalArgumentException` - if the wrapped source is an AugmentedSource
      Since:
        8.8

  - ### Method Detail

    - #### makeAugmentedSource

          public static AugmentedSource makeAugmentedSource​(javax.xml.transform.Source source)

      Create an AugmentedSource that wraps a given Source object. If this is already an AugmentedSource, the original AugmentedSource is returned. Note that this means that setting any properties on the returned AugmentedSource will also affect the original.
      Parameters:
        `source` - the Source object to be wrapped
      Returns:
        an AugmentedSource
      Since:
        8.8

    - #### addFilter

          public void addFilter​(FilterFactory filter)

      Add a filter to the list of filters to be applied to the raw input
      Parameters:
        `filter` - a factory for the filter to be added

    - #### getFilters

          public java.util.List<FilterFactory> getFilters()

      Get the list of filters to be applied to the input. Returns null if there are no filters.
      Returns:
        the list of filters, if there are any

    - #### getContainedSource

          public javax.xml.transform.Source getContainedSource()

      Get the Source object wrapped by this AugmentedSource
      Returns:
        the contained Source object
      Since:
        8.8

    - #### getParseOptions

          public ParseOptions getParseOptions()

      Get the ParseOptions defined in this AugmentedSource
      Returns:
        the ParseOptions, a bundle of options equivalent to obtaining all the properties individually. Changes to this object will be live, that is, they will affect the AugmentedSource from which they came.

    - #### setModel

          public void setModel​(TreeModel model)

      Set the tree model to use. Default is the tiny tree
      Parameters:
        `model` - typically one of the constants `TreeModel.TINY_TREE`, `TreeModel.TINY_TREE_CONDENSED`, or `TreeModel.LINKED_TREE`. However, in principle a user-defined tree model can be used.
      Since:
        9.2

    - #### getModel

          public TreeModel getModel()

      Get the tree model that will be used.
      Returns:
        typically one of the constants `TreeModel.TINY_TREE`, `TreeModel.TINY_TREE_CONDENSED`, or `TreeModel.LINKED_TREE`. However, in principle a user-defined tree model can be used.
      Since:
        9.2

    - #### setSchemaValidationMode

          public void setSchemaValidationMode​(int option)

      Set whether or not schema validation of this source is required
      Parameters:
        `option` - one of `Validation.STRICT`, `Validation.LAX`, `Validation.STRIP`, `Validation.PRESERVE`, `Validation.DEFAULT`
      Since:
        8.8

    - #### getSchemaValidation

          public int getSchemaValidation()

      Get whether or not schema validation of this source is required
      Returns:
        the validation mode requested, or `Validation.DEFAULT` to use the default validation mode from the Configuration.
      Since:
        8.8

    - #### setTopLevelElement

          public void setTopLevelElement​(StructuredQName elementName)

      Set the name of the top-level element for validation. If a top-level element is set then the document being validated must have this as its outermost element
      Parameters:
        `elementName` - the QName of the required top-level element, or null to unset the value
      Since:
        9.0. Type of argument changed in 9.5.

    - #### getTopLevelElement

          public StructuredQName getTopLevelElement()

      Get the name of the top-level element for validation. If a top-level element is set then the document being validated must have this as its outermost element
      Returns:
        the QName of the required top-level element, or null if no value is set
      Since:
        9.0. Type of result changed in 9.5.

    - #### setTopLevelType

          public void setTopLevelType​(SchemaType type)

      Set the type of the top-level element for validation. If this is set then the document element is validated against this type
      Parameters:
        `type` - the schema type required for the document element, or null to unset the value
      Since:
        9.0

    - #### getTopLevelType

          public SchemaType getTopLevelType()

      Get the type of the document element for validation. If this is set then the document element of the document being validated must have this type
      Returns:
        the type of the required top-level element, or null if no value is set
      Since:
        9.0

    - #### setDTDValidationMode

          public void setDTDValidationMode​(int option)

      Set whether or not DTD validation of this source is required
      Parameters:
        `option` - one of `Validation.STRICT`, `Validation.STRIP`, `Validation.DEFAULT`
      Since:
        8.8

    - #### getDTDValidation

          public int getDTDValidation()

      Get whether or not DTD validation of this source is required
      Returns:
        the validation mode requested, or `Validation.DEFAULT` to use the default validation mode from the Configuration.
      Since:
        8.8

    - #### setLineNumbering

          public void setLineNumbering​(boolean lineNumbering)

      Set whether line numbers are to be maintained in the constructed document
      Parameters:
        `lineNumbering` - true if line numbers are to be maintained
      Since:
        8.8

    - #### isLineNumbering

          public boolean isLineNumbering()

      Get whether line numbers are to be maintained in the constructed document
      Returns:
        true if line numbers are maintained
      Since:
        8.8

    - #### isLineNumberingSet

          public boolean isLineNumberingSet()

      Determine whether setLineNumbering() has been called
      Returns:
        true if setLineNumbering() has been called
      Since:
        8.9

    - #### setXMLReader

          public void setXMLReader​(org.xml.sax.XMLReader parser)

      Set the SAX parser (XMLReader) to be used
      Parameters:
        `parser` - the SAX parser
      Since:
        8.8

    - #### getXMLReader

          public org.xml.sax.XMLReader getXMLReader()

      Get the SAX parser (XMLReader) to be used
      Returns:
        the parser
      Since:
        8.8

    - #### setWrapDocument

          public void setWrapDocument​(java.lang.Boolean wrap)

      Assuming that the contained Source is a node in a tree, indicate whether a tree should be created as a view of this supplied tree, or as a copy.

      This option is used only when the Source is supplied to an interface such as the JAXP Transformer.transform() method where there is no other way of indicating whether a supplied external document should be wrapped or copied. It is not used when the Source is supplied to a Saxon-defined interface.

      Parameters:
        `wrap` - if true, the node in the supplied Source is wrapped, to create a view. If false, the node and its contained subtree is copied. If null, the system default is chosen.
      Since:
        8.8

    - #### getWrapDocument

          public java.lang.Boolean getWrapDocument()

      Assuming that the contained Source is a node in a tree, determine whether a tree will be created as a view of this supplied tree, or as a copy.

      This option is used only when the Source is supplied to an interface such as the JAXP Transformer.transform() method where there is no other way of indicating whether a supplied external document should be wrapped or copied. It is not used when the Source is supplied to a Saxon-defined interface.

      Returns:
        if true, the node in the supplied Source is wrapped, to create a view. If false, the node and its contained subtree is copied. If null, the system default is chosen.
      Since:
        8.8

    - #### setSystemId

          public void setSystemId​(java.lang.String id)

      Set the System ID. This sets the System Id to be returned by getSystemId.
      Specified by:
        `setSystemId` in interface `javax.xml.transform.Source`
      Parameters:
        `id` - the System ID. This provides a base URI for the document, and also the result of the document-uri() function
      Since:
        8.8, changed in 9.7 it no longer modifies the original source object

    - #### getSystemId

          public java.lang.String getSystemId()

      Get the System ID. Returns the System Id set by setSystemId if available, or the System Id on the underlying Source object otherwise.
      Specified by:
        `getSystemId` in interface `javax.xml.transform.Source`
      Returns:
        the System ID: effectively the base URI.
      Since:
        8.8

    - #### setXIncludeAware

          public void setXIncludeAware​(boolean state)

      Set state of XInclude processing.

      If XInclude markup is found in the document instance, should it be processed as specified in XML Inclusions (XInclude) Version 1.0.

      XInclude processing defaults to `false`.

      Parameters:
        `state` - Set XInclude processing to `true` or `false`
      Since:
        8.9

    - #### isXIncludeAwareSet

          public boolean isXIncludeAwareSet()

      Determine whether setXIncludeAware() has been called.

      Returns:
        true if setXIncludeAware() has been called
      Since:
        8.9

    - #### isXIncludeAware

          public boolean isXIncludeAware()

      Get state of XInclude processing.

      Returns:
        current state of XInclude processing. Default value is false.
      Since:
        8.9

    - #### setEntityResolver

          public void setEntityResolver​(org.xml.sax.EntityResolver resolver)

      Set an EntityResolver to be used when parsing. Note this is used only when a system-allocated parser is used; when a user-supplied parser is used (for example in a SAXSource), the EntityResolver should be preinitialized.
      Parameters:
        `resolver` - the EntityResolver to be used
      Since:
        8.9. The method had no useful effect in releases prior to 9.2.

    - #### getEntityResolver

          public org.xml.sax.EntityResolver getEntityResolver()

      Get the EntityResolver that will be used when parsing
      Returns:
        the EntityResolver, if one has been set using `setEntityResolver(org.xml.sax.EntityResolver)`, otherwise null.
      Since:
        8.9 The method had no useful effect in releases prior to 9.2.

    - #### setErrorReporter

          public void setErrorReporter​(ErrorReporter listener)

      Set an ErrorReporter to be used when parsing
      Parameters:
        `listener` - the ErrorReporter to be used
      Since:
        8.9. Changed in 10.0 to use an ErrorReporter rather than ErrorListener

    - #### getErrorReporter

          public ErrorReporter getErrorReporter()

      Get the ErrorReporter that will be used when parsing
      Returns:
        the ErrorReporter, if one has been set using `setErrorReporter(net.sf.saxon.lib.ErrorReporter)`, otherwise null.
      Since:
        8.9. Changed in 10.0 to use an ErrorReporter rather than ErrorListener

    - #### setPleaseCloseAfterUse

          public void setPleaseCloseAfterUse​(boolean close)

      Set whether or not the user of this Source is encouraged to close it as soon as reading is finished. Normally the expectation is that any Stream in a StreamSource will be closed by the component that created the Stream. However, in the case of a Source returned by a URIResolver, there is no suitable interface (the URIResolver has no opportunity to close the stream). Also, in some cases such as reading of stylesheet modules, it is possible to close the stream long before control is returned to the caller who supplied it. This tends to make a difference on .NET, where a file often can't be opened if there is a stream attached to it.
      Parameters:
        `close` - true if the source should be closed as soon as it has been consumed
      Since:
        8.8

    - #### isPleaseCloseAfterUse

          public boolean isPleaseCloseAfterUse()

      Determine whether or not the user of this Source is encouraged to close it as soon as reading is finished.
      Returns:
        true if the source should be closed as soon as it has been consumed
      Since:
        8.8

    - #### close

          public void close()

      Close any resources held by this Source. This only works if the underlying Source is one that is recognized as holding closable resources.
      Since:
        8.8