Mercurial > jhg

comparison src/org/tmatesoft/hg/core/HgBlameInspector.java @ 629:5f52074707b2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Diff/blame methods as command, their residence in HgDataFile was a mistake
author Artem Tikhomirov <tikhomirov.artem@gmail.com>
date Wed, 22 May 2013 16:46:15 +0200
parents src/org/tmatesoft/hg/repo/HgBlameInspector.java@707b5c7c6fa4
children 497e697636fc
comparison
equal deleted inserted replaced
628:6526d8adbc0f 629:5f52074707b2
1 /*
2 * Copyright (c) 2013 TMate Software Ltd
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; version 2 of the License.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * For information on how to redistribute this software under
14 * the terms of a license other than GNU General Public License
15 * contact TMate Software at support@hg4j.com
16 */
17 package org.tmatesoft.hg.core;
18
19 import org.tmatesoft.hg.core.HgCallbackTargetException;
20 import org.tmatesoft.hg.internal.Callback;
21 import org.tmatesoft.hg.internal.Experimental;
22 import org.tmatesoft.hg.repo.HgDataFile;
23 import org.tmatesoft.hg.util.Adaptable;
24
25 /**
26 * Client's sink for revision differences, diff/annotate functionality.
27 *
28 * When implemented, clients shall not expect new {@link Block blocks} instances in each call.
29 *
30 * In case more information about annotated revision is needed, inspector instances may supply
31 * {@link RevisionDescriptor.Recipient} through {@link Adaptable}.
32 *
33 * @author Artem Tikhomirov
34 * @author TMate Software Ltd.
35 * @since 1.1
36 */
37 @Callback
38 @Experimental(reason="Unstable API")
39 public interface HgBlameInspector {
40
41 void same(EqualBlock block) throws HgCallbackTargetException;
42 void added(AddBlock block) throws HgCallbackTargetException;
43 void changed(ChangeBlock block) throws HgCallbackTargetException;
44 void deleted(DeleteBlock block) throws HgCallbackTargetException;
45
46 /**
47 * Represents content of a block, either as a sequence of bytes or a
48 * sequence of smaller blocks (lines), if appropriate (according to usage context).
49 *
50 * This approach allows line-by-line access to content data along with complete byte sequence for the whole block, i.e.
51 * <pre>
52 * BlockData bd = addBlock.addedLines()
53 * // bd describes data from the addition completely.
54 * // elements of the BlockData are lines
55 * bd.elementCount() == addBlock.totalAddedLines();
56 * // one cat obtain complete addition with
57 * byte[] everythingAdded = bd.asArray();
58 * // or iterate line by line
59 * for (int i = 0; i < bd.elementCount(); i++) {
60 * byte[] lineContent = bd.elementAt(i);
61 * String line = new String(lineContent, fileEncodingCharset);
62 * }
63 * where bd.elementAt(0) is the line at index addBlock.firstAddedLine()
64 * </pre>
65 *
66 * LineData or ChunkData?
67 */
68 public interface BlockData {
69 BlockData elementAt(int index);
70 int elementCount();
71 byte[] asArray();
72 }
73
74 /**
75 * {@link HgBlameInspector} may optionally request extra information about revisions
76 * being inspected, denoting itself as a {@link RevisionDescriptor.Recipient}. This class
77 * provides complete information about file revision under annotation now.
78 */
79 public interface RevisionDescriptor {
80 /**
81 * @return complete source of the diff origin, never <code>null</code>
82 */
83 BlockData origin();
84 /**
85 * @return complete source of the diff target, never <code>null</code>
86 */
87 BlockData target();
88 /**
89 * @return changeset revision index of original file, or {@link HgRepository#NO_REVISION} if it's the very first revision
90 */
91 int originChangesetIndex();
92 /**
93 * @return changeset revision index of the target file
94 */
95 int targetChangesetIndex();
96 /**
97 * @return <code>true</code> if this revision is merge
98 */
99 boolean isMerge();
100 /**
101 * @return changeset revision index of the second, merged parent
102 */
103 int mergeChangesetIndex();
104 /**
105 * @return revision index of the change in target file's revlog
106 */
107 int fileRevisionIndex();
108
109 /**
110 * @return file object under blame (target file)
111 */
112 HgDataFile file();
113
114 /**
115 * Implement to indicate interest in {@link RevisionDescriptor}.
116 *
117 * Note, instance of {@link RevisionDescriptor} is the same for
118 * {@link #start(RevisionDescriptor)} and {@link #done(RevisionDescriptor)}
119 * methods, and not necessarily a new one (i.e. <code>==</code>) for the next
120 * revision announced.
121 */
122 @Callback
123 public interface Recipient {
124 /**
125 * Comes prior to any change {@link Block blocks}
126 */
127 void start(RevisionDescriptor revisionDescription) throws HgCallbackTargetException;
128 /**
129 * Comes after all change {@link Block blocks} were dispatched
130 */
131 void done(RevisionDescriptor revisionDescription) throws HgCallbackTargetException;
132 }
133 }
134
135 /**
136 * Each change block comes from a single origin, blocks that are result of a merge
137 * have {@link #originChangesetIndex()} equal to {@link RevisionDescriptor#mergeChangesetIndex()}.
138 */
139 public interface Block {
140 int originChangesetIndex();
141 int targetChangesetIndex();
142 }
143
144 public interface EqualBlock extends Block {
145 int originStart();
146 int targetStart();
147 int length();
148 BlockData content();
149 }
150
151 public interface AddBlock extends Block {
152 /**
153 * @return line index in the origin where this block is inserted
154 */
155 int insertedAt();
156 /**
157 * @return line index of the first added line in the target revision
158 */
159 int firstAddedLine();
160 /**
161 * @return number of added lines in this block
162 */
163 int totalAddedLines();
164 /**
165 * @return content of added lines
166 */
167 BlockData addedLines();
168 }
169 public interface DeleteBlock extends Block {
170 /**
171 * @return line index in the target revision were this deleted block would be
172 */
173 int removedAt();
174 /**
175 * @return line index of the first removed line in the original revision
176 */
177 int firstRemovedLine();
178 /**
179 * @return number of deleted lines in this block
180 */
181 int totalRemovedLines();
182 /**
183 * @return content of deleted lines
184 */
185 BlockData removedLines();
186 }
187 public interface ChangeBlock extends AddBlock, DeleteBlock {
188 }
189 }