Package com.deltaxml.ditamerge

Class ThreeWayMerge

java.lang.Object

com.deltaxml.ditamerge.ThreeWayMerge

All Implemented Interfaces:

MergeBase, MergeCommon

public class ThreeWayMerge
extends Object
implements MergeCommon

The main class for three-way concurrent DITA merge operations.

This class provides further output types beyond those provided in the ConcurrentMerge class because some specific three-way processing is possible when three inputs can be guaranteed. A set of 'single shot' merge methods are also provided, these avoid the use of the setAncestor/addVersion/extract methods that are used in the n-way class.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	ThreeWayMerge.TwoWayResultFormat

Field Summary

Fields inherited from interface com.deltaxml.mergecommon.MergeCommon

MERGE_REST_CONFIG_NAMESPACE

Constructor Summary

Constructors

Constructor	Description
ThreeWayMerge()	Constructs a new ThreeWayMerge instance.

Method Summary

Modifier and Type	Method	Description
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	addProgressListener(MergeProgressListener listener)	Add a progress listener to the list of registered progress listeners.
void	addVersion(File file, String version)	Adds a version with a File input.
void	addVersion(InputStream is, String systemId, String version)	Adds a version with an input stream input.
void	addVersion(Reader r, String systemId, String version)	Adds a version with a File input.
void	addVersion(URL url, String version)	Adds a version with a URL input.
void	clearProgressListeners()	Remove all currently registered progress listeners.
void	extractAll(File file)	Extracts the entire content of all added versions of the Merger to a File using the deltaV2 merge format.
void	extractAll(OutputStream os)	Extracts the entire content of all added versions of the Merger to a OutputStream using the deltaV2 merge format.
void	extractAll(Writer w)	Extracts the entire content of all added versions of the Merger to a Writer using the deltaV2 merge format.
String	getAncestorVersion()	Returns the version name of the ancestor.
CalsTableConfiguration	getCalsTableConfiguration()	Returns the current configuration options for CALS table comparison.
ConcurrentMergeState	getCurrentState()	Returns the current state of the ThreeWayMerge object.
boolean	getDebugFiles()	Gets whether the production of debug files is on or not.
String	getDebugFilesPrefix()	Get the current prefix used for debug result files.
DoctypePreservationMode	getDoctypePreservationMode()	Reports the current mode.
boolean	getElementSplitting()	States whether modified elements containing text are split when the amount of unchanged text falls below 10%.
EntityReferencePreservationMode	getEntityReferencePreservationMode()	Reports the current mode.
EntityResolver	getEntityResolver()	Gets the explicitly set EntityResolver in use by the merger.
EntityResolver	getEntityResolver(boolean builtInResolver)	Gets the EntityResolver in use by the merger.
ExistingOxygenTCsProcessingMode	getExistingOxygenTCsProcessingMode()	Reports the existing oxygen TCs processing mode used with three way track change output.
List<String>	getFormatExtractionPriorityList()	Reports the current setting of the format extraction priority list.
FormattingElementsConfiguration	getFormattingElementsConfiguration()	Returns the currently used FormattingElementConfiguration object.
FormattingOutputType	getFormattingOutputType()	Get the output type used for representing formatting elements in the output.
HtmlTableConfiguration	getHtmlTableConfiguration()	Returns the current configuration options for HTML table comparison.
ThreeToTwoResultPreset	getResultPreset()	Reports preset of three to two way merge use cases.
RuleConfiguration	getRuleConfiguration()	Returns the currently used (for extract operations) rule configuration object.
ThreeWayMergeResultType	getThreeWayResultType()	Reports the result type setting for the Merger.
TrackChangesAttributeMode	getThreeWayTrackChangeAttributeMode()	Reports the attribute mode used with three way track change output.
ThreeWayMerge.TwoWayResultFormat	getTwoWayResultFormat()	Reports the result format setting for the Merger.
List<String>	getVersions()	Returns an immutable list of versions which have been added.
boolean	getWordByWord()	Reports the state of the WordByWord setting.
boolean	isNewTableProcessingEnabled()	Returns the current setting for new table processing.
void	merge(File ancestor, File edit1, File edit2, File result)	This method is used to perform three way merge of DITA inputs.
void	merge(InputStream ancestor, String systemIdAncestor, InputStream edit1, String systemIdEdit1, InputStream edit2, String systemIdEdit2, OutputStream result)	This method is used to perform three way merge of InputStreams.
void	merge(Reader ancestor, String systemIdAncestor, Reader edit1, String systemIdEdit1, Reader edit2, String systemIdEdit2, Writer result)	This method is used to perform three way merge with Readers.
void	removeProgressListener(MergeProgressListener listener)	Remove a progress listener from the list of registered progress listeners.
void	reset()	Reverts the state of the merger to the point where MergeCommon.setAncestor(java.io.File, String) can be used.
void	setAncestor(File file, String version)	Sets the ancestor document with a File input.
void	setAncestor(InputStream is, String systemId, String version)	Sets the ancestor document with a InputStream.
void	setAncestor(Reader r, String systemId, String version)	Sets the ancestor document with a Reader.
void	setAncestor(URL url, String version)	Sets the ancestor document with a URL.
void	setCalsTableConfiguration(CalsTableConfiguration config)	Sets the configuration options for CALS table comparison.
void	setDebugFiles(boolean debug)	Enables the generation of intermediate pipeline debug files.
void	setDebugFilesPrefix(String prefix)	Provides a prefix for debug result files.
void	setDoctypePreservationMode(DoctypePreservationMode mode)	Sets how Doctype declarations should be preserved in the result.
void	setElementSplitting(boolean enabled)	Sets whether modified elements containing text should be split when the amount of unchanged text falls below 10%.
void	setEntityReferencePreservationMode(EntityReferencePreservationMode mode)	Sets how Entity references should be preserved.
void	setEntityResolver(EntityResolver resolver, boolean fallbackToDefaultCatalogResolver)	Sets the EntityResolver to use during the comparison.
void	setExistingOxygenTCsProcessingMode(ExistingOxygenTCsProcessingMode mode)	Sets the existing oxygen TCs processing mode for three way track change output.
void	setFormatExtractionPriorityList(List<String> priorityList)	Merge operations represent overlapping hierarchies from the input documents by flattening and subsequently fragmenting formatting elements where necessary.
void	setFormattingElementsConfiguration(FormattingElementsConfiguration formattingElementsConfiguration)	Provides various settings for specifying formatting elements.
void	setFormattingOutputType(FormattingOutputType formattingOutputType)	Set the output type used for representing formatting elements in the output.
void	setHtmlTableConfiguration(HtmlTableConfiguration config)	Sets the configuration options for HTML table comparison.
void	setIndent(boolean indent)	Enables indentation of output using the serializer output indent property.
void	setResultPreset(ThreeToTwoResultPreset p)	Used to preset three to two way merge use cases.
void	setRuleConfiguration(RuleConfiguration rc)	Allows the rules for ditamerge processing (during extract operations) to be specified.
void	setTableProcessingAlgorithmVersion2(boolean value)	Enables new table processing algorithm for CALS and HTML table.
void	setThreeWayResultType(ThreeWayMergeResultType type)	Sets the type of result which this Merger will produce.
void	setThreeWayTrackChangeAttributeMode(TrackChangesAttributeMode mode)	Sets the attribute mode for three way track change output.
void	setTwoWayResultFormat(ThreeWayMerge.TwoWayResultFormat rf)	Sets the result format which this Merger will produce.
void	setWordByWord(boolean wbwValue)	Determines whether WordByWord filter is used.

