Package com.deltaxml.core

Class DCPConfiguration

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

Loads a DocumentComparator from a DCP configuration.

DCP (Document Comparator Pipeline) is a declarative file format for defining the pipeline and settings for the Document Comparator. It supports DCP file format version 1.0 as described in DCP User Guide.

This class provides methods for obtaining information from DCP files and also for loading a DocumentComparator instance and configuring it using data from the DCP and any supplied override parameters. The constructor of this class is responsible for ensuring basic validity of the input DCP. Full validation is performed by default when generate() or setParams(Map, Map) is called.

The constructor optionally allows a 'checkDCP' argument that can be set false to disable validation of the DCP. This may improve performance, but results in less informative exception messages. It is therefore recommended that this is only used for cases where the DCP file and any parameter overrides are already known to be valid.

Since:
7.2
Author:
John Morgan
See Also:

  • Constructor Details

    • DCPConfiguration

      public DCPConfiguration(File f, net.sf.saxon.s9api.Processor suppliedProcessor, boolean checkDCP) throws StaticPDFormatException, FileNotFoundException
      Creates a DCPConfiguration object from a DCP file. Once loaded this Object can be queried for information from the DCP configuration file and a DocumentComparator object can be generated using generate().
      Parameters:
      f - A File containing a DCP configuration
      suppliedProcessor - A Saxon Processor instance. This will be used to process the DCP file but will also be supplied to the generated DocumentComparator instance as its underlying Processor. See DocumentComparator(Processor) for more details.
      checkDCP - Specifies whether to validate and perform other checks on input DCP
      Throws:
      StaticPDFormatException - if the DCP file is not well-formed or valid
      FileNotFoundException - if the DCP file cannot be located

    • DCPConfiguration

      public DCPConfiguration(File f, boolean checkDCP) throws StaticPDFormatException, FileNotFoundException
      Creates a DCPConfiguration object from a DCP file. Once loaded this Object can be queried for information from the DCP configuration file and a DocumentComparator object can be generated using generate().
      Parameters:
      f - A File containing a DCP configuration
      checkDCP - Specifies whether to validate and perform other checks on input DCP
      Throws:
      StaticPDFormatException - if the DCP file is not well-formed or valid
      FileNotFoundException - if the DCP file cannot be located

    • DCPConfiguration

      public DCPConfiguration(InputSource dcpSource, net.sf.saxon.s9api.Processor suppliedProcessor, boolean checkDCP) throws StaticPDFormatException
      Creates a DCPConfiguration object from an InputSource. It is recommended that the supplied InputSource should have a systemId set, otherwise validation issues may arise.
      Parameters:
      dcpSource - An InputSource containing a DCP configuration
      suppliedProcessor - A Saxon Processor instance. This will be used to process the DCP file but will also be supplied to the generated DocumentComparator instance as its underlying Processor. See DocumentComparator(Processor) for more details.
      checkDCP - Specifies whether to validate and perform other checks on input DCP
      Throws:
      StaticPDFormatException - if the DCP source is not well-formed or valid

    • DCPConfiguration

      public DCPConfiguration(InputSource dcpSource, boolean checkDCP) throws StaticPDFormatException
      Creates a DCPConfiguration object from an InputSource. It is recommended that the supplied InputSource should have a systemId set, otherwise validation issues may arise.
      Parameters:
      dcpSource - An InputSource containing a DCP configuration
      checkDCP - Specifies whether to validate and perform other checks on input DCP
      Throws:
      StaticPDFormatException - if the DCP source is not well-formed or valid

    • DCPConfiguration

      public DCPConfiguration(net.sf.saxon.s9api.XdmNode dcpNode, boolean checkDCP) throws StaticPDFormatException
      Creates a DCPConfiguration object from a supplied XdmNode tree.
      Parameters:
      dcpNode - An XdmNode tree containing a DCP configuration
      checkDCP - Specifies whether to validate and perform other checks on input DCP
      Throws:
      StaticPDFormatException - if the DCP document is not valid

    • DCPConfiguration

      public DCPConfiguration(File f, net.sf.saxon.s9api.Processor suppliedProcessor) throws StaticPDFormatException, FileNotFoundException
      Creates a DCPConfiguration object from a DCP file. Once loaded this Object can be queried for information from the DCP configuration file and a DocumentComparator object can be generated using generate().
      Parameters:
      f - A File containing a DCP configuration
      suppliedProcessor - A Saxon Processor instance. This will be used to process the DCP file but will also be supplied to the generated DocumentComparator instance as its underlying Processor. See DocumentComparator(Processor) for more details.
      Throws:
      StaticPDFormatException - if the DCP file is not well-formed or valid
      FileNotFoundException - if the DCP file cannot be located

    • DCPConfiguration

      public DCPConfiguration(File f) throws StaticPDFormatException, FileNotFoundException
      Creates a DCPConfiguration object from a DCP file. Once loaded this Object can be queried for information from the DCP configuration file and a DocumentComparator object can be generated using generate().
      Parameters:
      f - A File containing a DCP configuration
      Throws:
      StaticPDFormatException - if the DCP file is not well-formed or valid
      FileNotFoundException - if the DCP file cannot be located

    • DCPConfiguration

      public DCPConfiguration(InputSource dcpSource, net.sf.saxon.s9api.Processor suppliedProcessor) throws StaticPDFormatException
      Creates a DCPConfiguration object from an InputSource. It is recommended that the supplied InputSource should have a systemId set, otherwise validation issues may arise.
      Parameters:
      dcpSource - An InputSource containing a DCP configuration
      suppliedProcessor - A Saxon Processor instance. This will be used to process the DCP file but will also be supplied to the generated DocumentComparator instance as its underlying Processor. See DocumentComparator(Processor) for more details.
      Throws:
      StaticPDFormatException - if the DCP source is not well-formed or valid

    • DCPConfiguration

      public DCPConfiguration(InputSource dcpSource) throws StaticPDFormatException
      Creates a DCPConfiguration object from an InputSource. It is recommended that the supplied InputSource should have a systemId set, otherwise validation issues may arise.
      Parameters:
      dcpSource - An InputSource containing a DCP configuration
      Throws:
      StaticPDFormatException - if the DCP source is not well-formed or valid

    • DCPConfiguration

      public DCPConfiguration(net.sf.saxon.s9api.XdmNode dcpNode) throws StaticPDFormatException
      Creates a DCPConfiguration object from a supplied XdmNode tree.
      Parameters:
      dcpNode - An XdmNode tree containing a DCP configuration
      Throws:
      StaticPDFormatException - if the DCP document is not valid

  • Method Details

    • generate

      public void generate(Map<String,Boolean> booleanOverrides, Map<String,String> stringOverrides) throws DynamicPDFormatException, PDAdvancedConfigException, StaticPDFormatException, PDFilterConfigurationException
      Initializes the internal instance of a DocumentComparator. This method must only be called once.
      Parameters:
      booleanOverrides - A map of name, boolean value parameters with which to configure the generated DocumentComparator
      stringOverrides - A map of name, String value parameters with which to configure the generated DocumentComparator
      Throws:
      DynamicPDFormatException - if a problem is found when attempting to resolve DCP values
      PDFilterConfigurationException - if a problem is found when loading an XML filter
      StaticPDFormatException - if the resolved DCP values are invalid
      PDAdvancedConfigException - when properties or features in 'advancedConfig' element cause an error
      IllegalStateException - if called more than once

    • setParams

      public final void setParams(Map<String,Boolean> booleanOverrides, Map<String,String> stringOverrides) throws PDFilterConfigurationException, DynamicPDFormatException, PDAdvancedConfigException, IllegalStateException
      Set new parameter values to override named default parameter settings included in the DCP file. This method call must be preceded by a call to the generate() method.
      Parameters:
      booleanOverrides - set parameter values for DCP-defined boolean pipeline parameters
      stringOverrides - set parameter values for DCP-defined string pipeline parameters
      Throws:
      PDAdvancedConfigException - when properties or features in 'advancedConfig' element cause an error
      DynamicPDFormatException - if problem found while resolving DCP values
      PDFilterConfigurationException - if problem found when loading an XML filter
      IllegalStateException - if generate() method has not been called first

    • getComparator

      public DocumentComparator getComparator() throws IllegalStateException
      Returns the configured DocumentComparator instance. Must be used after the generate() method is called to initialize the DocumentComparator
      Returns:
      the DCP-configured DocumentComparator
      Throws:
      IllegalStateException - if generate() method has not been called first

    • getResolvedParameterValue

      public String getResolvedParameterValue(String parameterName)
      Returns the resolved value of the specified pipelineParameter in the DCP.
      Parameters:
      parameterName - name of the parameter
      Returns:
      the resolved parameter value as a string. Null is returned when no matching parameter is found or the generate() method has not been called first

    • generate

      public void generate() throws StaticPDFormatException, PDFilterConfigurationException, DynamicPDFormatException, PDAdvancedConfigException, IllegalStateException
      Initializes the internal instance of a concrete FeatureComparator. This method must only be called once.
      Throws:
      DynamicPDFormatException - if a problem is found when attempting to resolve Comparator Pipeline values
      PDFilterConfigurationException - if a problem is found when loading an XML filter
      StaticPDFormatException - if the resolved Comparator Pipeline values are invalid
      PDAdvancedConfigException - when properties or features in 'advancedConfig' element cause an error
      IllegalStateException - if called more than once

    • getProcessingInstruction

      public String getProcessingInstruction(String instructionName)
      Returns the value of a processing instruction that is a child node of the root element of the configuration. Processing instruction values are available as soon as the Configuration object is instantiated.
      Parameters:
      instructionName - name of the processing-instruction (cannot be in a namespace)
      Returns:
      the processing-instruction value
      See Also:

    • getFormattedPipelineSummaryTable

      public static String getFormattedPipelineSummaryTable(Collection<? extends com.deltaxml.core.FeatureConfiguration> featureConfigs, int width, int indent)
      Returns 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:
      featureConfigs - 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 DXPConfiguration.generate(Map, Map) or 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 DXPConfiguration.generate(Map, Map) or 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