com.deltaxml.cores9api

Class DXPConfigurationS9

java.lang.Object

com.deltaxml.cores9api.AbstractDPConfigurationS9

com.deltaxml.cores9api.DXPConfigurationS9

public class DXPConfigurationS9
extends com.deltaxml.cores9api.AbstractDPConfigurationS9

Loads a PipelinedComparatorS9 from a DXP configuration.

DXP (DeltaXML Pipelines) is a declarative file format for describing comparator pipelines and could also be considered a form of customization language for comparator based tools. It supports DXP file format versions 1.0-2.4 as discussed in DXP User Guide.

This class provides methods for obtaining information from DXP files and also for loading a PipelinedComparatorS9 instance from DXP. The constructor of this class is generally responsible for ensuring validity of the input DXP.

Since:

6.0

See Also:

DXP User Guide, PipelinedComparatorS9

Constructor Summary

Constructors

Constructor and Description
DXPConfigurationS9(java.io.File f) Creates a DXPConfigurationS9 object from a DXP file.
DXPConfigurationS9(org.xml.sax.InputSource dxpSource) Creates a DXPConfigurationS9 object from an InputSource.
DXPConfigurationS9(org.xml.sax.InputSource dxpSource, org.xml.sax.EntityResolver er, boolean validate) Creates a DXPConfigurationS9 object from a DXP InputSource.
DXPConfigurationS9(net.sf.saxon.s9api.XdmNode dxpSource) Creates a DXPConfigurationS9 object from a supplied XdmNode tree.

Method Summary

Modifier and Type	Method and Description
PipelinedComparatorS9	generate() Generates a PipelinedComparatorS9 from the DXP configuration loaded into this instance of a DXPConfigurationS9.
PipelinedComparatorS9	generate(java.util.Map<java.lang.String,java.lang.Boolean> booleanOverrides, java.util.Map<java.lang.String,java.lang.String> stringOverrides) Generates a PipelinedComparatorS9 from this instance of a DXPConfigurationS9.
PipelinedComparatorS9	generate(java.util.Map<java.lang.String,java.lang.Boolean> booleanOverrides, java.util.Map<java.lang.String,java.lang.String> stringOverrides, net.sf.saxon.s9api.Processor proc) Generates a PipelinedComparatorS9 from this instance of a DXPConfigurationS9.
java.lang.String	getFileExtension() Returns the contents of the DXP outputFileExtension/@extension attribute.
static java.lang.String	getFormattedPipelineSummaryTable(java.util.Collection<DXPConfigurationS9> dxpConfigs, int width, int indent) A table summarising the provided pipelines as a multi-line string.
boolean	isCorePipeline() States whether this represents a core (XML Compare) pipeline or not.

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

DXPConfigurationS9

public DXPConfigurationS9(java.io.File f)
                   throws ParserInstantiationException,
                          java.io.FileNotFoundException,
                          net.sf.saxon.s9api.SaxonApiException,
                          InvalidPipelineException

Creates a DXPConfigurationS9 object from a DXP file. Once loaded this Object can be queried for information from the DXP configuration and a PipelinedComparatorS9 object can be generated.

Parameters:

f - A File containing a DXP configuration

Throws:

ParserInstantiationException - if there are problems creating the parser

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

net.sf.saxon.s9api.SaxonApiException - if there are parsing errors or other s9api related problems

InvalidPipelineException - if the DXP contains errors (beyond standard validation errors)

See Also:

DXPConfigurationS9.generate(Map, Map), DXPConfigurationS9.generate()

DXPConfigurationS9

public DXPConfigurationS9(org.xml.sax.InputSource dxpSource,
                          org.xml.sax.EntityResolver er,
                          boolean validate)
                   throws ParserInstantiationException,
                          net.sf.saxon.s9api.SaxonApiException,
                          InvalidPipelineException

