com.atlassian.stash.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.
Summary
Public Methods |
void
|
offerAnchors(List<? extends DiffCommentAnchor> anchors)
Offers anchors 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
|
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)
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 .
|
Public Methods
public
void
offerAnchors
(List<? extends DiffCommentAnchor> anchors)
Offers anchors
for any comments which should be included in the diff to the callback.
File
and line
anchors may
both be included in the provided list.
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
anchors
| a list containing zero or more anchors describing comments within the diff or diffs that will be
streamed to the callback
|
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
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)
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 |
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.
|