Methods inherited from class java.lang.Object

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

Constructor Details

ThreeWayMerge

public ThreeWayMerge()

Constructs a new ThreeWayMerge instance.

Method Details

setThreeWayResultType

public void setThreeWayResultType(ThreeWayMergeResultType type)

Sets the type of result which this Merger will produce.

Parameters:

type - the desired result type

getThreeWayResultType

public ThreeWayMergeResultType getThreeWayResultType()

Reports the result type setting for the Merger.

Returns:

the current result type setting

setDebugFiles

public void setDebugFiles(boolean debug)

Enables the generation of intermediate pipeline debug files.

Specified by:

setDebugFiles in interface MergeBase

Parameters:

debug - when true debug files are generated

getDebugFiles

public boolean getDebugFiles()

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

Specified by:

getDebugFiles in interface MergeBase

Returns:

whether the production of debug files is on or not.

See Also:

• MergeBase.setDebugFilesPrefix(String)

setDebugFilesPrefix

public void setDebugFilesPrefix(String prefix)

Provides a prefix for debug result files.

Specified by:

setDebugFilesPrefix in interface MergeBase

Parameters:

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

See Also:

• MergeBase.setDebugFiles(boolean)

getDebugFilesPrefix

public String getDebugFilesPrefix()

Get the current prefix used for debug result files.

Specified by:

getDebugFilesPrefix in interface MergeBase

Returns:

the current prefix used for debug result files.

See Also:

• MergeBase.setDebugFiles(boolean)

setIndent

public void setIndent(boolean indent)

Enables indentation of output using the serializer output indent property.

Specified by:

setIndent in interface MergeBase

Parameters:

indent - when true the output is indented

getEntityResolver

public EntityResolver getEntityResolver()

Gets the explicitly set EntityResolver in use by the merger.

Specified by:

getEntityResolver in interface MergeBase

Returns:

the explicitly set EntityResolver in use by the merger.

getEntityResolver

public EntityResolver getEntityResolver(boolean builtInResolver)

Gets the EntityResolver in use by the merger.

Specified by:

getEntityResolver in interface MergeBase

Parameters:

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

Returns:

the EntityResolver in use by the merger.

setEntityResolver

public void setEntityResolver(EntityResolver resolver,
 boolean fallbackToDefaultCatalogResolver)
                       throws IllegalStateException

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.

Specified by:

setEntityResolver in interface MergeBase

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.

Throws:

IllegalStateException - Thrown if the merger object's state is not INITIAL or RESET.

reset

public void reset()

Reverts the state of the merger to the point where MergeCommon.setAncestor(java.io.File, String) can be used. This is useful if you want to perform a new merge with the same configuration settings.

