Package com.deltaxml.docbook

Class DocBookCompare

java.lang.Object

com.deltaxml.docbook.DocBookCompare

public final class DocBookCompare
extends Object

The main class for DeltaXML DocBook Compare.

Produces a DocBook result document from two input DocBook documents that contains revisionflag attributes indicating changes between the two inputs.

This product supports DocBook version 4.x and DocBook version 5 and the use of the new DocBook namespace.

N.B. It is not possible to compare a DocBook 4 input with a DocBook 5 input that uses namespaces.

Constructor Summary

Constructors

Constructor	Description
DocBookCompare()	Constructs a new DocBookCompare instance.

Method Summary

Modifier and Type	Method	Description
void	addDocBookCompareProgressListener(DocBookCompareProgressListener listener)	Adds a progress listener to the list of registered progress listeners.
void	addLicenseFile(File licenseFile)	Adds the license file for use with Flexera licensing.
void	addLicenseServer(String hostname)	Adds a license server for use with concurrent licensing.
void	addLicenseServer(String hostname, int port)	Adds a license server and port for use with concurrent licensing.
void	compare(File input1, File input2, File result)	Compares two File inputs to produce a File result.
void	compare(InputStream is1, String systemId1, InputStream is2, String systemId2, OutputStream result)	Compares two input streams to produce an output stream result.
void	compare(Reader r1, String systemId1, Reader r2, String systemId2, Writer result)	Compares two input reader (character streams) to produce an output writer result.
String	compare(String input1, String systemId1, String input2, String systemId2)	Compares two XML string inputs to produce an XML string result.
void	compare(InputSource input1, InputSource input2, StreamResult result)	Compares two InputSource inputs to produce a StreamResult.
AdvancedParameters	getAdvancedParameters()	Get the AdvancedParameters in use by this DocBookCompare.
boolean	getDebugFiles()	Gets whether the production of debug files is on or not.
String	getDebugFilesPrefix()	Get the current prefix used for debug result files.
EntityResolver	getEntityResolver()	Gets the explicitly set EntityResolver in use by the comparison.
EntityResolver	getEntityResolver(boolean builtInResolver)	Gets the EntityResolver in use by the comparison.
FormattingElementsConfig	getFormattingElementsConfig()	Get the FormattingElementsConfig in use by this DocBookCompare.
ImageConfiguration	getImageConfiguration()	Get the ImageConfiguration in use by this DocBookCompare.
MathMLConfig	getMathmlConfig()	Get the MathMLConfig in use by this DocBookCompare.
MovesConfig	getMovesConfig()	Get the MovesConfig in use by this DocBookCompare.
OutputParameters	getOutputParameters()	Get the OutputParameters in use by this DocBookCompare.
SVGConfig	getSvgConfig()	Get the SVGConfig in use by this DocBookCompare.
TableConfig	getTableConfig()	Get the TableConfig in use by this DocBookCompare.
TextComparisonConfig	getTextComparisonConfig()	Get the TextComparisonConfig in use by this DocBookCompare.
URIResolver	getURIResolver()	Gets the explicitly set URIResolver in use by the comparison.
URIResolver	getURIResolver(boolean builtInResolver)	Gets the URIResolver in use by the comparison.
void	removeDocBookCompareProgressListener(DocBookCompareProgressListener listener)	Remove the first occurrence of the progress listener from the registered progress listener list.
void	setAdvancedParameters(AdvancedParameters advancedParameters)	Set the AdvancedParameters in use by this DocBookCompare.
void	setDebugFiles(boolean enableDebug)	Determines whether intermediate pipeline result files are generated.
void	setDebugFilesPrefix(String prefix)	Provide a prefix for debug result files.
void	setEntityResolver(EntityResolver resolver, boolean fallbackToDefaultCatalogResolver)	Sets the EntityResolver to use during the comparison.
void	setFormattingElementsConfig(FormattingElementsConfig formattingElementsConfig)	Set the FormattingElementsConfig in use by this DocBookCompare.
void	setImageConfiguration(ImageConfiguration imageConfiguration)	Set the ImageConfiguration in use by this DocBookCompare.
void	setMathmlConfig(MathMLConfig mathmlConfig)	Set the MathMLConfig in use by this DocBookCompare.
void	setMovesConfig(MovesConfig movesConfig)	Set the MovesConfig in use by this DocBookCompare.
void	setOutputParameters(OutputParameters outputParameters)	Set the OutputParameters in use by this DocBookCompare.
void	setSvgConfig(SVGConfig svgConfig)	Set the SVGConfig in use by this DocBookCompare.
void	setTableConfig(TableConfig tableConfig)	Set the TableConfig in use by this DocBookCompare.
void	setTextComparisonConfig(TextComparisonConfig textComparisonConfig)	Set the TextComparisonConfig in use by this DocBookCompare.
void	setURIResolver(URIResolver resolver, boolean fallbackToDefaultCatalogResolver)	Sets the URIResolver to use during the comparison.

