Summary: Methods | [Expand All]
public interface

DiffContentCallback

com.atlassian.bitbucket.content.DiffContentCallback
Known Indirect Subclasses

Class Overview

A callback for receiving streaming diff details.

Diff contents are broken into 3 levels:

  • Segment - A collection of one or more content lines sharing the same DiffSegmentType
  • Hunk - A collection of segments, pinned to starting lines within the source and destination, representing contiguous lines within the files being compared
  • Diff - A collection of hunks comprising the changes between a given source and destination
In the case of deleted files, the segment will consistent entirely of removed lines; conversely, for newly-added files, the segment will consist entirely of added lines.

Certain types of changes, such as a copy or a rename, may emit a diff without any hunks.

Note: Implementors are strongly encouraged to extend from AbstractDiffContentCallback. This interface will change, over time, and any class implementing it directly will be broken by such changes. Extending from the abstract class will help prevent such breakages.

See Also

Summary

Public Methods
void offerThreads(Stream<CommentThread> threads)
Offers threads for any comments which should be included in the diff to the callback.
void onBinary(Path src, Path dst)
Called to indicate a binary file differs.
void onDiffEnd(boolean truncated)
Called upon reaching the end of the current overall diff, indicating no more changes exist for the current source/destination pair.
void onDiffStart(Path src, Path dst)
Called to mark the start of an overall diff.
void onEnd(DiffSummary summary)
Called after the final onDiffEnd(boolean), after all diffs have been streamed.
void onHunkEnd(boolean truncated)
Called upon reaching the end of a hunk of segments within the current overall diff.
void onHunkStart(int srcLine, int srcSpan, int dstLine, int dstSpan, String context)
Called to mark the start of a new hunk within the current overall diff, containing one or more contiguous segments of lines anchored at the provided line numbers in the source and destination files.
void onSegmentEnd(boolean truncated)
Called upon reaching the end of a segment within the current hunk, where a segment may end either because lines with a different type were encountered or because there are no more contiguous lines in the hunk.
void onSegmentLine(String line, ConflictMarker marker, boolean truncated)
Called to process a line within the current segment.
void onSegmentStart(DiffSegmentType type)
Called to mark the start of a new segment within the current hunk, containing one or more contiguous lines which all share the same type.
void onStart(DiffContext context)
Called before the first onDiffStart(Path, Path).

Public Methods

public void offerThreads (Stream<CommentThread> threads)

Offers threads for any comments which should be included in the diff to the callback. Threads with both File and line anchors may both be included in the provided stream.

Note: If this method is going to be invoked, it will always be invoked before the first invocation of onDiffStart(Path, Path). This method will be called at most once. If multiple diffs are going to be output to the callback, the paths of the anchors may reference any of the files whose diffs will follow. Reconciling anchors to diffs is left to the implementation.

Parameters
threads a stream of zero or more threads describing comments within the diff or diffs that will be streamed to the callback. It can only be consumed once
Throws
IOException

public void onBinary (Path src, Path dst)

Called to indicate a binary file differs. The exact differences cannot be effectively conveyed, however, so no hunks/segments will be provided for binary files.

Parameters
src the source binary file
dst the destination binary file
Throws
IOException May be thrown by implementations which perform I/O.

public void onDiffEnd (boolean truncated)

Called upon reaching the end of the current overall diff, indicating no more changes exist for the current source/destination pair.

Parameters
truncated true if any segment or hunk in the diff had to be truncated; otherwise, false
Throws
IOException May be thrown by implementations which perform I/O.

public void onDiffStart (Path src, Path dst)

Called to mark the start of an overall diff. The source and destination paths being compared, relative to their containing repository, are provided.

  • For added files, the src path will be null
  • For deleted files, the dst path will be null
  • For all other changes, both paths will be provided

Parameters
src the source file being compared
dst the destination file being compared
Throws
IOException May be thrown by implementations which perform I/O.

public void onEnd (DiffSummary summary)

Called after the final onDiffEnd(boolean), after all diffs have been streamed.

Parameters
summary summarizes the request and the streamed diff
Throws
IOException May be thrown by implementations which perform I/O.

public void onHunkEnd (boolean truncated)

Called upon reaching the end of a hunk of segments within the current overall diff.

Parameters
truncated true if any segment in the hunk had to be truncated; otherwise, false
Throws
IOException May be thrown by implementations which perform I/O.

public void onHunkStart (int srcLine, int srcSpan, int dstLine, int dstSpan, String context)

Called to mark the start of a new hunk within the current overall diff, containing one or more contiguous segments of lines anchored at the provided line numbers in the source and destination files.

Parameters
srcLine the line in the source file at which the hunk starts
srcSpan the number of lines spanned by this hunk in the source file
dstLine the line in the destination file at which the hunk starts
dstSpan the number of lines spanned by this hunk in the destination file
context an optional context, such as a method or class name, for the hunk's lines
Throws
IOException May be thrown by implementations which perform I/O.

public void onSegmentEnd (boolean truncated)

Called upon reaching the end of a segment within the current hunk, where a segment may end either because lines with a different type were encountered or because there are no more contiguous lines in the hunk.

Note: Internal restrictions may prevent streaming full segments if they are overly large. For example, if a new file containing tens of thousands of lines is added (or an existing file of such size is deleted), the resulting segment may be truncated.

Parameters
truncated true if the overall segment exceeded the maximum allowed lines, indicating one or more lines were omitted from the segment; otherwise false to indicate all lines were sent
Throws
IOException May be thrown by implementations which perform I/O.

public void onSegmentLine (String line, ConflictMarker marker, boolean truncated)

Called to process a line within the current segment.

Pull request diffs may contain conflicts, if the pull request cannot be merged cleanly. The marker conveys this information.

  • null: The line is not conflicted
  • MARKER: The line is a conflict marker
  • OURS: The line is conflicting, and is present in the merge target
  • THEIRS: The line is conflicting, and is present in the merge source

Note: Internal restrictions may prevent receiving the full line if it contains too many characters. When this happens truncated will be set to true to indicate the line is not complete.

Parameters
line a single line of content
marker indicates whether the line is conflicted and, if it is, which side of the conflict it's on
truncated true if the line exceeded the maximum allowed length and was truncated; otherwise, false to indicate the line is complete
Throws
IOException May be thrown by implementations which perform I/O.

public void onSegmentStart (DiffSegmentType type)

Called to mark the start of a new segment within the current hunk, containing one or more contiguous lines which all share the same type.

Parameters
type the shared type for all lines in the new segment
Throws
IOException May be thrown by implementations which perform I/O.

public void onStart (DiffContext context)

Called before the first onDiffStart(Path, Path).

Parameters
context provides details about the diff request for which results are being streamed
Throws
IOException May be thrown by implementations which perform I/O.