The merger has a state machine to control the proper ordering of setAncestor and addVersion methods. reset() is used to clear the ancestor and version state. After calling reset() a new ancestor should be provided.

It does not completely re-initialize a merger to the state it would have after calling the constructor, in particular settings for catalogs, entity resolvers and word by word are preserved through a reset method (methods are provided to change these settings, alternatively you can create a new merger object via the constructor).

Specified by:

reset in interface MergeBase

getCurrentState

public ConcurrentMergeState getCurrentState()

Returns the current state of the ThreeWayMerge object. The state affects which methods can be validly be called, this is documented in the ConcurrentMergeState enumeration.

Returns:

The current state of the ThreeWayMerge object.

setAncestor

public void setAncestor(File file,
 String version)
                 throws IllegalStateException,
IllegalArgumentException,
FileNotFoundException,
InvalidInputException,
UnorderedElementContainingPCDATAException,
UnorderedDuplicateKeysException,
com.deltaxml.licensing.LicenseException

Sets the ancestor document with a File input.

The version parameter appears in the result file and must correspond to the NMTOKEN production rule in the XML Specification (the same production rule is used in both XML 1.0 and XML 1.1). This precludes the use of the '!' (0x21) and '=' (0x3d) characters used for version delimiting and other characters which could cause confusion such as the space character.

Specified by:

setAncestor in interface MergeCommon

Parameters:

file - The input file which is the ancestor version.

version - The string to use as the name of the version. This appears in the deltaxml:deltaV2 attributes in the result. This must be an XML NMTOKEN

Throws:

IllegalStateException - Thrown if the merge object's state is not INITIAL or RESET.

IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN.

FileNotFoundException - Thrown if the provided file object does not exist.

InvalidInputException - Thrown if the input is invalid in some way.

UnorderedElementContainingPCDATAException - Thrown if input contains mixed content in orderless merge.

UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.

com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.

See Also:

• XML 1.0 Specification, Section 2.3: Common Syntactic Constructs

setAncestor

public void setAncestor(InputStream is,
 String systemId,
 String version)
                 throws IllegalStateException,
IllegalArgumentException,
InvalidInputException,
com.deltaxml.licensing.LicenseException,
UnorderedDuplicateKeysException,
UnorderedElementContainingPCDATAException

Sets the ancestor document with a InputStream.

The version parameter appears in the result file and must correspond to the NMTOKEN production rule in the XML Specification (the same production rule is used in both XML 1.0 and XML 1.1). This precludes the use of the '!' (0x21) and '=' (0x3d) characters used for version delimiting and other characters which could cause confusion such as the space character.

Specified by:

setAncestor in interface MergeCommon

Parameters:

is - The input steam which is the ancestor version.

systemId - The location of the ancestor input stream (for relative lookup).

version - The string to use as the name of the version. This appears in the deltaxml:deltaV2 attributes in the result. This cannot contain '=' or '!' characters.

Throws:

IllegalStateException - Thrown if the merge object's state is not INITIAL or RESET.

IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN.

InvalidInputException - Thrown if the input is invalid in some way.

com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.

UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.

UnorderedElementContainingPCDATAException - Thrown if input contains mixed content in orderless merge.

See Also:

• XML 1.0 Specification, Section 2.3: Common Syntactic Constructs

setAncestor

public void setAncestor(Reader r,
 String systemId,
 String version)
                 throws IllegalStateException,
IllegalArgumentException,
InvalidInputException,
com.deltaxml.licensing.LicenseException,
UnorderedDuplicateKeysException,
UnorderedElementContainingPCDATAException

Sets the ancestor document with a Reader.

The version parameter appears in the result file and must correspond to the NMTOKEN production rule in the XML Specification (the same production rule is used in both XML 1.0 and XML 1.1). This precludes the use of the '!' (0x21) and '=' (0x3d) characters used for version delimiting and other characters which could cause confusion such as the space character.

Specified by:

setAncestor in interface MergeCommon

Parameters:

r - The reader which is the ancestor version.

systemId - The location of the ancestor reader (for relative lookup).

version - The string to use as the name of the version. This appears in the deltaxml:deltaV2 attributes in the result. This cannot contain '=' or '!' characters.

Throws:

IllegalStateException - Thrown if the merge object's state is not INITIAL or RESET.

IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN.

InvalidInputException - Thrown if the input is invalid in some way.

com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.

UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.

UnorderedElementContainingPCDATAException - Thrown if input contains mixed content in orderless merge.

See Also:

• XML 1.0 Specification, Section 2.3: Common Syntactic Constructs

setAncestor

public void setAncestor(URL url,
 String version)
                 throws IllegalStateException,
IllegalArgumentException,
IOException,
InvalidInputException,
com.deltaxml.licensing.LicenseException,
UnorderedDuplicateKeysException,
UnorderedElementContainingPCDATAException

Sets the ancestor document with a URL.

The version parameter appears in the result file and must correspond to the NMTOKEN production rule in the XML Specification (the same production rule is used in both XML 1.0 and XML 1.1). This precludes the use of the '!' (0x21) and '=' (0x3d) characters used for version delimiting and other characters which could cause confusion such as the space character.

Specified by:

