net.sf.saxon.lib
Class AugmentedSource

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

All Implemented Interfaces:

Source

public class AugmentedSource
extends Object
implements 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.

Since:

8.8

Method Summary

void	addFilter(ProxyReceiver 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.
Source	getContainedSource() Get the Source object wrapped by this AugmentedSource
int	getDTDValidation() Get whether or not DTD validation of this source is required
EntityResolver	getEntityResolver() Get the EntityResolver that will be used when parsing
ErrorListener	getErrorListener() Get the ErrorListener that will be used when parsing
List	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
int	getStripSpace() Get the space-stripping action to be applied to the source document
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.
int	getTreeModel() Deprecated. since 9.2: use getModel()
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.
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(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(EntityResolver resolver) Set an EntityResolver to be used when parsing.
void	setErrorListener(ErrorListener listener) Set an ErrorListener 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	setStripSpace(int stripAction) Set the space-stripping action to be applied to the source document
void	setSystemId(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	setTreeModel(int model) Deprecated. since 9.2: use setModel(net.sf.saxon.om.TreeModel)
void	setWrapDocument(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(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

Method Detail

makeAugmentedSource

public static AugmentedSource makeAugmentedSource(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(ProxyReceiver filter)

Add a filter to the list of filters to be applied to the raw input

Parameters:

filter - the filter to be added

getFilters

public List 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 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.

setStripSpace

public void setStripSpace(int stripAction)

Set the space-stripping action to be applied to the source document

Parameters:

stripAction - one of Whitespace.IGNORABLE, Whitespace.ALL, or Whitespace.NONE

Since:

8.8

getStripSpace

public int getStripSpace()

Get the space-stripping action to be applied to the source document

Returns:

one of Whitespace.IGNORABLE, Whitespace.ALL, or Whitespace.NONE

Since:

8.8

setTreeModel

public void setTreeModel(int model)

Deprecated. since 9.2: use setModel(net.sf.saxon.om.TreeModel)

Set the tree model to use. Default is the tiny tree

Parameters:

model - one of Builder.TINY_TREE, Builder.TINY_TREE_CONDENSED or Builder.LINKED_TREE

Since:

8.9 (Condensed tree added in 9.2)

getTreeModel

public int getTreeModel()

Deprecated. since 9.2: use getModel()

Get the tree model that will be used.

Returns:

one of Builder.TINY_TREE, Builder.TINY_TREE_CONDENSED, Builder.LINKED_TREE, or {link Builder#UNSPECIFIED_TREE_MODEL} if no call on setTreeModel() has been made

Since:

8.9 (Condensed tree added in 9.2)

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

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

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(XMLReader parser)

Set the SAX parser (XMLReader) to be used

Parameters:

parser - the SAX parser

Since:

8.8

getXMLReader

public XMLReader getXMLReader()

Get the SAX parser (XMLReader) to be used

Returns:

the parser

Since:

8.8

setWrapDocument

public void setWrapDocument(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 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(String id)

Set the System ID. This sets the System Id on the underlying Source object.

Specified by:

setSystemId in interface 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

getSystemId

public String getSystemId()

Get the System ID. This gets the System Id on the underlying Source object.

Specified by:

getSystemId in interface 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(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 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.

setErrorListener

public void setErrorListener(ErrorListener listener)

Set an ErrorListener to be used when parsing

Parameters:

listener - the ErrorListener to be used

Since:

8.9

getErrorListener

public ErrorListener getErrorListener()

Get the ErrorListener that will be used when parsing

Returns:

the ErrorListener, if one has been set using setErrorListener(javax.xml.transform.ErrorListener), otherwise null.

Since:

8.9

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