Creates a DXPConfigurationS9 object from a DXP InputSource. Once loaded this Object can be queried for information from the DXP configuration and a PipelinedComparatorS9 object can be generated. This method allows the user to control entity resolving and validation associated with the InputSource. Normally validation is strongly recommended and in order to validate a systemId should be associated with the InputSource so that a DTD can be located using relative URLs. Note: Please only consider this method after considering the other DXPConfiguration constructors, as invalid DXP files may produce unpredictable results.

Parameters:

dxpSource - An InputSource describing a DXP configuration

er - An EntityResolver for dealing with DTD and other external URL references

validate - controls parser validation (requires uses of a DTD)

Throws:

ParserInstantiationException - if there are problems creating the parser

net.sf.saxon.s9api.SaxonApiException - if there are parsing errors or other s9api related problems

InvalidPipelineException - if the DXP contains errors (beyond standard validation errors)

See Also:

DXPConfigurationS9.generate(Map, Map), DXPConfigurationS9.generate()

DXPConfigurationS9

public DXPConfigurationS9(org.xml.sax.InputSource dxpSource)
                   throws ParserInstantiationException,
                          net.sf.saxon.s9api.SaxonApiException,
                          InvalidPipelineException

Creates a DXPConfigurationS9 object from an InputSource. Unlike other constructors there is no option to control entity resolving and validation is always performed. It is recommended that the supplied InputSource should have a systemId set, otherwise validation issues may arise.

Parameters:

dxpSource - An InputSource describing a DXP configuration

Throws:

ParserInstantiationException - if there are problems creating the parser

net.sf.saxon.s9api.SaxonApiException - if there are parsing errors or other s9api related problems

InvalidPipelineException - if the DXP contains errors (beyond standard validation errors)

DXPConfigurationS9

public DXPConfigurationS9(net.sf.saxon.s9api.XdmNode dxpSource)
                   throws InvalidPipelineException,
                          java.lang.IllegalArgumentException

Creates a DXPConfigurationS9 object from a supplied XdmNode tree. As such a tree will have been parsed there is no opportunity for DTD based validity checking. Users must ensure that the supplied tree is valid.

Parameters:

dxpSource - An XdmNode tree containing a DXP pipeline definition

Throws:

InvalidPipelineException - if the DXP contains errors (beyond standard validation errors)

java.lang.IllegalArgumentException - if the supplied XdmNode is not a DOCUMENT or ELEMENT node

Method Detail

generate

public final PipelinedComparatorS9 generate(java.util.Map<java.lang.String,java.lang.Boolean> booleanOverrides,
                                            java.util.Map<java.lang.String,java.lang.String> stringOverrides)
                                     throws java.lang.ClassNotFoundException,
                                            java.net.MalformedURLException,
                                            ParserInstantiationException,
                                            FilterClassInstantiationException,
                                            FilterClassIncompatibilityException,
                                            FilterConfigurationException,
                                            FilterParameterizationException,
                                            FeatureNotRecognizedException,
                                            FeatureSettingNotSupportedException,
                                            PropertyNotRecognizedException,
                                            ParameterValueConflict,
                                            NonUniqueParameterNameException,
                                            UnknownParameterException,
                                            ComparatorInstantiationException,
                                            ConditionalFilterXPathException,
                                            XPathFilterParameterException

Generates a PipelinedComparatorS9 from this instance of a DXPConfigurationS9.

This method allows parameters to be overridden when the pipeline is constructed. The Map arguments should correspond to the declared 'pipelineParameters' in the associated DXP. An easy way to achieve this is to use and modify the Maps returned with AbstractDPConfigurationS9.getBooleanParameters() and AbstractDPConfigurationS9.getStringParameters().

This method throws a large number of exceptions. Further details of the circumstances in which they are thrown are documented in the javadoc descriptions of the Exception classes themselves. Should fine-grain exception handling not be required, it is possible to catch the PipelinedComparatorException, DXPConfigurationException or DeltaXMLException supertypes for all but two (ClassNotFoundException and MalformedURLException) of the exceptions thrown by this method.

Parameters:

booleanOverrides - parameter settings to override the boolean pipeline parameters

stringOverrides - parameter settings to override the string pipeline parameters