setAncestor in interface MergeCommon

Parameters:

url - The URL to load as the ancestor version.

version - The string to use as the name of the version. This appears in the deltaxml:deltaV2 attributes in the result. This cannot contain '=' or '!' characters.

Throws:

IllegalStateException - Thrown if the merge object's state is not INITIAL or RESET.

IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN.

IOException - Thrown if a stream for the supplied URL cannot be opened.

InvalidInputException - Thrown if the input is invalid in some way.

com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.

UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.

UnorderedElementContainingPCDATAException - Thrown if input contains mixed content in orderless merge.

See Also:

• XML 1.0 Specification, Section 2.3: Common Syntactic Constructs

addVersion

public void addVersion(File file,
 String version)
                throws IllegalStateException,
IllegalArgumentException,
FileNotFoundException,
DifferentRootElementException,
InvalidInputException,
com.deltaxml.licensing.LicenseException,
UnorderedDuplicateKeysException,
DifferingOrderedAttributesException,
UnorderedElementContainingPCDATAException,
ComparisonCancelledException

Adds a version with a File input.

The version parameter appears in the result file and must correspond to the NMTOKEN production rule in the XML Specification (the same production rule is used in both XML 1.0 and XML 1.1). This precludes the use of the '!' (0x21) and '=' (0x3d) characters used for version delimiting and other characters which could cause confusion such as the space character.

Specified by:

addVersion in interface MergeBase

Parameters:

file - The input file which is the version to be added.

version - The string to use as the name of the version. This appears in the deltaxml:deltaV2 attributes in the result. This cannot contain '=' or '!' characters.

Throws:

IllegalStateException - Thrown if the merge object's state is not STARTED or EXTRACTABLE.

IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN, if a version has already been added with this name, or if the supplied name is the same as the ancestor version.

FileNotFoundException - Thrown if the provided file object does not exist.

DifferentRootElementException - Thrown if the version added has a different root XML element as the ancestor.

InvalidInputException - Thrown if the input is invalid.

com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.

UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.

DifferingOrderedAttributesException - Thrown if inputs have different deltaxml:ordered attribute values.

UnorderedElementContainingPCDATAException - Thrown if input contains mixed content in orderless merge.

ComparisonCancelledException

See Also:

• XML 1.0 Specification, Section 2.3: Common Syntactic Constructs

addVersion

public void addVersion(InputStream is,
 String systemId,
 String version)
                throws IllegalStateException,
IllegalArgumentException,
DifferentRootElementException,
InvalidInputException,
com.deltaxml.licensing.LicenseException,
UnorderedDuplicateKeysException,
DifferingOrderedAttributesException,
UnorderedElementContainingPCDATAException,
ComparisonCancelledException

Adds a version with an input stream input.

The version parameter appears in the result file and must correspond to the NMTOKEN production rule in the XML Specification (the same production rule is used in both XML 1.0 and XML 1.1). This precludes the use of the '!' (0x21) and '=' (0x3d) characters used for version delimiting and other characters which could cause confusion such as the space character.

Specified by:

addVersion in interface MergeBase

Parameters:

is - The input stream which is the version to be added.

systemId - The location of the version input stream (for relative lookup).

version - The string to use as the name of the version. This appears in the deltaxml:deltaV2 attributes in the result. This cannot contain '=' or '!' characters.

Throws:

IllegalStateException - Thrown if the merge object's state is not STARTED or EXTRACTABLE.

IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN, if a version has already been added with this name, or if the supplied name is the same as the ancestor version.

DifferentRootElementException - Thrown if the version added has a different root XML element as the ancestor.

InvalidInputException - Thrown if the input is invalid.

com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.

UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.

DifferingOrderedAttributesException - Thrown if inputs have different deltaxml:ordered attribute values.

UnorderedElementContainingPCDATAException - Thrown if input contains mixed content in orderless merge.

ComparisonCancelledException

See Also:

• XML 1.0 Specification, Section 2.3: Common Syntactic Constructs

addVersion

public void addVersion(Reader r,
 String systemId,
 String version)
                throws IllegalStateException,
IllegalArgumentException,
DifferentRootElementException,
InvalidInputException,
DifferingOrderedAttributesException,
com.deltaxml.licensing.LicenseException,
UnorderedDuplicateKeysException,
UnorderedElementContainingPCDATAException,
ComparisonCancelledException

Adds a version with a File input.

The version parameter appears in the result file and must correspond to the NMTOKEN production rule in the XML Specification (the same production rule is used in both XML 1.0 and XML 1.1). This precludes the use of the '!' (0x21) and '=' (0x3d) characters used for version delimiting and other characters which could cause confusion such as the space character.

Specified by:

addVersion in interface MergeBase

Parameters:

r - The input reader which is the version to be added.

systemId - The location of the ancestor reader (for relative lookup).

version - The string to use as the name of the version. This appears in the deltaxml:deltaV2 attributes in the result. This cannot contain '=' or '!' characters.

Throws:

IllegalStateException - Thrown if the merge object's state is not STARTED or EXTRACTABLE.

IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN, if a version has already been added with this name, or if the supplied name is the same as the ancestor version.

