ResultReadabilityOptions

java.lang.Object
- com.deltaxml.cores9api.config.ResultReadabilityOptions

```
public class ResultReadabilityOptions
extends java.lang.Object
```
Sets options to change the granularity and ordering of changes in the result in order to improve readability.

The underlying comparison engine attempts to produce a result based on the Levenshtein distance between the inputs. While this will produce a mathematically optimal result, when looking at individual word changes in a block of text, the results produced are not always very readable as they can appear to be a mix of added, deleted and unchanged items. This configuration object can be used to make the result more readable using a variety of techniques, including:
- Element splitting This involves splitting a modified element that contains text when the amount of text that is actually common/unchanged fall below a given percentage of the total content
- Orphaned word detection This involves detecting cases where unchanged words lie within a larger block of modified text. This often occurs when common words such as 'the', 'and', 'a' etc are matched together in otherwise unrelated sentences. When these unchanged words are detected, they are treated as if they have been deleted and added again in order to make the larger change much more readable.
- Change gathering This can have an effect at all levels of the XML tree. When sibling element/text is a mix of added and deleted content, it can be reordered to show, for example, all deleted content followed by all added content.
Changes to whitespace within a document can be insignificant, such as when editors automatically add line wrapping and indentation within a DITA, DocBook, or HTML paragraph. In these cases, it would be useful if changes in whitespace are not reported. This can be achieved in a number of ways, including: normalizing the whitespace in the inputs; and identifying and then ignoring modified whitespace in the raw comparison output. Here whitespace, at a given point in the document, is considered to be modified if, and only if, both documents have some whitespace at this point which differs.

Note: if there are subtrees in a document where whitespace change is important this can be identified by adding the standard XML xml:space="preserve" attribute to the top-element of the subtree, in the input filtering. Conversely, it is possible to specify that the whitespace within a subtree does not need to be preserved by adding the xml:space="default" attribute to the top-element of that subtree, which is the implicit setting.
Since:

7.0

See Also:

Document Comparator Guide, Word by Word Text Comparison

Constructor Summary

Constructors
Constructor and Description

ResultReadabilityOptions()
Constructs a new ResultReadabilityOptions instance.

Constructors
Constructor and Description
`ResultReadabilityOptions()` Constructs a new `ResultReadabilityOptions` instance.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`int`	`getElementSplittingDebugTextReportSize()` Returns the current limit on the length of each debug report output by the element splitting filter.
`int`	`getElementSplittingThreshold()` Returns the percentage of unchanged text present in a modified element below which the element will be split.
`MixedContentDetectionScope`	`getMixedContentDetectionScope()` Return the current scope `MixedContentDetectionScope` for determining whether elements are of a mixed-content type.
`ModifiedWhitespaceBehaviour`	`getModifiedWhitespaceBehaviour()` Return the current `ModifiedWhitespaceBehaviour` for handling changes in whitespace.
`java.lang.String`	`getMoveAttributeXpath()` Deprecated. Please use `MoveDetectionConfig` instead.
`int`	`getOrphanedWordLengthLimit()` Returns the current maximum number of words that could be considered orphaned.
`int`	`getOrphanedWordMaxPercentage()` Returns the maximum proportion of the total change size that orphaned words can take while still being considered orphans.
`boolean`	`isChangeGatheringEnabled()` States whether or not the change reordering functionality is currently enabled.
`boolean`	`isCharacterByCharacterEnabled()` Sets whether to use Character by Character in comparison.
`boolean`	`isDetectMoves()` Deprecated. Please use `MoveDetectionConfig` instead.
`boolean`	`isElementSplittingDebug()` States whether the element splitting filter is set to output internal debug information.
`boolean`	`isElementSplittingEnabled()` States whether modified elements containing text are split when the amount of unchanged text falls below a given percentage.
`boolean`	`isOrphanedWordDetectionEnabled()` States whether or not orphaned word detection is enabled.
`boolean`	`isRemoveMoveSource()` Deprecated. Please use `MoveDetectionConfig` instead.
`void`	`setChangeGatheringEnabled(boolean enabled)` Sets whether to change the order of consecutive changed items to improve readability.
`void`	`setCharacterByCharacterEnabled(boolean characterByCharacter)` Returns the setting which enables the character by character comparison.
`void`	`setDetectMoves(boolean value)` Deprecated. Please use `MoveDetectionConfig` instead.
`void`	`setElementSplittingDebug(boolean debug)` Sets whether the element splitting filter should output internal debug information.
`void`	`setElementSplittingDebugTextReportSize(int size)` Sets a limit on the length of each debug report output by the element splitting filter.
`void`	`setElementSplittingEnabled(boolean enabled)` Sets whether modified elements containing text should be split when the amount of unchanged text falls below a given percentage.
`void`	`setElementSplittingThreshold(int percentage)` Sets the percentage of unchanged text present in a modified element below which the element will be split.
`void`	`setMixedContentDetectionScope(MixedContentDetectionScope scope)` Set the scope `MixedContentDetectionScope` to use for determining whether elements are of a mixed-content type.
`void`	`setModifiedWhitespaceBehaviour(ModifiedWhitespaceBehaviour mode)` Set the `ModifiedWhitespaceBehaviour` to use for changes to whitespace.
`void`	`setMoveAttributeXpath(java.lang.String value)` Deprecated. Please use `MoveDetectionConfig` instead.
`void`	`setOrphanedWordDetectionEnabled(boolean enabled)` Sets whether or not to enable orphaned word detection and fix-up.
`void`	`setOrphanedWordLengthLimit(int length)` Sets the maximum number of words to consider for orphaned word detection.
`void`	`setOrphanedWordMaxPercentage(int percentage)` Sets the maximum proportion of the total change size that orphaned words can take while still being considered orphans.
`void`	`setRemoveMoveSource(boolean removeMoveSource)` Deprecated. Please use `MoveDetectionConfig` instead.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - ResultReadabilityOptions
```
public ResultReadabilityOptions()
```
    Constructs a new ResultReadabilityOptions instance.