Returns:

a configured PipelineComparatorS9

Throws:

java.lang.ClassNotFoundException - if a class specified in a DXP class element cannot be located

java.net.MalformedURLException - if a DXP URL elements contents are malformed

ParserInstantiationException - if the PipelinedComparatorS9 constructor throws this exception

FilterClassInstantiationException - if there are problems instantiating a Java class based filter

FilterClassIncompatibilityException - if a class is not of the correct type

FilterConfigurationException - if there is a problem instantiating or configuring an XSLT based filter

FilterParameterizationException - if there are problems setting the parameters on a Java filter

FeatureNotRecognizedException - if the feature, in a parserFeature element, is not recognized

FeatureSettingNotSupportedException - if the setting of the specified parser feature is not supported

PropertyNotRecognizedException - if the specified outputProperty is not recognized

ParameterValueConflict - if the attributes used to specify a filter or other parameter are in conflict

NonUniqueParameterNameException - if the PipelineParameter names are not unique

UnknownParameterException - if the referenced parameter name is not known/declared

ComparatorInstantiationException - if the comparator used in the pipeline cannot be instantiated

ConditionalFilterXPathException - if there is a problem with an XPath expression on a conditional filter

XPathFilterParameterException - if there is a problem with an XPath expression being used as a filter parameter

generate

public final PipelinedComparatorS9 generate(java.util.Map<java.lang.String,java.lang.Boolean> booleanOverrides,
                                            java.util.Map<java.lang.String,java.lang.String> stringOverrides,
                                            net.sf.saxon.s9api.Processor proc)
                                     throws java.lang.ClassNotFoundException,
                                            java.net.MalformedURLException,
                                            ParserInstantiationException,
                                            FilterClassInstantiationException,
                                            FilterClassIncompatibilityException,
                                            FilterConfigurationException,
                                            FilterParameterizationException,
                                            FeatureNotRecognizedException,
                                            FeatureSettingNotSupportedException,
                                            PropertyNotRecognizedException,
                                            ParameterValueConflict,
                                            NonUniqueParameterNameException,
                                            UnknownParameterException,
                                            ComparatorInstantiationException,
                                            java.lang.IllegalArgumentException,
                                            ConditionalFilterXPathException,
                                            XPathFilterParameterException

Generates a PipelinedComparatorS9 from this instance of a DXPConfigurationS9.

This method allows a Saxon s9api Processor to be specified and should be used if you intend to supply XdmNode inputs to the generated PipelinedComparatorS9.

This method allows parameters to be overridden when the pipeline is constructed. The Map arguments should correspond to the declared 'pipelineParameters' in the associated DXP. An easy way to achieve this is to use and modify the Maps returned with AbstractDPConfigurationS9.getBooleanParameters() and AbstractDPConfigurationS9.getStringParameters().

This method throws a large number of exceptions. Further details of the circumstances in which they are thrown are documented in the javadoc descriptions of the Exception classes themselves. Should fine-grain exception handling not be required, it is possible to catch the PipelinedComparatorException, DXPConfigurationException or DeltaXMLException supertypes for all but two (ClassNotFoundException and MalformedURLException) of the exceptions thrown by this method.

Parameters:

booleanOverrides - parameter settings to override the boolean pipeline parameters

stringOverrides - parameter settings to override the string pipeline parameters

proc - a Saxon processor to be used for the NamePool and filter compilation

Returns:

a configured PipelineComparatorS9

Throws:

java.lang.ClassNotFoundException - if a class specified in a DXP class element cannot be located

java.net.MalformedURLException - if a DXP URL elements contents are malformed

ParserInstantiationException - if the PipelinedComparatorS9 constructor throws this exception

FilterClassInstantiationException - if there are problems instantiating a Java class based filter

FilterClassIncompatibilityException - if a class is not of the correct type

FilterConfigurationException - if there is a problem instantiating or configuring an XSLT based filter

FilterParameterizationException - if there are problems setting the parameters on a Java filter

