com.deltaxml.cores9api

Class DCPConfiguration

java.lang.Object

com.deltaxml.cores9api.AbstractDPConfigurationS9

com.deltaxml.cores9api.DCPConfiguration

public class DCPConfiguration
extends com.deltaxml.cores9api.AbstractDPConfigurationS9

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

See Also:

DCP User Guide, DocumentComparator

Constructor Summary

Constructors

Constructor and Description
DCPConfiguration(java.io.File f) Creates a DCPConfiguration object from a DCP file.
DCPConfiguration(java.io.File f, boolean checkDCP) Creates a DCPConfiguration object from a DCP file.
DCPConfiguration(java.io.File f, net.sf.saxon.s9api.Processor suppliedProcessor) Creates a DCPConfiguration object from a DCP file.
DCPConfiguration(java.io.File f, net.sf.saxon.s9api.Processor suppliedProcessor, boolean checkDCP) Creates a DCPConfiguration object from a DCP file.
DCPConfiguration(org.xml.sax.InputSource dcpSource) Creates a DCPConfiguration object from an InputSource.
DCPConfiguration(org.xml.sax.InputSource dcpSource, boolean checkDCP) Creates a DCPConfiguration object from an InputSource.
DCPConfiguration(org.xml.sax.InputSource dcpSource, net.sf.saxon.s9api.Processor suppliedProcessor) Creates a DCPConfiguration object from an InputSource.
DCPConfiguration(org.xml.sax.InputSource dcpSource, net.sf.saxon.s9api.Processor suppliedProcessor, boolean checkDCP) Creates a DCPConfiguration object from an InputSource.
DCPConfiguration(net.sf.saxon.s9api.XdmNode dcpNode) Creates a DCPConfiguration object from a supplied XdmNode tree.
DCPConfiguration(net.sf.saxon.s9api.XdmNode dcpNode, boolean checkDCP) Creates a DCPConfiguration 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 DocumentComparator.
DocumentComparator	getComparator() Returns the configured DocumentComparator instance.
DocumentComparator	getDocumentComparator() Deprecated. This method is deprecated and will be removed in the next major release. Use DCPConfiguration.getComparator() instead.
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.
java.lang.String	getResolvedParameterValue(java.lang.String parameterName) Returns the resolved value of the specified pipelineParameter in the DCP.
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 DCP 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

DCPConfiguration

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

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

DCPConfiguration

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

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

DCPConfiguration

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

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

DCPConfiguration

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

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

DCPConfiguration

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

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 PDFilterConfigurationException,
                            DynamicPDFormatException,
                            PDAdvancedConfigException,
                            java.lang.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

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

getComparator

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

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

getDocumentComparator

@Deprecated
public DocumentComparator getDocumentComparator()
                                                     throws java.lang.IllegalStateException

Deprecated. This method is deprecated and will be removed in the next major release. Use DCPConfiguration.getComparator() instead.

Returns the configured DocumentComparator instance.

Returns:

the DCP-configured DocumentComparator

Throws:

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

See Also:

DCPConfiguration.getComparator()

getResolvedParameterValue

public java.lang.String getResolvedParameterValue(java.lang.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,
                     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