- Method Detail
  - setElementSplittingEnabled
```
public void setElementSplittingEnabled(boolean enabled)
```
    Sets whether modified elements containing text should be split when the amount of unchanged text falls below a given percentage.
    
    The percentage at which this behaviour is triggered can be set using ResultReadabilityOptions.setElementSplittingThreshold(int)
    
    Parameters:
    
    enabled - whether or not to enable element splitting
    
    See Also:
    
    ResultReadabilityOptions.setElementSplittingThreshold(int)
  - isElementSplittingEnabled
```
public boolean isElementSplittingEnabled()
```
    States whether modified elements containing text are split when the amount of unchanged text falls below a given percentage.
    
    Returns:
    
    a boolean stating whether the splitting behaviour is enabled or not
  - setElementSplittingThreshold
```
public void setElementSplittingThreshold(int percentage)
                                  throws java.lang.IllegalArgumentException
```
    Sets the percentage of unchanged text present in a modified element below which the element will be split.
    
    Parameters:
    
    percentage - an integer in the range 0-100 specifying the percentage of unchanged text
    
    Throws:
    
    java.lang.IllegalArgumentException - if the supplied parameter is not in the range 0-100
  - getElementSplittingThreshold
```
public int getElementSplittingThreshold()
```
    Returns the percentage of unchanged text present in a modified element below which the element will be split.
    
    Returns:
    
    an integer in the range 0-100 specifying the percentage of unchanged text
  - setElementSplittingDebug
```
public void setElementSplittingDebug(boolean debug)
```
    Sets whether the element splitting filter should output internal debug information.
    
    The internal debug output is passed using <xsl:message/>. This is typically passed to std.out but this can be changed my configuring the relevant Saxon Configuration object.
    
    Parameters:
    
    debug - whether the element splitting filter should output internal debug information
    
    See Also:
    
    Configuration.setStandardErrorOutput(java.io.PrintStream)
  - isElementSplittingDebug
```
public boolean isElementSplittingDebug()
```
    States whether the element splitting filter is set to output internal debug information.
    
    Returns:
    
    a boolean stating whether debug output is expected
  - setElementSplittingDebugTextReportSize
```
public void setElementSplittingDebugTextReportSize(int size)
                                            throws java.lang.IllegalArgumentException
```
    Sets a limit on the length of each debug report output by the element splitting filter.
    
    Parameters:
    
    size - the size limit for the debug output report
    
    Throws:
    
    java.lang.IllegalArgumentException - if the supplied parameter is not a positive integer
  - getElementSplittingDebugTextReportSize