FeatureNotRecognizedException - if the feature, in a parserFeature element, is not recognized

FeatureSettingNotSupportedException - if the setting of the specified parser feature is not supported

PropertyNotRecognizedException - if the specified outputProperty is not recognized

ParameterValueConflict - if the attributes used to specify a filter or other parameter are in conflict

NonUniqueParameterNameException - if the PipelineParameter names are not unique

UnknownParameterException - if the referenced parameter name is not known/declared

ComparatorInstantiationException - if the comparator used in the pipeline cannot be instantiated

java.lang.IllegalArgumentException - if the Processor argument is null

ConditionalFilterXPathException - if there is a problem with an XPath expression on a conditional filter

XPathFilterParameterException - if there is a problem with an XPath expression being used as a filter parameter

isCorePipeline

public boolean isCorePipeline()

States whether this represents a core (XML Compare) pipeline or not. As .dxp is a common file extension for core dxp files and sync dxp files, this method provides an easy way of determining if this dxp file represents a core pipeline.

Returns:

true if this is a comparator pipeline, otherwise false

getFileExtension

public java.lang.String getFileExtension()

Returns the contents of the DXP outputFileExtension/@extension attribute. This can be used by applications to alter the behaviour of an application based on the type of data generated. For example a pipeline producing HTML, using an extension of "html", may be processed differently (shown in a browser), to a pipeline with an "xml" extension.

Returns:

the extension attribute, or the default value of "xml"

generate

public final PipelinedComparatorS9 generate()
                                     throws java.lang.ClassNotFoundException,
                                            java.net.MalformedURLException,
                                            ParserInstantiationException,
                                            FilterClassInstantiationException,
                                            FilterClassIncompatibilityException,
                                            FilterConfigurationException,
                                            FilterParameterizationException,
                                            FeatureNotRecognizedException,
                                            FeatureSettingNotSupportedException,
                                            PropertyNotRecognizedException,
                                            ParameterValueConflict,
                                            NonUniqueParameterNameException,
                                            UnknownParameterException,
                                            ComparatorInstantiationException,
                                            ConditionalFilterXPathException,
                                            XPathFilterParameterException

Generates a PipelinedComparatorS9 from the DXP configuration loaded into this instance of a DXPConfigurationS9. This method allows does not allow parameter overriding.

This method throws a large number of exceptions. Further details of the circumstances in which they are thrown are documented in the javadoc descriptions of the Exception classes themselves. Should fine-grain exception handling not be required, it is possible to catch the PipelinedComparatorException, DXPConfigurationException or DeltaXMLException supertypes for all but two (ClassNotFoundException and MalformedURLException) of the exceptions thrown by this method.

Returns:

a configured PipelineComparatorS9

Throws:

java.lang.ClassNotFoundException - if a class specified in a DXP class element cannot be located

java.net.MalformedURLException - if a DXP URL elements contents are malformed

ParserInstantiationException - if the PipelinedComparatorS9 constructor throws this exception

FilterClassInstantiationException - if there are problems instantiating a Java class based filter

FilterClassIncompatibilityException - if a class is not of the correct type

FilterConfigurationException - if there is a problem instantiating or configuring an XSLT based filter

FilterParameterizationException - if there are problems setting the parameters on a Java filter

FeatureNotRecognizedException - if the feature, in a parserFeature element, is not recognized

FeatureSettingNotSupportedException - if the setting of the specified parser feature is not supported

PropertyNotRecognizedException - if the specified outputProperty is not recognized

ParameterValueConflict - if the attributes used to specify a filter or other parameter are in conflict

NonUniqueParameterNameException - if the PipelineParameter names are not unique

UnknownParameterException - if the referenced parameter name is not known/declared

ComparatorInstantiationException - if the comparator used in the pipeline cannot be instantiated

ConditionalFilterXPathException - if there is a problem with an XPath expression on a conditional filter

XPathFilterParameterException - if there is a problem with an XPath expression being used as a filter parameter

getFormattedPipelineSummaryTable

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

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:

dxpConfigs - 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