DifferentRootElementException - Thrown if the version added has a different root XML element as the ancestor.

InvalidInputException - Thrown if the input is invalid.

DifferingOrderedAttributesException - Thrown if inputs have different deltaxml:ordered attribute values.

com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.

UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.

UnorderedElementContainingPCDATAException - Thrown if input contains mixed content in orderless merge.

ComparisonCancelledException

See Also:

• XML 1.0 Specification, Section 2.3: Common Syntactic Constructs

addVersion

public void addVersion(URL url,
 String version)
                throws IllegalStateException,
IllegalArgumentException,
IOException,
DifferentRootElementException,
InvalidInputException,
com.deltaxml.licensing.LicenseException,
UnorderedDuplicateKeysException,
DifferingOrderedAttributesException,
UnorderedElementContainingPCDATAException,
ComparisonCancelledException

Adds a version with a URL input.

The version parameter appears in the result file and must correspond to the NMTOKEN production rule in the XML Specification (the same production rule is used in both XML 1.0 and XML 1.1). This precludes the use of the '!' (0x21) and '=' (0x3d) characters used for version delimiting and other characters which could cause confusion such as the space character.

Specified by:

addVersion in interface MergeBase

Parameters:

url - The URL which is the version to be added.

version - The string to use as the name of the version. This appears in the deltaxml:deltaV2 attributes in the result. This cannot contain '=' or '!' characters.

Throws:

IllegalStateException - Thrown if the merger object's state is not STARTED or EXTRACTABLE.

IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN, if a version has already been added with this name, or if the supplied name is the same as the ancestor version.

IOException - Thrown if a stream for the supplied URL cannot be opened.

DifferentRootElementException - Thrown if the version added has a different root XML element as the ancestor.

InvalidInputException - Thrown if the input is invalid.

com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.

UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.

DifferingOrderedAttributesException - Thrown if inputs have different deltaxml:ordered attribute values.

UnorderedElementContainingPCDATAException - Thrown if input contains mixed content in orderless merge.

ComparisonCancelledException

See Also:

• XML 1.0 Specification, Section 2.3: Common Syntactic Constructs

setWordByWord

public void setWordByWord(boolean wbwValue)
                   throws IllegalStateException

Determines whether WordByWord filter is used.

Specified by:

setWordByWord in interface MergeBase

Parameters:

wbwValue - The new WordByWord setting to use.

Throws:

IllegalStateException - when this operation is not allowed according to the MergeState

getWordByWord

public boolean getWordByWord()

Reports the state of the WordByWord setting.

Specified by:

getWordByWord in interface MergeBase

Returns:

the current value

setElementSplitting

public void setElementSplitting(boolean enabled)
                         throws IllegalStateException

Sets whether modified elements containing text should be split when the amount of unchanged text falls below 10%.

Note that element splitting does not happen when the WordByWord setting is 'false'.

Default: true

Certain DITA elements such as a section, title are only permitted once in the DITA DTD. Therefore, the element splitting feature is not applied to such elements.

Element splitting is currently applied to following DITA elements.

DITA elements : apiname, b, cite, cmdname, codeph, filepath, i, li, lines, msgnum, msgph, note, p, parmname, pre, q, sli, sub, sup, systemoutput, term, text, tm, tt, u, uicontrol, userinput, var, varname, wintitle

Specified by:

setElementSplitting in interface MergeBase

Parameters:

enabled - whether or not to enable element splitting

Throws:

IllegalStateException - when this operation is not allowed according to the MergeState

getElementSplitting

public boolean getElementSplitting()

States whether modified elements containing text are split when the amount of unchanged text falls below 10%.

Specified by:

getElementSplitting in interface MergeBase

Returns:

a boolean stating whether the splitting behaviour is enabled or not

setDoctypePreservationMode

public void setDoctypePreservationMode(DoctypePreservationMode mode)

Sets how Doctype declarations should be preserved in the result.

Default Setting

The DoctypePreservationMode.PRESERVE_WHEN_UNCHANGED setting is used by default.

Parameters:

mode - the new preservation mode

getDoctypePreservationMode

public DoctypePreservationMode getDoctypePreservationMode()

Reports the current mode.

Returns:

the current mode

setEntityReferencePreservationMode

public void setEntityReferencePreservationMode(EntityReferencePreservationMode mode)

Sets how Entity references should be preserved.

Default Setting

The EntityReferencePreservationMode.PRESERVE_REFERENCES setting is used by default.

Parameters:

mode - the new preservation mode

getEntityReferencePreservationMode

public EntityReferencePreservationMode getEntityReferencePreservationMode()

Reports the current mode.

Returns:

the current mode

setRuleConfiguration

public void setRuleConfiguration(RuleConfiguration rc)

Allows the rules for ditamerge processing (during extract operations) to be specified.

Parameters:

rc - A new set of rules

getRuleConfiguration

public RuleConfiguration getRuleConfiguration()

Returns the currently used (for extract operations) rule configuration object.

Returns:

the current rule configuration

extractAll

public void extractAll(File file)
                throws IllegalStateException,
DoctypeChangeException,
DoctypeMissingException,
InvalidInputException,
com.deltaxml.licensing.LicenseException

