ro.sync.diff.api

Interface AuthorDifferencePerformer

@API(type=NOT_EXTENDABLE,
     src=PUBLIC)
public interface AuthorDifferencePerformer

The AuthorDifferencePerformer is used to compare two Author documents using a set of options. The result of the diff is a list with the differences between the resources.

Since:

22
*********************************
EXPERIMENTAL - Subject to change
********************************

Please note that this API is not marked as final and it can change in one of the next versions of the application. If you have suggestions, comments about it, please let us know.

Method Summary

Modifier and Type	Method and Description
java.util.List<Difference>	performDiff(DiffProgressListener diffProgressListener) Performs the diff operation between the resources represented by the two AuthorAccess.
void	setBaseDocument(AuthorAccess baseAuthorAccess) Set the base Author document, used to perform a three-way comparison.
void	setDocumentsToCompare(AuthorAccess leftAuthorAccess, AuthorAccess rightAuthorAccess) Set the documents to be compared.
void	setOptions(DiffOptions diffOptions) Set the options used by the diff performer to perform the comparison.
void	stop() Signal to the diff performer that it must stop.

Method Detail

setBaseDocument

void setBaseDocument(AuthorAccess baseAuthorAccess)

Set the base Author document, used to perform a three-way comparison. It can be null.

Parameters:

baseAuthorAccess - The access to the base Author document.

setDocumentsToCompare

void setDocumentsToCompare(AuthorAccess leftAuthorAccess,
                           AuthorAccess rightAuthorAccess)

Set the documents to be compared.

Parameters:

leftAuthorAccess - The access to the left Author document.

rightAuthorAccess - The access to the right Author document.

setOptions

void setOptions(DiffOptions diffOptions)

Set the options used by the diff performer to perform the comparison. It can be null meaning a default set of options will be used.

Parameters:

diffOptions - The options.

performDiff

java.util.List<Difference> performDiff(DiffProgressListener diffProgressListener)
                                throws DiffException,
                                       java.io.IOException

Performs the diff operation between the resources represented by the two AuthorAccess.

Parameters:

diffProgressListener - The DiffProgressListener notified about the progress of the diff. It can be null when the diff progress doesn't need to be monitored.

Returns:

The list with the differences. If the resources are identical or the diff fails the list will be empty.
The returned differences are represented by Difference objects that contain the start and end offsets in the Author content for each Author document.

The Author content contains the entire XML document text and special marker characters.
Each author node points in the content to the start and end marker characters which are used to delimit it's range. The start and end offsets pointed to by the AuthorNode can be retrieved using the AuthorNode.getStartOffset() and AuthorNode.getEndOffset()

The following image represents the architecture of an Author document fragment that is a part of the Author document content. The red markers represent special control characters which represent the node ranges:



If the hierarchical diff is activated (DiffOptions.isEnableHierarchicalDiff() returns true) then the returned list contains DifferenceParent elements.

Throws:

DiffException - If the diff operation fails or it is stopped before it finishes.

java.io.IOException

stop

void stop()

Signal to the diff performer that it must stop.