com.deltaxml.cores9api

Class DTCPConfiguration

java.lang.Object

com.deltaxml.cores9api.AbstractDPConfigurationS9

com.deltaxml.cores9api.DTCPConfiguration

public class DTCPConfiguration
extends com.deltaxml.cores9api.AbstractDPConfigurationS9

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 DTCPConfiguration.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

See Also:

DTCP User Guide, DataComparator

Constructor Summary

Constructors

Constructor and Description
DTCPConfiguration(java.io.File f) Creates a DTCPConfiguration object from a DTCP file.
DTCPConfiguration(java.io.File f, boolean checkDTCP) Creates a DTCPConfiguration object from a DTCP file.
DTCPConfiguration(java.io.File f, net.sf.saxon.s9api.Processor suppliedProcessor) Creates a DTCPConfiguration object from a DTCP file.
DTCPConfiguration(java.io.File f, net.sf.saxon.s9api.Processor suppliedProcessor, boolean checkDTCP) Creates a DTCPConfiguration object from a DTCP file.
DTCPConfiguration(org.xml.sax.InputSource dtcpSource) Creates a DTCPConfiguration object from an InputSource.
DTCPConfiguration(org.xml.sax.InputSource dtcpSource, boolean checkDTCP) Creates a DTCPConfiguration object from an InputSource.
DTCPConfiguration(org.xml.sax.InputSource dtcpSource, net.sf.saxon.s9api.Processor suppliedProcessor) Creates a DTCPConfiguration object from an InputSource.
DTCPConfiguration(org.xml.sax.InputSource dtcpSource, net.sf.saxon.s9api.Processor suppliedProcessor, boolean checkDTCP) Creates a DTCPConfiguration object from an InputSource.
DTCPConfiguration(net.sf.saxon.s9api.XdmNode dtcpNode) Creates a DTCPConfiguration object from a supplied XdmNode tree.
DTCPConfiguration(net.sf.saxon.s9api.XdmNode dtcpNode, boolean checkDTCP) Creates a DTCPConfiguration object from a supplied XdmNode tree.

Method Summary

Modifier and Type	Method and Description
void	generate() Initializes the internal instance of a concrete FeatureComparator.
void	generate(java.util.Map<java.lang.String,java.lang.Boolean> booleanOverrides, java.util.Map<java.lang.String,java.lang.String> stringOverrides) Initializes the internal instance of a DataComparator.
DataComparator	getComparator() Returns the configured DataComparator instance.
static java.lang.String	getFormattedPipelineSummaryTable(java.util.Collection<? extends com.deltaxml.cores9api.FeatureConfiguration> featureConfigs, int width, int indent) Returns a table summarising the provided pipelines as a multi-line string.
java.lang.String	getProcessingInstruction(java.lang.String instructionName) Returns the value of a processing instruction that is a child node of the root element of the configuration.
void	setParams(java.util.Map<java.lang.String,java.lang.Boolean> booleanOverrides, java.util.Map<java.lang.String,java.lang.String> stringOverrides) Set new parameter values to override named default parameter settings included in the DTCP file.

Methods inherited from class com.deltaxml.cores9api.AbstractDPConfigurationS9

getBooleanParameterList, getBooleanParameters, getDescription, getFormattedParametersDescription, getFormattedParametersDescription, getFullDescription, getId, getParameterDescriptions, getParameterList, getStringParameterList, getStringParameters, getSystemId, getURIResolver, setURIResolver, setURIResolver, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DTCPConfiguration

public DTCPConfiguration(java.io.File f,
                         net.sf.saxon.s9api.Processor suppliedProcessor,
                         boolean checkDTCP)
                  throws StaticPDFormatException,
                         java.io.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

java.io.FileNotFoundException - if the DTCP file cannot be located

DTCPConfiguration

public DTCPConfiguration(java.io.File f,
                         boolean checkDTCP)
                  throws StaticPDFormatException,
                         java.io.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

java.io.FileNotFoundException - if the DTCP file cannot be located

DTCPConfiguration

public DTCPConfiguration(org.xml.sax.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(org.xml.sax.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(java.io.File f,
                         net.sf.saxon.s9api.Processor suppliedProcessor)
                  throws StaticPDFormatException,
                         java.io.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

java.io.FileNotFoundException - if the DTCP file cannot be located

DTCPConfiguration

public DTCPConfiguration(java.io.File f)
                  throws StaticPDFormatException,
                         java.io.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

java.io.FileNotFoundException - if the DTCP file cannot be located

DTCPConfiguration

public DTCPConfiguration(org.xml.sax.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(org.xml.sax.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 Detail

generate

public void generate(java.util.Map<java.lang.String,java.lang.Boolean> booleanOverrides,
                     java.util.Map<java.lang.String,java.lang.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

java.lang.IllegalStateException - if called more than once

setParams

public final void setParams(java.util.Map<java.lang.String,java.lang.Boolean> booleanOverrides,
                            java.util.Map<java.lang.String,java.lang.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

java.lang.IllegalStateException - if generate() method has not been called first

DynamicPDFormatException

PDAdvancedConfigException

getComparator

public DataComparator getComparator()
                             throws java.lang.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:

java.lang.IllegalStateException - if generate() method has not been called first

generate

public void generate()
              throws StaticPDFormatException,
                     PDFilterConfigurationException,
                     DynamicPDFormatException,
                     PDAdvancedConfigException,
                     java.lang.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

java.lang.IllegalStateException - if called more than once

getProcessingInstruction

public java.lang.String getProcessingInstruction(java.lang.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:

Document Comparator Configuration using DCP, Data Comparator Configuration using DTCP

getFormattedPipelineSummaryTable

public static java.lang.String getFormattedPipelineSummaryTable(java.util.Collection<? extends com.deltaxml.cores9api.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