Extracts the entire content of all added versions of the Merger to a File using the deltaV2 merge format.

Specified by:

extractAll in interface MergeBase

Parameters:

file - The file into which the deltaV2 content is extracted

Throws:

IllegalStateException - the Merger is not in a state ready for extraction

DoctypeChangeException - when there are doctype changes and DoctypePreservationMode specifies that they are reported

DoctypeMissingException - when there are doctype is missing and DoctypePreservationMode specifies that they are reported

InvalidInputException - Thrown if the input is invalid in some way.

com.deltaxml.licensing.LicenseException - if there are any problems with the supplied license or its use

extractAll

public void extractAll(Writer w)
                throws IllegalStateException,
DoctypeChangeException,
DoctypeMissingException,
InvalidInputException,
com.deltaxml.licensing.LicenseException

Extracts the entire content of all added versions of the Merger to a Writer using the deltaV2 merge format.

Specified by:

extractAll in interface MergeBase

Parameters:

w - The writer into which the deltaV2 content is extracted

Throws:

IllegalStateException - the Merger is not in a state ready for extraction

DoctypeChangeException - when there are doctype changes and DoctypePreservationMode specifies that they are reported

DoctypeMissingException - when there are doctype is missing and DoctypePreservationMode specifies that they are reported

InvalidInputException - Thrown if the input is invalid in some way.

com.deltaxml.licensing.LicenseException - if there are any problems with the supplied license or its use

extractAll

public void extractAll(OutputStream os)
                throws IllegalStateException,
DoctypeChangeException,
DoctypeMissingException,
InvalidInputException,
com.deltaxml.licensing.LicenseException

Extracts the entire content of all added versions of the Merger to a OutputStream using the deltaV2 merge format.

Specified by:

extractAll in interface MergeBase

Parameters:

os - The OutputStream into which the deltaV2 content is extracted

Throws:

IllegalStateException - the Merger is not in a state ready for extraction

DoctypeChangeException - when there are doctype changes and DoctypePreservationMode specifies that they are reported

DoctypeMissingException - when there are doctype is missing and DoctypePreservationMode specifies that they are reported

InvalidInputException - Thrown if the input is invalid in some way.

com.deltaxml.licensing.LicenseException - if there are any problems with the supplied license or its use

getAncestorVersion

public String getAncestorVersion()

Returns the version name of the ancestor.

Specified by:

getAncestorVersion in interface MergeCommon

Returns:

the version name of the ancestor

getVersions

public List<String> getVersions()

Returns an immutable list of versions which have been added.

Specified by:

getVersions in interface MergeBase

Returns:

an immutable list of versions which have been added

merge

public void merge(File ancestor,
 File edit1,
 File edit2,
 File result)
           throws IllegalStateException,
IllegalArgumentException,
FileNotFoundException,
InvalidInputException,
UnorderedElementContainingPCDATAException,
UnorderedDuplicateKeysException,
com.deltaxml.licensing.LicenseException,
DifferentRootElementException,
DifferingOrderedAttributesException,
DoctypeChangeException,
DoctypeMissingException,
ComparisonCancelledException

This method is used to perform three way merge of DITA inputs.

Parameters:

ancestor - The common ancestor.

edit1 - First version

edit2 - second version

result - Result of a three way dita merge.

Throws:

DifferentRootElementException - Thrown if any version has a different root XML element as the ancestor.

com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.

UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.

UnorderedElementContainingPCDATAException - if an orderless element contains PCDATA or text nodes.

InvalidInputException - Thrown if the input is invalid.

FileNotFoundException - Thrown if an attempt to open the file denoted by a specified pathname fails

IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN, if a version has already been added with this name, or if the supplied name is the same as the ancestor version.

IllegalStateException - Thrown if the merge object's state is not STARTED or EXTRACTABLE.

DifferingOrderedAttributesException - Thrown if inputs have different deltaxml:ordered attribute values.

DoctypeChangeException - when there are doctype changes and DoctypePreservationMode specifies that they are reported

DoctypeMissingException - when there are doctype missing and DoctypePreservationMode specifies that they are reported

ComparisonCancelledException

merge

public void merge(InputStream ancestor,
 String systemIdAncestor,
 InputStream edit1,
 String systemIdEdit1,
 InputStream edit2,
 String systemIdEdit2,
 OutputStream result)
           throws IllegalStateException,
IllegalArgumentException,
FileNotFoundException,
InvalidInputException,
UnorderedElementContainingPCDATAException,
UnorderedDuplicateKeysException,
com.deltaxml.licensing.LicenseException,
DifferentRootElementException,
DifferingOrderedAttributesException,
DoctypeChangeException,
DoctypeMissingException,
ComparisonCancelledException

This method is used to perform three way merge of InputStreams.

Parameters:

ancestor - The common ancestor.

systemIdAncestor - The location of the ancestor input stream (for relative lookup).

edit1 - First version

systemIdEdit1 - The location of the version 1 input stream (for relative lookup).

edit2 - second version

systemIdEdit2 - The location of the version 2 input stream (for relative lookup).

result - Result of a three way dita merge.

Throws:

DifferentRootElementException - Thrown if any version has a different root XML element to the ancestor.