```
public int getElementSplittingDebugTextReportSize()
```
    Returns the current limit on the length of each debug report output by the element splitting filter.
    
    Returns:
    
    an integer stating the current setting for the length of debug output
  - setOrphanedWordDetectionEnabled
```
public void setOrphanedWordDetectionEnabled(boolean enabled)
```
    Sets whether or not to enable orphaned word detection and fix-up.
    
    Parameters:
    
    enabled - whether or not to enable orphaned word detection
  - isOrphanedWordDetectionEnabled
```
public boolean isOrphanedWordDetectionEnabled()
```
    States whether or not orphaned word detection is enabled.
    
    Returns:
    
    whether or not orphaned word detection is enabled
  - setOrphanedWordLengthLimit
```
public void setOrphanedWordLengthLimit(int length)
                                throws java.lang.IllegalArgumentException
```
    Sets the maximum number of words to consider for orphaned word detection. Sequences of words longer than the specified length will never be detected as orphaned words, regardless of the amount of changed words around them.
    
    Parameters:
    
    length - the maximum number of consecutive words that could be considered to be orphaned
    
    Throws:
    
    java.lang.IllegalArgumentException - if the supplied parameter is not a positive integer
  - getOrphanedWordLengthLimit
```
public int getOrphanedWordLengthLimit()
```
    Returns the current maximum number of words that could be considered orphaned.
    
    Returns:
    
    an int representing the number of words
  - setOrphanedWordMaxPercentage
```
public void setOrphanedWordMaxPercentage(int percentage)
                                  throws java.lang.IllegalArgumentException
```
    Sets the maximum proportion of the total change size that orphaned words can take while still being considered orphans.
    
    If the percentage value for a possibly orphaned section is less than or equal to this value, then it is classified as orphaned (unless there are more words than the length limit allows). The percentage value for a possibly orphaned section is calculated as follows:
```
 (possibly_orphaned_words_count * 100) / (preceding_changed_words_count + possibly_orphaned_words_count + following_changed_words_count)
 
```
    Parameters:
    
    percentage - the maximum proportion of a changed section that orphaned words can take and still be considered orphans
    
    Throws:
    
    java.lang.IllegalArgumentException - if the supplied value is not in the range 0-100
  - getOrphanedWordMaxPercentage
```
public int getOrphanedWordMaxPercentage()
```
    Returns the maximum proportion of the total change size that orphaned words can take while still being considered orphans.
    
    Returns:
    
    an integer in the range 0-100 that represents the percentage
  - setChangeGatheringEnabled
```
public void setChangeGatheringEnabled(boolean enabled)
```
    Sets whether to change the order of consecutive changed items to improve readability.
    
    If the result contains a sequence of elements whose deltaxml:deltaV2 attribute values are mixed up in a sequence of As and Bs, enabling this feature will cause them to be reordered so that they are not mixed.
    
    For example,
```
   <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="B"/>
   <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="B"/>
   <elem deltaxml:deltaV2="B"/>
   <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="A"/>
 
```
    would be reordered to
```
   <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="A"/>
   <elem deltaxml:deltaV2="B"/>
   <elem deltaxml:deltaV2="B"/>
   <elem deltaxml:deltaV2="B"/>
 
```
    Parameters:
    
    enabled - whether the reordering functionality should be enabled
  - isChangeGatheringEnabled
```
public boolean isChangeGatheringEnabled()
```
    States whether or not the change reordering functionality is currently enabled.
    
    Returns:
    
    a boolean stating whether or not the functionality is enabled
  - setModifiedWhitespaceBehaviour
```
public void setModifiedWhitespaceBehaviour(ModifiedWhitespaceBehaviour mode)
```
    Set the ModifiedWhitespaceBehaviour to use for changes to whitespace. Here, both documents must have some whitespace at a given point in order for there to be a change in whitespace. This will then be processed in accordance with the specified behaviour. Whitespace insertions and deletions are not affected by the modified whitespace behaviour.
    
    Parameters:
    
    mode - the ModifiedWhitespaceBehaviour to use for changes in whitespace
  - getModifiedWhitespaceBehaviour
```
public ModifiedWhitespaceBehaviour getModifiedWhitespaceBehaviour()
```
    Return the current ModifiedWhitespaceBehaviour for handling changes in whitespace.
    
    Returns:
    
    a ModifiedWhitespaceBehaviour detailing how changed whitespace will be output
  - setMixedContentDetectionScope