Methods inherited from class java.lang.Object

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

Constructor Details

DocBookCompare

public DocBookCompare()
               throws ParserException

Constructs a new DocBookCompare instance.

Throws:

ParserException - when there is a problem creating/configuring a parser

Method Details

addDocBookCompareProgressListener

public void addDocBookCompareProgressListener(DocBookCompareProgressListener listener)

Adds a progress listener to the list of registered progress listeners. The same listener may be added more than once.

Parameters:

listener - the progress listener to add.

removeDocBookCompareProgressListener

public void removeDocBookCompareProgressListener(DocBookCompareProgressListener listener)

Remove the first occurrence of the progress listener from the registered progress listener list.

Parameters:

listener - the progress listener to remove.

setEntityResolver

public void setEntityResolver(EntityResolver resolver,
 boolean fallbackToDefaultCatalogResolver)

Sets the EntityResolver to use during the comparison.

By default, the Apache Commons Resolver is used as an EntityResolver. If you wish to use a different one, set it up using this method. Note you can turn off the default catalog support by providing a null resolver and setting the fallbackToDefaultCatalogResolver to false.

Parameters:

resolver - The resolver to use. Using null removes an existing resolver.

fallbackToDefaultCatalogResolver - Sets whether to use the inbuilt catalog resolver if the provided resolver fails to resolve the entity.

setURIResolver

public void setURIResolver(URIResolver resolver,
 boolean fallbackToDefaultCatalogResolver)

Sets the URIResolver to use during the comparison.

By default, the Apache Commons Resolver is used as an URIResolver. If you wish to use a different one, set it up using this method. Note you can turn off the default catalog support by providing a null resolver and setting the fallbackToDefaultCatalogResolver to false.

Parameters:

resolver - The resolver to use. Using null removes an existing resolver.

fallbackToDefaultCatalogResolver - Sets whether to use the inbuilt catalog resolver if the provided resolver fails to resolve the URI.

setDebugFilesPrefix

public void setDebugFilesPrefix(String prefix)

Provide a prefix for debug result files.

Parameters:

prefix - The prefix that will be used for debug file names in subsequent compare operations.

See Also:

• setDebugFiles(boolean)

getDebugFilesPrefix

public String getDebugFilesPrefix()

Get the current prefix used for debug result files.

Returns:

the current prefix used for debug result files.

See Also:

• setDebugFiles(boolean)

setDebugFiles

public void setDebugFiles(boolean enableDebug)

Determines whether intermediate pipeline result files are generated. When developing a pipelined application it is sometimes useful to see the intermediate results. This debug option when set will generate a file containing the XML corresponding the intermediate result of most of the pipeline stages.

Parameters:

enableDebug - when true intermediate result files are produced and stored in a directory using the debugFilesPrefix set.

See Also:

• setDebugFilesPrefix(String)

getDebugFiles

public boolean getDebugFiles()

Gets whether the production of debug files is on or not.

Returns:

whether the production of debug files is on or not.

See Also:

• setDebugFilesPrefix(String)

getEntityResolver

public EntityResolver getEntityResolver()

Gets the explicitly set EntityResolver in use by the comparison.

Returns:

the explicitly set EntityResolver in use by the comparison.

getEntityResolver

public EntityResolver getEntityResolver(boolean builtInResolver)

Gets the EntityResolver in use by the comparison.

Parameters:

builtInResolver - Whether to get the built in resolver (with any explicit enhancement), or just the explicitly set resolver.

Returns:

the explicitly set EntityResolver in use by the comparison.

getURIResolver

public URIResolver getURIResolver()

Gets the explicitly set URIResolver in use by the comparison.

Returns:

the explicitly set URIResolver in use by the comparison.

getURIResolver

public URIResolver getURIResolver(boolean builtInResolver)

Gets the URIResolver in use by the comparison.

Parameters:

builtInResolver - Whether to get the built in resolver (with any explicit enhancement), or just the explicitly set resolver.

Returns:

the explicitly set URIResolver in use by the comparison.

compare

public void compare(InputSource input1,
 InputSource input2,
 StreamResult result)
             throws ParserException,
