Package com.deltaxml.core

Class DTCPConfiguration

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

Loads a DataComparator from a DTCP configuration.

DTCP (Data Comparator Pipeline) is a declarative file format for defining the pipeline and settings for the Data Comparator. It supports DTCP file format version 1.0 as described in DTCP TODO make user guide User Guide.

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

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

Since:
17.0
Author:
Charlotte Lawrence, Edward Monah
See Also:

  • Constructor Details

    • DTCPConfiguration

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

    • DTCPConfiguration

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

    • DTCPConfiguration

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

    • DTCPConfiguration

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

    • DTCPConfiguration

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

    • DTCPConfiguration

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

    • DTCPConfiguration

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

    • DTCPConfiguration

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

    • DTCPConfiguration

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

    • DTCPConfiguration

      public DTCPConfiguration(net.sf.saxon.s9api.XdmNode dtcpNode) throws StaticPDFormatException
      Creates a DTCPConfiguration object from a supplied XdmNode tree.
      Parameters:
      dtcpNode - An XdmNode tree containing a DTCP configuration
      Throws:
      StaticPDFormatException - if the DTCP 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 DataComparator. This method must only be called once.
      Parameters:
      booleanOverrides - A map of name, boolean value parameters with which to configure the generated DataComparator
      stringOverrides - A map of name, String value parameters with which to configure the generated DataComparator
      Throws:
      DynamicPDFormatException - if a problem is found when attempting to resolve DTCP values
      PDFilterConfigurationException - if a problem is found when loading an XML filter
      StaticPDFormatException - if the resolved DTCP 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 DynamicPDFormatException, PDAdvancedConfigException, PDFilterConfigurationException
      Set new parameter values to override named default parameter settings included in the DTCP file. This method call must be preceded by a call to the generate() method.
      Parameters:
      booleanOverrides - set parameter values for DTCP-defined boolean pipeline parameters
      stringOverrides - set parameter values for DTCP-defined string pipeline parameters
      Throws:
      PDFilterConfigurationException - if problem found while resolving DTCP values
      IllegalStateException - if generate() method has not been called first
      DynamicPDFormatException
      PDAdvancedConfigException

    • getComparator

      public DataComparator getComparator() throws IllegalStateException
      Returns the configured DataComparator instance. Must be used after the generate() method is called to initialize the DataComparator
      Returns:
      the DTCP-configured DataComparator
      Throws:
      IllegalStateException - if 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 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 DXPConfiguration.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