com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.

UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.

UnorderedElementContainingPCDATAException - if an orderless element contains PCDATA or text nodes.

InvalidInputException - Thrown if the input is invalid.

FileNotFoundException - Thrown if an attempt to open the file denoted by a specified pathname has failed

IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN, if a version has already been added with this name, or if the supplied name is the same as the ancestor version.

IllegalStateException - Thrown if the merge object's state is not STARTED or EXTRACTABLE.

DifferingOrderedAttributesException - Thrown if inputs have different deltaxml:ordered attribute values.

DoctypeChangeException - when there are doctype changes and DoctypePreservationMode specifies that they are reported

DoctypeMissingException - when there are doctype changes and DoctypePreservationMode specifies that they are reported

ComparisonCancelledException

Since:

1.2.1

merge

public void merge(Reader ancestor,
 String systemIdAncestor,
 Reader edit1,
 String systemIdEdit1,
 Reader edit2,
 String systemIdEdit2,
 Writer result)
           throws IllegalStateException,
IllegalArgumentException,
FileNotFoundException,
InvalidInputException,
UnorderedElementContainingPCDATAException,
UnorderedDuplicateKeysException,
com.deltaxml.licensing.LicenseException,
DifferentRootElementException,
DifferingOrderedAttributesException,
DoctypeChangeException,
DoctypeMissingException,
ComparisonCancelledException

This method is used to perform three way merge with Readers.

Parameters:

ancestor - The common ancestor.

systemIdAncestor - The location of the ancestor reader (for relative lookup).

edit1 - First version

systemIdEdit1 - The location of the version 1 reader (for relative lookup).

edit2 - second version

systemIdEdit2 - The location of the version 2 reader (for relative lookup).

result - Result of a three way dita merge.

Throws:

DifferentRootElementException - Thrown if any version has a different root XML element to the ancestor.

com.deltaxml.licensing.LicenseException - Thrown if there is no license installed, or if the installed license is invalid.

UnorderedDuplicateKeysException - Thrown if there are duplicate keys in orderless merge.

UnorderedElementContainingPCDATAException - if an orderless element contains PCDATA or text nodes.

InvalidInputException - Thrown if the input is invalid.

FileNotFoundException - Thrown if an attempt to open the file denoted by a specified pathname has failed

IllegalArgumentException - Thrown if the version parameter is not an NMTOKEN, if a version has already been added with this name, or if the supplied name is the same as the ancestor version.

IllegalStateException - Thrown if the merge object's state is not STARTED or EXTRACTABLE.

DifferingOrderedAttributesException - Thrown if inputs have different deltaxml:ordered attribute values.

DoctypeChangeException - when there are doctype changes and DoctypePreservationMode specifies that they are reported

DoctypeMissingException - when there are doctype changes and DoctypePreservationMode specifies that they are reported

ComparisonCancelledException

Since:

1.2.1

setTwoWayResultFormat

public void setTwoWayResultFormat(ThreeWayMerge.TwoWayResultFormat rf)

Sets the result format which this Merger will produce.

Parameters:

rf - the desired result format

getTwoWayResultFormat

public ThreeWayMerge.TwoWayResultFormat getTwoWayResultFormat()

Reports the result format setting for the Merger.

Returns:

the current result format setting

setThreeWayTrackChangeAttributeMode

public void setThreeWayTrackChangeAttributeMode(TrackChangesAttributeMode mode)

Sets the attribute mode for three way track change output. Note: This setting has an effect with the result type ThreeWayMergeResultType.THREE_WAY_OXYGEN_TRACK_CHANGES

Default Setting

The TrackChangesAttributeMode.TC_EDIT1 setting is used by default.

Parameters:

mode - the desired attribute mode

getThreeWayTrackChangeAttributeMode

public TrackChangesAttributeMode getThreeWayTrackChangeAttributeMode()

Reports the attribute mode used with three way track change output.

Returns:

the current attribute mode

setExistingOxygenTCsProcessingMode

public void setExistingOxygenTCsProcessingMode(ExistingOxygenTCsProcessingMode mode)

Sets the existing oxygen TCs processing mode for three way track change output. Note: This setting has an effect with the result type ThreeWayMergeResultType.THREE_WAY_OXYGEN_TRACK_CHANGES

Default Setting

The ExistingOxygenTCsProcessingMode.ACCEPT setting is used by default.

Parameters:

mode - the desired existing oxygen TCs processing mode

getExistingOxygenTCsProcessingMode

public ExistingOxygenTCsProcessingMode getExistingOxygenTCsProcessingMode()

Reports the existing oxygen TCs processing mode used with three way track change output.

Returns:

the current existing oxygen TCs processing mode

setResultPreset

public void setResultPreset(ThreeToTwoResultPreset p)

Used to preset three to two way merge use cases.

The merge extraction process applies default rule configuration settings which executes before this method. Applying this configuration overrides the different RuleConfiguration and ThreeWayMergeResultType settings applied prior to this.

Parameters:

p - the desired ThreeToTwoResultPreset

getResultPreset

public ThreeToTwoResultPreset getResultPreset()

Reports preset of three to two way merge use cases.