SerializationException,
InputLoadException,
InvalidInputException,
FilterException,
InvalidParameterException,
DifferentRootElementException,
ComparisonCancelledException,
com.deltaxml.licensing.LicenseException

Compares two InputSource inputs to produce a StreamResult.

This is the most general of the compare methods, in the sense that all the other compare methods can (and are) written in terms of it. However, care must be taken to ensure that each InputSource is provided with an appropriate systemId (say via the InputSource's setSystemId method). This system identifer is used as the base-path for locating external resources (such as those provided by xi:includes and external entity references).

Note that the presence of a system id is not checked for as there are at least two plausible use cases where it is not required. First, simple documents that are self contained (i.e. have no external resource references) do not need to set a system Id, though it can still be useful for error reporting. Second, when catalogs are being used to provide access to external resources, then relative document based lookup mechanisms may not be required (as well).

Parameters:

input1 - the first input to compare as a Source object

input2 - the second input to compare as a Source object

result - the Result to which to write the comparison result

Throws:

com.deltaxml.licensing.LicenseException - when the license cannot be read or is not valid

ParserException - when there is a problem creating/configuring an XML parser

SerializationException - when there is a problem writing the result File

InputLoadException - when there is a problem loading an input File

FilterException - when an error occurs running a filter in the pipeline

DifferentRootElementException - if the two input Files have different roots

InvalidInputException - if an input file is not in the correct format

InvalidParameterException - if a previous parameter setting on the comparator cannot be used at comparison time

ComparisonCancelledException - if a comparison is cancelled by some cancellation policy

compare

public void compare(File input1,
 File input2,
 File result)
             throws ParserException,
FileNotFoundException,
SerializationException,
InputLoadException,
FilterException,
DifferentRootElementException,
InvalidInputException,
InvalidParameterException,
ComparisonCancelledException,
com.deltaxml.licensing.LicenseException

Compares two File inputs to produce a File result.

Parameters:

input1 - the first input to compare as a File object

input2 - the second input to compare as a File object

result - the File in which to write the comparison result

Throws:

com.deltaxml.licensing.LicenseException - when the license cannot be read or is not valid

ParserException - when there is a problem creating/configuring an XML parser

FileNotFoundException - when an input File or the location of the result File cannot be found

SerializationException - when there is a problem writing the result File

InputLoadException - when there is a problem loading an input File

FilterException - when an error occurs running a filter in the pipeline

DifferentRootElementException - if the two input Files have different roots

InvalidInputException - if an input file is not in the correct format

InvalidParameterException - if a previous parameter setting on the comparator cannot be used at comparison time

ComparisonCancelledException - if a comparison is cancelled by some cancellation policy

compare

public void compare(Reader r1,
 String systemId1,
 Reader r2,
 String systemId2,
 Writer result)
             throws ParserException,
SerializationException,
InputLoadException,
FilterException,
DifferentRootElementException,
InvalidInputException,
InvalidParameterException,
ComparisonCancelledException,
com.deltaxml.licensing.LicenseException

Compares two input reader (character streams) to produce an output writer result.

Parameters:

r1 - the first input to compare

systemId1 - the location of the first input stream (for relative lookup)

r2 - the second input to compare

systemId2 - the location of the second input stream (for relative lookup)

result - the writer in which to write the comparison result

Throws:

com.deltaxml.licensing.LicenseException - when the license cannot be read or is not valid

ParserException - when there is a problem creating/configuring an XML parser

SerializationException - when there is a problem writing the result File

InputLoadException - when there is a problem loading an input File

FilterException - when an error occurs running a filter in the pipeline

DifferentRootElementException - if the two input Files have different roots

InvalidInputException - if an input file is not in the correct format

InvalidParameterException - if a previous parameter setting on the comparator cannot be used at comparison time

ComparisonCancelledException - if a comparison is cancelled by some cancellation policy

compare

public void compare(InputStream is1,
 String systemId1,
 InputStream is2,
 String systemId2,
 OutputStream result)
             throws ParserException,
SerializationException,
InputLoadException,
FilterException,
DifferentRootElementException,
InvalidInputException,
InvalidParameterException,
ComparisonCancelledException,
com.deltaxml.licensing.LicenseException

Compares two input streams to produce an output stream result.

Parameters:

is1 - the first input to compare

systemId1 - the location of the first input stream (for relative lookup)

is2 - the second input to compare

systemId2 - the location of the second input stream (for relative lookup)

result - the output stream in which to write the comparison result

Throws:

com.deltaxml.licensing.LicenseException - when the license cannot be read or is not valid

ParserException - when there is a problem creating/configuring an XML parser

SerializationException - when there is a problem writing the result File

InputLoadException - when there is a problem loading an input File

FilterException - when an error occurs running a filter in the pipeline

DifferentRootElementException - if the two input Files have different roots

InvalidInputException - if an input file is not in the correct format

InvalidParameterException - if a previous parameter setting on the comparator cannot be used at comparison time

ComparisonCancelledException - if a comparison is cancelled by some cancellation policy

compare

public String compare(String input1,
 String systemId1,
 String input2,
 String systemId2)
               throws ParserException,
SerializationException,
InputLoadException,
FilterException,
DifferentRootElementException,
InvalidInputException,
InvalidParameterException,
ComparisonCancelledException,
com.deltaxml.licensing.LicenseException

Compares two XML string inputs to produce an XML string result.

Parameters:

input1 - the first input to compare as a string containing an XML document

systemId1 - the location of the first input (for relative lookup)

input2 - the second input to compare as a string containing an XML document

systemId2 - the location of the second input (for relative lookup)

Returns:

the comparison result as a string containing an XML document

Throws:

com.deltaxml.licensing.LicenseException - when the license cannot be read or is not valid

ParserException - when there is a problem creating/configuring an XML parser

SerializationException - when there is a problem writing the result File

InputLoadException - when there is a problem loading an input File

FilterException - when an error occurs running a filter in the pipeline

DifferentRootElementException - if the two input Files have different roots

InvalidInputException - if an input file is not in the correct format

InvalidParameterException - if a previous parameter setting on the comparator cannot be used at comparison time

ComparisonCancelledException - if a comparison is cancelled by some cancellation policy

addLicenseFile

public void addLicenseFile(File licenseFile)
                    throws SecurityException,
IOException,
com.deltaxml.licensing.LicenseException

Adds the license file for use with Flexera licensing. This can be either simple server/named-user license file or a concurrent license file containing the USE_SERVER directive

Parameters:

licenseFile - the FlexLM format license file

Throws:

com.deltaxml.licensing.LicenseSecurityException - if the file cannot be accessed

IOException - if there are problems reading the file

com.deltaxml.licensing.LicenseException - if there is a problem using the license file

SecurityException

addLicenseServer

public void addLicenseServer(String hostname)
                      throws com.deltaxml.licensing.LicenseException

Adds a license server for use with concurrent licensing.

Parameters:

hostname - of the license server host or its ip address

Throws:

com.deltaxml.licensing.LicenseException - if there is a problem using the license server

addLicenseServer

public void addLicenseServer(String hostname,
 int port)
                      throws IllegalArgumentException,
com.deltaxml.licensing.LicenseException

Adds a license server and port for use with concurrent licensing.

Parameters:

hostname - of the license server host or its ip address

port - the port number on the license server for the lmgrd

Throws:

IllegalArgumentException - if the port number is out of range

com.deltaxml.licensing.LicenseException - if there is a problem using the license server

getTextComparisonConfig

public TextComparisonConfig getTextComparisonConfig()

Get the TextComparisonConfig in use by this DocBookCompare. The TextComparisonConfig contains parameters that control how text is compared during the comparison.

Returns:

the active TextComparisonConfig in use by this DocBookCompare

See Also:

• TextComparisonConfig

setTextComparisonConfig

public void setTextComparisonConfig(TextComparisonConfig textComparisonConfig)

Set the TextComparisonConfig in use by this DocBookCompare. The TextComparisonConfig contains parameters that control how text is compared during the comparison.

Parameters:

textComparisonConfig - the TextComparisonConfig to use

Throws:

IllegalArgumentException - if passed TextComparisonConfig is null

See Also:

• TextComparisonConfig

getTableConfig

public TableConfig getTableConfig()

Get the TableConfig in use by this DocBookCompare. The TableConfig contains parameters that control how tables are handled and compared.

Returns:

the active TableConfig in use by this DocBookCompare

See Also:

• TableConfig

setTableConfig

public void setTableConfig(TableConfig tableConfig)

Set the TableConfig in use by this DocBookCompare. The TableConfig contains parameters that control how tables are handled and compared.

Parameters:

tableConfig - the TableConfig to use

Throws:

IllegalArgumentException - if passed TableConfig is null

See Also:

• TableConfig

getFormattingElementsConfig

public FormattingElementsConfig getFormattingElementsConfig()

Get the FormattingElementsConfig in use by this DocBookCompare. The FormattingElementsConfig contains parameters that control how formatting elements are defined and compared.

Returns:

the active FormattingElementsConfig in use by this DocBookCompare

See Also:

• FormattingElementsConfig

setFormattingElementsConfig

public void setFormattingElementsConfig(FormattingElementsConfig formattingElementsConfig)

Set the FormattingElementsConfig in use by this DocBookCompare. The FormattingElementsConfig contains parameters that control how formatting elements are defined and compared.

Parameters:

formattingElementsConfig - the FormattingElementsConfig to use

Throws:

IllegalArgumentException - if passed FormattingElementsConfig is null

See Also:

• FormattingElementsConfig

getMathmlConfig

public MathMLConfig getMathmlConfig()

Get the MathMLConfig in use by this DocBookCompare. The MathMLConfig contains parameters that control how and if MathML content is specially handled.

Returns:

the active MathMLConfig in use by this DocBookCompare

See Also:

• MathMLConfig

setMathmlConfig

public void setMathmlConfig(MathMLConfig mathmlConfig)

Set the MathMLConfig in use by this DocBookCompare. The MathMLConfig contains parameters that control how and if MathML content is specially handled.

Parameters:

mathmlConfig - the MathMLConfig to use

Throws:

IllegalArgumentException - if passed MathMLConfig is null

See Also:

• MathMLConfig

getImageConfiguration

public ImageConfiguration getImageConfiguration()

Get the ImageConfiguration in use by this DocBookCompare. The ImageConfiguration contains parameters that control how and if referenced image content is compared.

Returns:

the active ImageConfiguration in use by this DocBookCompare

See Also:

• ImageConfiguration

setImageConfiguration

public void setImageConfiguration(ImageConfiguration imageConfiguration)

Set the ImageConfiguration in use by this DocBookCompare. The ImageConfiguration contains parameters that control how and if referenced image content is compared.

Parameters:

imageConfiguration - the ImageConfiguration to use

Throws:

IllegalArgumentException - if passed ImageConfiguration is null

See Also:

• ImageConfiguration

getMovesConfig

public MovesConfig getMovesConfig()

Get the MovesConfig in use by this DocBookCompare. The MovesConfig contains parameters that control how and if element moves are shown and how they are represented.

Returns:

the active MovesConfig in use by this DocBookCompare

See Also:

• MovesConfig

setMovesConfig

public void setMovesConfig(MovesConfig movesConfig)

Set the MovesConfig in use by this DocBookCompare. The MovesConfig contains parameters that control how and if element moves are shown and how they are represented.

Parameters:

movesConfig - the MovesConfig to use

Throws:

IllegalArgumentException - if passed MovesConfig is null

See Also:

• MovesConfig

getSvgConfig

public SVGConfig getSvgConfig()

Get the SVGConfig in use by this DocBookCompare. The SVGConfig contains parameters that control how SVG comparison is performed and the output is displayed.

Returns:

the active SVGConfig in use by this DocBookCompare

See Also:

• SVGConfig

setSvgConfig

public void setSvgConfig(SVGConfig svgConfig)

Set the SVGConfig in use by this DocBookCompare. The SVGConfig contains parameters that control how SVG comparison is performed and the output is displayed.

Parameters:

svgConfig - the SVGConfig to use

Throws:

IllegalArgumentException - if passed SVGConfig is null

See Also:

• SVGConfig

getOutputParameters

public OutputParameters getOutputParameters()

Get the OutputParameters in use by this DocBookCompare. The OutputParameters contains parameters that control how the result of the comparison is presented.

Returns:

the active OutputParameters in use by this DocBookCompare

See Also:

• OutputParameters

setOutputParameters

public void setOutputParameters(OutputParameters outputParameters)

Set the OutputParameters in use by this DocBookCompare. The OutputParameters contains parameters that control how the result of the comparison is presented.

Parameters:

outputParameters - the OutputParameters to use

Throws:

IllegalArgumentException - if passed OutputParameters is null

See Also:

• OutputParameters

getAdvancedParameters

public AdvancedParameters getAdvancedParameters()

Get the AdvancedParameters in use by this DocBookCompare. The AdvancedParameters provide a finer level of control over the comparison, the output, and error reporting.

Returns:

the active AdvancedParameters in use by this DocBookCompare

See Also:

• AdvancedParameters

setAdvancedParameters

public void setAdvancedParameters(AdvancedParameters advancedParameters)

Set the AdvancedParameters in use by this DocBookCompare. The AdvancedParameters provide a finer level of control over the comparison, the output, and error reporting.

Parameters:

advancedParameters - the AdvancedParameters to use

Throws:

IllegalArgumentException - if passed AdvancedParameters is null

See Also:

• AdvancedParameters