```
public void setMixedContentDetectionScope(MixedContentDetectionScope scope)
```
    Set the scope MixedContentDetectionScope to use for determining whether elements are of a mixed-content type. This property has no effect if DTD or XML Schema validation is enabled. The mixed-content type of an element affects whitespace handling.
    
    Parameters:
    
    scope - the MixedContentDetectionScope to use for determining if elements are mixed-content.
  - getMixedContentDetectionScope
```
public MixedContentDetectionScope getMixedContentDetectionScope()
```
    Return the current scope MixedContentDetectionScope for determining whether elements are of a mixed-content type.
    
    Returns:
    
    the scope MixedContentDetectionScope used for determining if elements are mixed-content.
  - setDetectMoves
```
@Deprecated
public void setDetectMoves(boolean value)
```
    Deprecated. Please use MoveDetectionConfig instead.
    
    Sets the moves detection feature on or off. The move detection feature uses unique ids to identify moves. These unique ids can be set using ResultReadabilityOptions.setMoveAttributeXpath(java.lang.String).
    
    Parameters:
    
    value - A boolean value to set moves detection feature.
  - isDetectMoves
```
@Deprecated
public boolean isDetectMoves()
```
    Deprecated. Please use MoveDetectionConfig instead.
    
    Returns true if moves detection feature is on, otherwise false.
    
    Returns:
    
    the current setting for moves detection.
  - setMoveAttributeXpath
```
@Deprecated
public void setMoveAttributeXpath(java.lang.String value)
```
    Deprecated. Please use MoveDetectionConfig instead.
    
    Sets id attribute XPath to be used during moves detection. This id attribute must be an unique identifier for an element. It is used to identify and detect source and target for an element move. If a bad or invalid XPath expression is provided then an exception will be thrown during the comparison.
    
    Parameters:
    
    value - XPath for id attribute.
  - getMoveAttributeXpath
```
@Deprecated
public java.lang.String getMoveAttributeXpath()
```
    Deprecated. Please use MoveDetectionConfig instead.
    
    Returns id attribute XPath used during moves detection.
    
    Returns:
    
    a XPath for id attribute.
  - isRemoveMoveSource
```
@Deprecated
public boolean isRemoveMoveSource()
```
    Deprecated. Please use MoveDetectionConfig instead.
    
    Sets whether to remove the source of the move.
    
    Returns:
    
    the remove moves source setting
  - setRemoveMoveSource
```
@Deprecated
public void setRemoveMoveSource(boolean removeMoveSource)
```
    Deprecated. Please use MoveDetectionConfig instead.
    
    Returns the setting which removes the source of the move.
    
    Parameters:
    
    removeMoveSource - the setting to set remove moves source
  - isCharacterByCharacterEnabled
```
public boolean isCharacterByCharacterEnabled()
```
    Sets whether to use Character by Character in comparison.
    
    Returns:
    
    the enableCharacterByCharacter setting
  - setCharacterByCharacterEnabled
```
public void setCharacterByCharacterEnabled(boolean characterByCharacter)
```
    Returns the setting which enables the character by character comparison.
    
    Parameters:
    
    characterByCharacter - the setting to set character by character comparison

Class ResultReadabilityOptions

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ResultReadabilityOptions

Method Detail

setElementSplittingEnabled

isElementSplittingEnabled

setElementSplittingThreshold

getElementSplittingThreshold

setElementSplittingDebug

isElementSplittingDebug

setElementSplittingDebugTextReportSize

getElementSplittingDebugTextReportSize

setOrphanedWordDetectionEnabled

isOrphanedWordDetectionEnabled

setOrphanedWordLengthLimit

getOrphanedWordLengthLimit

setOrphanedWordMaxPercentage

getOrphanedWordMaxPercentage

setChangeGatheringEnabled

isChangeGatheringEnabled

setModifiedWhitespaceBehaviour

getModifiedWhitespaceBehaviour

setMixedContentDetectionScope

getMixedContentDetectionScope

setDetectMoves

isDetectMoves

setMoveAttributeXpath

getMoveAttributeXpath

isRemoveMoveSource

setRemoveMoveSource

isCharacterByCharacterEnabled

setCharacterByCharacterEnabled