Returns:

the current preset

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 fixed host/user licensing, or a concurrent licensing containing the USE_SERVER directive

Specified by:

addLicenseFile in interface MergeBase

Parameters:

licenseFile - the FlexLM format license file

Throws:

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

addLicenseServer

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

Adds a license server for use with concurrent licensing.

Specified by:

addLicenseServer in interface MergeBase

Parameters:

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

Specified by:

addLicenseServer in interface MergeBase

Parameters:

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

setCalsTableConfiguration

public void setCalsTableConfiguration(CalsTableConfiguration config)

Sets the configuration options for CALS table comparison.

Specified by:

setCalsTableConfiguration in interface MergeBase

Parameters:

config - a CalsTableConfiguration object that contains the settings to use for CALS table comparison

getCalsTableConfiguration

public CalsTableConfiguration getCalsTableConfiguration()

Returns the current configuration options for CALS table comparison.

Specified by:

getCalsTableConfiguration in interface MergeBase

Returns:

a CalsTableConfiguration object that contains the settings to use for CALS table comparison

setHtmlTableConfiguration

public void setHtmlTableConfiguration(HtmlTableConfiguration config)

Sets the configuration options for HTML table comparison.

Specified by:

setHtmlTableConfiguration in interface MergeBase

Parameters:

config - a HtmlTableConfiguration object that contains the settings to use for HTML table comparison

getHtmlTableConfiguration

public HtmlTableConfiguration getHtmlTableConfiguration()

Returns the current configuration options for HTML table comparison.

Specified by:

getHtmlTableConfiguration in interface MergeBase

Returns:

a HtmlTableConfiguration object that contains the settings to use for HTML table comparison

addProgressListener

public void addProgressListener(MergeProgressListener listener)

Add a progress listener to the list of registered progress listeners. It is possible to add the same listener multiple times.

Specified by:

addProgressListener in interface MergeBase

Parameters:

listener - the progress listener to register.

removeProgressListener

public void removeProgressListener(MergeProgressListener listener)

Remove a progress listener from the list of registered progress listeners. This will remove the first occurrence of a progress listener.

Specified by:

removeProgressListener in interface MergeBase

Parameters:

listener - the progress listener to remove.

clearProgressListeners

public void clearProgressListeners()

Remove all currently registered progress listeners.

Specified by:

clearProgressListeners in interface MergeBase

setFormattingElementsConfiguration

public void setFormattingElementsConfiguration(FormattingElementsConfiguration formattingElementsConfiguration)
                                        throws IllegalStateException,
IllegalArgumentException

Provides various settings for specifying formatting elements.

Parameters:

formattingElementsConfiguration - a FormattingElementsConfiguration object

Throws:

IllegalStateException - when this operation is not allowed according to the merge state

IllegalArgumentException - when FormattingElementsConfiguration is null

getFormattingElementsConfiguration

public FormattingElementsConfiguration getFormattingElementsConfiguration()

Returns the currently used FormattingElementConfiguration object.

Returns:

the FormattingElementConfiguration object

setFormattingOutputType

public void setFormattingOutputType(FormattingOutputType formattingOutputType)

Set the output type used for representing formatting elements in the output. The default is FormattingOutputType.DELTA_V_2_1 which represents Formatting Elements using our Delta v2.1 format.

Specified by:

setFormattingOutputType in interface MergeBase

Parameters:

formattingOutputType - the type of representation to use.

See Also:

• FormattingOutputType

getFormattingOutputType

public FormattingOutputType getFormattingOutputType()

Get the output type used for representing formatting elements in the output.

Specified by:

getFormattingOutputType in interface MergeBase

Returns:

the output type

See Also:

• FormattingOutputType

setFormatExtractionPriorityList

public void setFormatExtractionPriorityList(List<String> priorityList)

Merge operations represent overlapping hierarchies from the input documents by flattening and subsequently fragmenting formatting elements where necessary.

To produce a result without overlapping or nesting of formatting elements, it may be necessary to remove formatting information in a controlled way.

The format extraction priority list specifies the list of versions by priority. This priority list will be used to extract formatting to resolve overlaps and nesting to produce a deltaV2 result.

Please note that if only some, not all, of the versions are specified in the priority list there is a possibility of format loss due to additions/deletions of formatting by the missing version(s).

Specified by:

setFormatExtractionPriorityList in interface MergeBase

Parameters:

priorityList - a list of priority versions specified using Strings

getFormatExtractionPriorityList

public List<String> getFormatExtractionPriorityList()

Reports the current setting of the format extraction priority list.

Specified by:

getFormatExtractionPriorityList in interface MergeBase

Returns:

the current list of priority versions

isNewTableProcessingEnabled

public boolean isNewTableProcessingEnabled()

Returns the current setting for new table processing.

Specified by:

isNewTableProcessingEnabled in interface MergeCommon

Returns:

the current value

setTableProcessingAlgorithmVersion2

public void setTableProcessingAlgorithmVersion2(boolean value)

Enables new table processing algorithm for CALS and HTML table.

Specified by:

setTableProcessingAlgorithmVersion2 in interface MergeCommon

Parameters:

value - The new newTableProcessing setting to use.