Package com.deltaxml.core

Class DXPConfiguration

java.lang.Object
com.deltaxml.core.DXPConfiguration
public class DXPConfiguration extends Object

Loads a PipelinedComparator from a DXP configuration.

DXP (DeltaXML Pipelines) is a declarative file format for describing comparator pipelines and could also be considered a form of customization language for comparator based tools. It supports DXP file format versions 1.0-2.4 as discussed in DXP User Guide.

This class provides methods for obtaining information from DXP files and also for loading a PipelinedComparatorS9 instance from DXP. The constructor of this class is generally responsible for ensuring validity of the input DXP.

Since:
6.0
Author:
Nigel Whitaker, Tristan Mitchell
See Also:

  • Constructor Details

    • DXPConfiguration

      public DXPConfiguration(File f) throws ParserInstantiationException, FileNotFoundException, net.sf.saxon.s9api.SaxonApiException, InvalidPipelineException
      Creates a DXPConfigurationS9 object from a DXP file. Once loaded this Object can be queried for information from the DXP configuration and a PipelinedComparatorS9 object can be generated.
      Parameters:
      f - A File containing a DXP configuration
      Throws:
      ParserInstantiationException - if there are problems creating the parser
      FileNotFoundException - if the DXP file cannot be located
      net.sf.saxon.s9api.SaxonApiException - if there are parsing errors or other s9api related problems
      InvalidPipelineException - if the DXP contains errors (beyond standard validation errors)
      See Also:

    • DXPConfiguration

      public DXPConfiguration(InputSource dxpSource, EntityResolver er, boolean validate) throws ParserInstantiationException, net.sf.saxon.s9api.SaxonApiException, InvalidPipelineException
      Creates a DXPConfigurationS9 object from a DXP InputSource. Once loaded this Object can be queried for information from the DXP configuration and a PipelinedComparatorS9 object can be generated. This method allows the user to control entity resolving and validation associated with the InputSource. Normally validation is strongly recommended and in order to validate a systemId should be associated with the InputSource so that a DTD can be located using relative URLs. Note: Please only consider this method after considering the other DXPConfiguration constructors, as invalid DXP files may produce unpredictable results.
      Parameters:
      dxpSource - An InputSource describing a DXP configuration
      er - An EntityResolver for dealing with DTD and other external URL references
      validate - controls parser validation (requires uses of a DTD)
      Throws:
      ParserInstantiationException - if there are problems creating the parser
      net.sf.saxon.s9api.SaxonApiException - if there are parsing errors or other s9api related problems
      InvalidPipelineException - if the DXP contains errors (beyond standard validation errors)
      See Also:

    • DXPConfiguration

      public DXPConfiguration(InputSource dxpSource) throws ParserInstantiationException, net.sf.saxon.s9api.SaxonApiException, InvalidPipelineException
      Creates a DXPConfigurationS9 object from an InputSource. Unlike other constructors there is no option to control entity resolving and validation is always performed. It is recommended that the supplied InputSource should have a systemId set, otherwise validation issues may arise.
      Parameters:
      dxpSource - An InputSource describing a DXP configuration
      Throws:
      ParserInstantiationException - if there are problems creating the parser
      net.sf.saxon.s9api.SaxonApiException - if there are parsing errors or other s9api related problems
      InvalidPipelineException - if the DXP contains errors (beyond standard validation errors)

    • DXPConfiguration

      public DXPConfiguration(net.sf.saxon.s9api.XdmNode dxpSource) throws InvalidPipelineException, IllegalArgumentException
      Creates a DXPConfigurationS9 object from a supplied XdmNode tree. As such a tree will have been parsed there is no opportunity for DTD based validity checking. Users must ensure that the supplied tree is valid.
      Parameters:
      dxpSource - An XdmNode tree containing a DXP pipeline definition
      Throws:
      InvalidPipelineException - if the DXP contains errors (beyond standard validation errors)
      IllegalArgumentException - if the supplied XdmNode is not a DOCUMENT or ELEMENT node

  • Method Details

    • generate

      public final PipelinedComparator generate(Map<String,Boolean> booleanOverrides, Map<String,String> stringOverrides) throws ClassNotFoundException, MalformedURLException, ParserInstantiationException, FilterClassInstantiationException, FilterConfigurationException, FilterParameterizationException, FeatureNotRecognizedException, FeatureSettingNotSupportedException, PropertyNotRecognizedException, ParameterValueConflict, NonUniqueParameterNameException, UnknownParameterException, ConditionalFilterXPathException

      Generates a PipelinedComparatorS9 from this instance of a DXPConfigurationS9.

      This method allows parameters to be overridden when the pipeline is constructed. The Map arguments should correspond to the declared 'pipelineParameters' in the associated DXP. An easy way to achieve this is to use and modify the Maps returned with AbstractDPConfiguration.getBooleanParameters() and AbstractDPConfiguration.getStringParameters().

      This method throws a large number of exceptions. Further details of the circumstances in which they are thrown are documented in the javadoc descriptions of the Exception classes themselves. Should fine-grain exception handling not be required, it is possible to catch the DeltaXMLException supertypes for all but two (ClassNotFoundException and MalformedURLException) of the exceptions thrown by this method.

      Parameters:
      booleanOverrides - parameter settings to override the boolean pipeline parameters
      stringOverrides - parameter settings to override the string pipeline parameters
      Returns:
      a configured PipelineComparatorS9
      Throws:
      ClassNotFoundException - if a class specified in a DXP class element cannot be located
      MalformedURLException - if a DXP URL elements contents are malformed
      ParserInstantiationException - if the PipelinedComparatorS9 constructor throws this exception
      FilterClassInstantiationException - if there are problems instantiating a Java class based filter
      FilterConfigurationException - if there is a problem instantiating or configuring an XSLT based filter
      FilterParameterizationException - if there are problems setting the parameters on a Java filter
      FeatureNotRecognizedException - if the feature, in a parserFeature element, is not recognized
      FeatureSettingNotSupportedException - if the setting of the specified parser feature is not supported
      PropertyNotRecognizedException - if the specified outputProperty is not recognized
      ParameterValueConflict - if the attributes used to specify a filter or other parameter are in conflict
      NonUniqueParameterNameException - if the PipelineParameter names are not unique
      UnknownParameterException - if the referenced parameter name is not known/declared
      ConditionalFilterXPathException - if there is a problem with an XPath expression on a conditional filter
      XPathFilterParameterException - if there is a problem with an XPath expression being used as a filter parameter

    • generate

      public final PipelinedComparator generate(Map<String,Boolean> booleanOverrides, Map<String,String> stringOverrides, net.sf.saxon.s9api.Processor proc) throws ClassNotFoundException, MalformedURLException, ParserInstantiationException, FilterClassInstantiationException, FilterConfigurationException, FilterParameterizationException, FeatureNotRecognizedException, FeatureSettingNotSupportedException, PropertyNotRecognizedException, ParameterValueConflict, NonUniqueParameterNameException, UnknownParameterException, IllegalArgumentException, ConditionalFilterXPathException

      Generates a PipelinedComparatorS9 from this instance of a DXPConfigurationS9.

      This method allows a Saxon s9api Processor to be specified and should be used if you intend to supply XdmNode inputs to the generated PipelinedComparatorS9.

      This method allows parameters to be overridden when the pipeline is constructed. The Map arguments should correspond to the declared 'pipelineParameters' in the associated DXP. An easy way to achieve this is to use and modify the Maps returned with AbstractDPConfiguration.getBooleanParameters() and AbstractDPConfiguration.getStringParameters().

      This method throws a large number of exceptions. Further details of the circumstances in which they are thrown are documented in the javadoc descriptions of the Exception classes themselves. Should fine-grain exception handling not be required, it is possible to catch the DeltaXMLException supertypes for all but two (ClassNotFoundException and MalformedURLException) of the exceptions thrown by this method.

      Parameters:
      booleanOverrides - parameter settings to override the boolean pipeline parameters
      stringOverrides - parameter settings to override the string pipeline parameters
      proc - a Saxon processor to be used for the NamePool and filter compilation
      Returns:
      a configured PipelineComparatorS9
      Throws:
      ClassNotFoundException - if a class specified in a DXP class element cannot be located
      MalformedURLException - if a DXP URL elements contents are malformed
      ParserInstantiationException - if the PipelinedComparatorS9 constructor throws this exception
      FilterClassInstantiationException - if there are problems instantiating a Java class based filter
      FilterConfigurationException - if there is a problem instantiating or configuring an XSLT based filter
      FilterParameterizationException - if there are problems setting the parameters on a Java filter
      FeatureNotRecognizedException - if the feature, in a parserFeature element, is not recognized
      FeatureSettingNotSupportedException - if the setting of the specified parser feature is not supported
      PropertyNotRecognizedException - if the specified outputProperty is not recognized
      ParameterValueConflict - if the attributes used to specify a filter or other parameter are in conflict
      NonUniqueParameterNameException - if the PipelineParameter names are not unique
      UnknownParameterException - if the referenced parameter name is not known/declared
      IllegalArgumentException - if the Processor argument is null
      ConditionalFilterXPathException - if there is a problem with an XPath expression on a conditional filter
      XPathFilterParameterException - if there is a problem with an XPath expression being used as a filter parameter

    • isCorePipeline

      public boolean isCorePipeline()
      States whether this represents a core (XML Compare) pipeline or not. As .dxp is a common file extension for core dxp files and sync dxp files, this method provides an easy way of determining if this dxp file represents a core pipeline.
      Returns:
      true if this is a comparator pipeline, otherwise false

    • getFileExtension

      public String getFileExtension()
      Returns the contents of the DXP outputFileExtension/@extension attribute. This can be used by applications to alter the behaviour of an application based on the type of data generated. For example a pipeline producing HTML, using an extension of "html", may be processed differently (shown in a browser), to a pipeline with an "xml" extension.
      Returns:
      the extension attribute, or the default value of "xml"

    • generate

      public final PipelinedComparator generate() throws ClassNotFoundException, MalformedURLException, ParserInstantiationException, FilterClassInstantiationException, FilterConfigurationException, FilterParameterizationException, FeatureNotRecognizedException, FeatureSettingNotSupportedException, PropertyNotRecognizedException, ParameterValueConflict, NonUniqueParameterNameException, UnknownParameterException, ConditionalFilterXPathException

      Generates a PipelinedComparatorS9 from the DXP configuration loaded into this instance of a DXPConfigurationS9. This method allows does not allow parameter overriding.

      This method throws a large number of exceptions. Further details of the circumstances in which they are thrown are documented in the javadoc descriptions of the Exception classes themselves. Should fine-grain exception handling not be required, it is possible to catch the DeltaXMLException supertypes for all but two (ClassNotFoundException and MalformedURLException) of the exceptions thrown by this method.

      Returns:
      a configured PipelineComparatorS9
      Throws:
      ClassNotFoundException - if a class specified in a DXP class element cannot be located
      MalformedURLException - if a DXP URL elements contents are malformed
      ParserInstantiationException - if the PipelinedComparatorS9 constructor throws this exception
      FilterClassInstantiationException - if there are problems instantiating a Java class based filter
      FilterConfigurationException - if there is a problem instantiating or configuring an XSLT based filter
      FilterParameterizationException - if there are problems setting the parameters on a Java filter
      FeatureNotRecognizedException - if the feature, in a parserFeature element, is not recognized
      FeatureSettingNotSupportedException - if the setting of the specified parser feature is not supported
      PropertyNotRecognizedException - if the specified outputProperty is not recognized
      ParameterValueConflict - if the attributes used to specify a filter or other parameter are in conflict
      NonUniqueParameterNameException - if the PipelineParameter names are not unique
      UnknownParameterException - if the referenced parameter name is not known/declared
      ConditionalFilterXPathException - if there is a problem with an XPath expression on a conditional filter
      XPathFilterParameterException - if there is a problem with an XPath expression being used as a filter parameter

    • getFormattedPipelineSummaryTable

      public static String getFormattedPipelineSummaryTable(Collection<DXPConfiguration> dxpConfigs, int width, int indent)
      A table summarising the provided pipelines as a multi-line string. There is a minimum width of 40, any provided width less than 40 is treated as 40.
      Parameters:
      dxpConfigs - The dxpConfigurations to summarise.
      width - the maximum width of each line for the description (not including the indent)
      indent - the number of spaces to prefix each line with.
      Returns:
      a table summarising the provided pipeline as a multi-line string.
      Since:
      6.2

    • getId

      public String getId()
      Returns the id attribute from a DXP/DCP file. The id attribute is compulsory on a valid DXP or DCP file but null may be returned on an invalid file.
      Returns:
      the value of the id attribute

    • getSystemId

      public String getSystemId()
      Returns the systemId of the loaded DXP/DCP file. The value will depend on how the DXP/DCP file was loaded. The following list provides a summary.
      • Loaded as an InputSource - returns the result of InputSource.getSystemId()
      • Loaded as a File - returns the result of File.toURI().toURL().toExternalForm()
      • Loaded as an XdmNode - returns the result of XdmNode.getDocumentURI()
      Returns:
      the SystemId of the loaded DXP/DCP file, null if unknown or cannot be determined
      See Also:

    • getDescription

      public String getDescription()
      Returns the contents of the description attribute of a DXP/DCP File. This attribute provides a more human friendly description of the pipeline and can be used in command-lines or selection boxes for example.
      Returns:
      the contents of description attribute

    • getBooleanParameterList

      public List<DXPParameterDefinition<Boolean>> getBooleanParameterList()
      Returns the boolean parameters declared in a configuration file. This method can be used in UIs and other applications which may wish to display parameter options prior to creating a pipeline instance.
      Returns:
      a list of boolean DXP/DCP parameter definitions.

    • getStringParameterList

      public List<DXPParameterDefinition<String>> getStringParameterList()
      Returns the string parameters declared in a configuration file. This method can be used in UIs and other applications which may wish to display parameter options prior to creating a pipeline instance.
      Returns:
      a list of string DXP/DCP parameter definitions.

    • getParameterList

      public List<DXPParameterDefinition<?>> getParameterList()
      Returns the parameters declared in a configuration file. This method can be used in UIs and other applications which may wish to display parameter options prior to creating a pipeline instance.
      Returns:
      a list of DXP/DCP parameter definitions.

    • getBooleanParameters

      public Map<String,Boolean> getBooleanParameters()
      Returns the boolean parameters declared in a configuration file. This method can be used in UIs and other applications which may wish to display parameter options prior to creating a pipeline instance. For example it is possible to obtain the Map provided by this method and then pass the Map, possibly modified, as an argument to the applicable generate(Map, Map) or DCPConfiguration.generate(Map, Map) method.
      Returns:
      a Map describing the boolean parameters and their default values
      See Also:

    • getParameterDescriptions

      public Map<String,String> getParameterDescriptions()
      Returns the description of each of the parameters in a configuration file. This method can be used in UIs and other applications which may wish to display parameters prior to creating a pipeline instance.
      Returns:
      a Map containing each of the parameters by name along with a textual description

    • getStringParameters

      public Map<String,String> getStringParameters()
      Returns the String parameters declared in a configuration file. This method can be used in UIs and other applications which may wish to display parameter options prior to creating a pipeline instance. For example, it is possible to obtain the Map provided by this method and then pass the Map, possibly modified, as an argument to the applicable generate(Map, Map) or DCPConfiguration.generate(Map, Map) method.
      Returns:
      a Map describing the string parameters and their default values
      See Also:

    • getFullDescription

      public String getFullDescription()
      Returns the contents of the fullDescription element.
      Returns:
      the contents of the description element or an empty String.

    • getFormattedParametersDescription

      public String getFormattedParametersDescription()
      Returns the contents of the parameter elements as a formatted table. This can be used to provide multi-line information to the user about the pipeline's parameters.
      Returns:
      the contents of the description and parameter elements or an empty String.

    • getFormattedParametersDescription

      public String getFormattedParametersDescription(int width, int indent)
      Returns the contents of the parameter elements as a formatted table. This can be used to provide multi-line information to the user about the pipeline's parameters.
      Parameters:
      width - the maximum width of each line for the description (not including the indent)
      indent - the number of spaces to prefix each line with.
      Returns:
      the contents of the description and parameter elements or an empty String.

    • setURIResolver

      public void setURIResolver(URIResolver resolver, boolean useFallbackURIResolver)

      Specifies the URIResolver to be used with the generated comparator and also during compilation of XSLT scripts. A URIResolver used in this way is useful when resolving files referenced by <xsl:import> , <xsl:include> and document()

      Parameters:
      resolver - An implementation of the URIResolver interface, or null
      useFallbackURIResolver - Whether to use the fallback URI Resolver, if the user supplied URI Resolver fails to resolve.

    • setURIResolver

      public void setURIResolver(URIResolver resolver)

      Specifies the URIResolver to be used with the generated comparator and also during compilation of XSLT scripts. A URIResolver used in this way is useful when resolving files referenced by <xsl:import> , <xsl:include> and document()

      This method is equivalent to calling setURIResolver(resolver, true).

      Parameters:
      resolver - An implementation of the URIResolver interface, or null

    • getURIResolver

      public URIResolver getURIResolver()
      Returns the user specified URIResolver.
      Returns:
      the resolver that was last set using one of the setURIResolver methods.

    • toString

      public String toString()
      Provides a string representation of the configuration based on the systemId of the DXP/DCP file.
      Overrides:
      toString in class Object
      Returns:
      a string representation