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 DCPConfiguration.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 DocumentComparator.
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 DocumentComparator using passed parameter values.
DocumentComparator	getDocumentComparator() Returns the configured DocumentComparator instance.
static java.lang.String	getFormattedPipelineSummaryTable(java.util.Collection<DCPConfiguration> dcpConfigs, int width, int indent) Returns a table summarizing 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 DCP.
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 DCPConfiguration.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 DCPConfiguration.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 DCPConfiguration.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 DCPConfiguration.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()
              throws StaticPDFormatException,
                     PDFilterConfigurationException,
                     DynamicPDFormatException,
                     PDAdvancedConfigException,
                     java.lang.IllegalStateException

Initializes the internal instance of DocumentComparator. This method must only be called once.

Throws:

DynamicPDFormatException - if problem found when attempting to resolve DCP values

PDFilterConfigurationException - if problem found when loading an XML filter

StaticPDFormatException - if resolved DCP values are invalid

PDAdvancedConfigException - when properties or features in 'advancedConfig' element cause an error

java.lang.IllegalStateException - if called more than once

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

Initializes the internal instance of DocumentComparator using passed parameter values. This method must only be called once.

Parameters:

booleanOverrides - set parameter values for DCP-defined boolean pipeline parameters

stringOverrides - set parameter values for DCP-defined string pipeline parameters

Throws:

StaticPDFormatException - if problem occurred when preparing to resolve DCP values

DynamicPDFormatException - if problem found while resolving DCP values

PDFilterConfigurationException - if problem found when loading an XML filter

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 DCPConfiguration.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 DCPConfiguration.generate() method has not been called first

getDocumentComparator

public DocumentComparator getDocumentComparator()
                                         throws java.lang.IllegalStateException

Returns the configured DocumentComparator instance. Must be used after the DCPConfiguration.generate() method is called to initialize the DocumentComparator

Returns:

the DCP-configured DocumentComparator

Throws:

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

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 DCPConfiguration.generate() method has not been called first

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 DCP. Processing instruction values are available as soon as the DCPConfiguration 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

getFormattedPipelineSummaryTable

public static java.lang.String getFormattedPipelineSummaryTable(java.util.Collection<DCPConfiguration> dcpConfigs,
                                                                int width,
                                                                int indent)

Returns a table summarizing 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:

dcpConfigs - The dcpConfigurations to summarize.

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 summarizing the provided pipeline as a multi-line string.