Package net.sf.saxon.lib

Class ParseOptions

  • public class ParseOptions
extends java.lang.Object
    This class defines options for parsing and/or validating a source document. Some of the options are relevant only when parsing, some only when validating, but they are combined into a single class because the two operations are often performed together.

    Rewritten in 12.x as an immutable class, because the product was previously creating a large number of instances as copies of other instances, without ever making any changes, just in case a change was required.

    • Constructor Detail

      • ParseOptions

        public ParseOptions()
        Create a ParseOptions object with default options set

    • Method Detail

      • merge

        public ParseOptions merge​(ParseOptions other)
        Merge another set of ParseOptions into these ParseOptions. Properties in the other ParseOptions take precedence over properties in these ParseOptions. "Taking precedence" here means:
        • If a non-default value for a property is present in one ParseOptions and the default value is present in the other, the non-default value is used.
        • If both ParseOptions objects have non-default values for a property, then the value is taken from the one that "takes precedence".
        Parameters:
        other - the set of ParseOptions properties to be merged in.
        Returns:
        the merged ParseOptions

      • applyDefaults

        public ParseOptions applyDefaults​(Configuration config)
        Merge settings from the Configuration object into these parseOptions
        Parameters:
        config - the Configuration. Settings from the Configuration are used only where no setting is present in this ParseOptions object

      • withFilter

        public ParseOptions withFilter​(FilterFactory filterFactory)
        Add a filter to the list of filters to be applied to the raw input

        User-supplied filters are applied to the input stream after applying any system-defined filters such as the whitespace stripper and the schema validator.

        Example: withFilter(receiver -> new MyFilter(receiver), where MyFilter extends ProxyReceiver

        Parameters:
        filterFactory - the filterFactory 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

      • getSpaceStrippingRule

        public SpaceStrippingRule getSpaceStrippingRule()
        Get the space-stripping action to be applied to the source document
        Returns:
        the space stripping rule to be used

      • withSpaceStrippingRule

        public ParseOptions withSpaceStrippingRule​(SpaceStrippingRule rule)
        Set the space-stripping action to be applied to the source document
        Parameters:
        rule - space stripping rule to be used

      • withParserFeature

        public ParseOptions withParserFeature​(java.lang.String uri,
                                      boolean value)
        Add a parser feature to a map, which will be applied to the XML parser later
        Parameters:
        uri - The features as a URIs
        value - The value given to the feature as boolean

      • withParserProperty

        public ParseOptions withParserProperty​(java.lang.String uri,
                                       java.lang.Object value)
        Add a parser property to a map, which is applied to the XML parser later
        Parameters:
        uri - The properties as a URIs
        value - The value given to the properties as a string

      • hasParserFeature

        public boolean hasParserFeature​(java.lang.String uri)
        Get a particular parser feature added
        Parameters:
        uri - The feature name as a URIs
        Returns:
        The feature value as boolean (returns false if the feature has not been set, or if it has been set to false)

      • isParserFeatureSet

        public boolean isParserFeatureSet​(java.lang.String uri)
        Ask if a particular parser feature has been set (either to true or false)
        Parameters:
        uri - The feature name as a URIs
        Returns:
        true if the feature has been set

      • getParserProperty

        public java.lang.Object getParserProperty​(java.lang.String name)
        Get a particular parser property added
        Parameters:
        name - The properties as a URIs
        Returns:
        The property value (which may be any object), or null if the property has not been set

      • getParserFeatures

        public java.util.Map<java.lang.String,​java.lang.Boolean> getParserFeatures()
        Get all the parser features added
        Returns:
        A map of (feature, value) pairs

      • getParserProperties

        public java.util.Map<java.lang.String,​java.lang.Object> getParserProperties()
        Get all the parser properties added
        Returns:
        A map of (feature, string) pairs

      • getSchemaValidationMode

        public int getSchemaValidationMode()
        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.

      • withExpandAttributeDefaults

        public ParseOptions withExpandAttributeDefaults​(boolean expand)
        Set whether to expand default attributes defined in a DTD or schema. By default, default attribute values are expanded
        Parameters:
        expand - true if missing attribute values are to take the default value supplied in a DTD or schema, false if they are to be left as absent

      • isExpandAttributeDefaults

        public boolean isExpandAttributeDefaults()
        Ask whether to expand default attributes defined in a DTD or schema. By default, default attribute values are expanded
        Returns:
        true if missing attribute values are to take the default value supplied in a DTD or schema, false if they are to be left as absent

      • withTopLevelElement

        public ParseOptions withTopLevelElement​(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

      • 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

      • withTopLevelType

        public ParseOptions withTopLevelType​(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

      • 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

      • withUseXsiSchemaLocation

        public ParseOptions withUseXsiSchemaLocation​(boolean use)
        Set whether or not to use the xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes in an instance document to locate a schema for validation. Note, these attribute are only used if validation is requested.
        Parameters:
        use - true if these attributes are to be used, false if they are to be ignored

      • isUseXsiSchemaLocation

        public boolean isUseXsiSchemaLocation()
        Ask whether or not to use the xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes in an instance document to locate a schema for validation. Note, these attribute are only used if validation is requested.
        Returns:
        true (the default) if these attributes are to be used, false if they are to be ignored

      • getValidationErrorLimit

        public int getValidationErrorLimit()
        Get the limit on the number of errors reported before schema validation is abandoned. Default is unlimited (Integer.MAX_VALUE)
        Returns:
        the limit on the number of errors

      • withValidationErrorLimit

        public ParseOptions withValidationErrorLimit​(int validationErrorLimit)
        Set a limit on the number of errors reported before schema validation is abandoned. Default is unlimited (Integer.MAX_VALUE). If set to one, validation is terminated as soon as a single validation error is detected.
        Parameters:
        validationErrorLimit - the limit on the number of errors

      • getDTDValidationMode

        public int getDTDValidationMode()
        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.

        The value Validation.LAX indicates that DTD validation is requested, but validation failures are treated as warnings only.

      • withValidationStatisticsRecipient

        public ParseOptions withValidationStatisticsRecipient​(ValidationStatisticsRecipient recipient)
        Say that statistics of component usage are maintained during schema validation, and indicate where they should be sent
        Parameters:
        recipient - the agent to be notified of the validation statistics on completion of the validation episode, May be set to null if no agent is to be notified.

      • getValidationStatisticsRecipient

        public ValidationStatisticsRecipient getValidationStatisticsRecipient()
        Ask whether statistics of component usage are maintained during schema validation, and where they will be sent
        Returns:
        the agent to be notified of the validation statistics on completion of the validation episode, or null if none has been nominated

      • withLineNumbering

        public ParseOptions withLineNumbering​(boolean lineNumbering)
        Set whether line numbers are to be maintained in the constructed document
        Parameters:
        lineNumbering - true if line numbers are to be maintained

      • isLineNumbering

        public boolean isLineNumbering()
        Get whether line numbers are to be maintained in the constructed document
        Returns:
        true if line numbers are maintained

      • isLineNumberingSet

        public boolean isLineNumberingSet()
        Determine whether setLineNumbering() has been called
        Returns:
        true if setLineNumbering() has been called

      • withXMLReader

        public ParseOptions withXMLReader​(org.xml.sax.XMLReader parser)
        Set the SAX parser (XMLReader) to be used. This method must be used with care, because an XMLReader is not thread-safe. If there is any chance that this ParseOptions object will be used in multiple threads, then this property should not be set. Instead, set the XMLReaderMaker property, which allows a new parser to be created each time it is needed.
        Parameters:
        parser - the SAX parser

      • getXMLReader

        public org.xml.sax.XMLReader getXMLReader()
        Get the SAX parser (XMLReader) to be used.
        Returns:
        the parser

      • withXMLReaderMaker

        public ParseOptions withXMLReaderMaker​(Maker<org.xml.sax.XMLReader> parserMaker)
        Set the parser factory class to be used.
        Parameters:
        parserMaker - a factory object that delivers an XMLReader on demand

      • getXMLReaderMaker

        public Maker<org.xml.sax.XMLReader> getXMLReaderMaker()
        Get the parser factory class to be used
        Returns:
        a factory object that delivers an XMLReader on demand, or null if none has been set

      • obtainXMLReader

        public org.xml.sax.XMLReader obtainXMLReader()
                                      throws XPathException
        Obtain an XMLReader (parser), by making one using the XMLReaderMaker if available, or by returning the registered XMLReader if available, or failing that, return null
        Throws:
        XPathException

      • withEntityResolver

        public ParseOptions withEntityResolver​(org.xml.sax.EntityResolver resolver)
        Set an EntityResolver to be used when parsing. Note that this will not be used if an XMLReader has been supplied (in that case, the XMLReader should be initialized with the EntityResolver already set.)
        Parameters:
        resolver - the EntityResolver to be used. May be null, in which case any existing EntityResolver is removed from the options

      • 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 withEntityResolver(org.xml.sax.EntityResolver), otherwise null.

      • withErrorHandler

        public ParseOptions withErrorHandler​(org.xml.sax.ErrorHandler handler)
        Set an ErrorHandler to be used when parsing. Note that this will not be used if an XMLReader has been supplied (in that case, the XMLReader should be initialized with the ErrorHandler already set.)
        Parameters:
        handler - the ErrorHandler to be used, or null to indicate that no ErrorHandler is to be used.

      • getErrorHandler

        public org.xml.sax.ErrorHandler getErrorHandler()
        Get the ErrorHandler that will be used when parsing
        Returns:
        the ErrorHandler, if one has been set using withErrorHandler(org.xml.sax.ErrorHandler), otherwise null.

      • withXIncludeAware

        public ParseOptions withXIncludeAware​(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

      • isXIncludeAware

        public boolean isXIncludeAware()

        Get state of XInclude processing.

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

      • withErrorReporter

        public ParseOptions withErrorReporter​(ErrorReporter reporter)
        Set an ErrorReporter to be used when parsing
        Parameters:
        reporter - the ErrorReporter to be used; or null, to indicate that the standard ErrorReporter is to be used.

      • withContinueAfterValidationErrors

        public ParseOptions withContinueAfterValidationErrors​(boolean keepGoing)
        Say that processing should continue after a validation error. Note that all validation errors are reported to the error() method of the ErrorListener, and processing always continues except when this method chooses to throw an exception. At the end of the document, a fatal error is thrown if (a) there have been any validation errors, and (b) this option is not set.
        Parameters:
        keepGoing - true if processing should continue

      • isContinueAfterValidationErrors

        public boolean isContinueAfterValidationErrors()
        Ask whether processing should continue after a validation error. Note that all validation errors are reported to the error() method of the ErrorListener, and processing always continues except when this method chooses to throw an exception. At the end of the document, a fatal error is thrown if (a) there have been any validation errors, and (b) this option is not set.
        Returns:
        true if processing should continue

      • withAddCommentsAfterValidationErrors

        public ParseOptions withAddCommentsAfterValidationErrors​(boolean addComments)
        Say that on validation errors, messages explaining the error should (where possible) be written as comments in the validated source document. This option is only relevant when processing continues after a validation error
        Parameters:
        addComments - true if comments should be added
        Since:
        9.3. Default is now false; in previous releases this option was always on.

      • isAddCommentsAfterValidationErrors

        public boolean isAddCommentsAfterValidationErrors()
        Ask whether on validation errors, messages explaining the error should (where possible) be written as comments in the validated source document. This option is only relevant when processing continues after a validation error
        Returns:
        true if comments should be added
        Since:
        9.3

      • withValidationParams

        public ParseOptions withValidationParams​(ValidationParams params)
        Set the validation parameters. These are the values of variables declared in the schema using the saxon:param extension, and referenced in XSD assertions (or CTA expressions) associated with user-defined types
        Parameters:
        params - the validation parameters

      • getValidationParams

        public ValidationParams getValidationParams()
        Get the validation parameters. These are the values of variables declared in the schema using the saxon:param extension, and referenced in XSD assertions (or CTA expressions) associated with user-defined types
        Returns:
        the validation parameters

      • withCheckEntityReferences

        public ParseOptions withCheckEntityReferences​(boolean check)
        Say whether to check elements and attributes of type xs:ENTITY (or xs:ENTITIES) against the unparsed entities declared in the document's DTD. This is normally true when performing standalone schema validation, false when invoking validation from XSLT or XQuery.
        Parameters:
        check - true if entities are to be checked, false otherwise

      • isCheckEntityReferences

        public boolean isCheckEntityReferences()
        Ask whether to check elements and attributes of type xs:ENTITY (or xs:ENTITIES) against the unparsed entities declared in the document's DTD. This is normally true when performing standalone schema validation, false when invoking validation from XSLT or XQuery.
        Returns:
        true if entities are to be checked, false otherwise

      • isStable

        public boolean isStable()
        Ask whether the document (or collection) should be stable, that is, if repeated attempts to dereference the same URI are guaranteed to return the same result. By default, documents and collections are stable.
        Returns:
        true if the document or collection is stable

      • withStable

        public ParseOptions withStable​(boolean stable)
        Say whether the document (or collection) should be stable, that is, if repeated attempts to dereference the same URI are guaranteed to return the same result. By default, documents and collections are stable.
        Parameters:
        stable - true if the document or collection is stable

      • getInvalidityHandler

        public InvalidityHandler getInvalidityHandler()
        Get the callback for reporting validation errors
        Returns:
        the registered InvalidityHandler

      • withInvalidityHandler

        public ParseOptions withInvalidityHandler​(InvalidityHandler invalidityHandler)
        Set the callback for reporting validation errors
        Parameters:
        invalidityHandler - the InvalidityHandler to be used for reporting validation failures

      • withApplicableAccumulators

        public ParseOptions withApplicableAccumulators​(java.util.Set<? extends Accumulator> accumulators)
        Set the list of XSLT 3.0 accumulators that apply to this tree.
        Parameters:
        accumulators - the accumulators that apply; or null if all accumulators apply. (Note, this is not the same as the meaning of #all in the use-accumulators attribute, which refers to all accumulators declared in a given package).

      • getApplicableAccumulators

        public java.util.Set<? extends Accumulator> getApplicableAccumulators()
        Set the list of XSLT 3.0 accumulators that apply to this tree.
        Returns:
        the accumulators that apply; or null if all accumulators apply. (Note, this is not the same as the meaning of #all in the use-accumulators attribute, which refers to all accumulators declared in a given package).

      • withPleaseCloseAfterUse

        public ParseOptions withPleaseCloseAfterUse​(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

      • 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

      • close

        public static void close​(javax.xml.transform.Source source)
        Close any resources held by a given Source. This only works if the underlying Source is one that is recognized as holding closable resources.
        Parameters:
        source - the source to be closed
        Since:
        9.2

      • toString

        public java.lang.String toString()
        Returns a string representation of the object.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a string representation of the object.