comparison src/org/tmatesoft/hg/repo/HgBlameInspector.java @ 603:707b5c7c6fa4

Refactor HgBlameFacility: relevant action methods moved to proper home (HgDataFile), as facility doesn't provide anything but packaging of relevant methods/interfaces
author Artem Tikhomirov <tikhomirov.artem@gmail.com>
date Mon, 06 May 2013 18:29:57 +0200
parents src/org/tmatesoft/hg/repo/HgBlameFacility.java@43cfa08ff3fd
children 5f52074707b2
comparison
equal deleted inserted replaced
602:e3717fc7d26f 603:707b5c7c6fa4
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.repo;
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.util.Adaptable;
23
24 /**
25 * Client's sink for revision differences, diff/annotate functionality.
26 *
27 * When implemented, clients shall not expect new {@link Block blocks} instances in each call.
28 *
29 * In case more information about annotated revision is needed, inspector instances may supply
30 * {@link RevisionDescriptor.Recipient} through {@link Adaptable}.
31 *
32 * @author Artem Tikhomirov
33 * @author TMate Software Ltd.
34 * @since 1.1
35 */
36 @Callback
37 @Experimental(reason="Unstable API")
38 public interface HgBlameInspector {
39
40 void same(EqualBlock block) throws HgCallbackTargetException;
41 void added(AddBlock block) throws HgCallbackTargetException;
42 void changed(ChangeBlock block) throws HgCallbackTargetException;
43 void deleted(DeleteBlock block) throws HgCallbackTargetException;
44
45 /**
46 * Represents content of a block, either as a sequence of bytes or a
47 * sequence of smaller blocks (lines), if appropriate (according to usage context).
48 *
49 * This approach allows line-by-line access to content data along with complete byte sequence for the whole block, i.e.
50 * <pre>
51 * BlockData bd = addBlock.addedLines()
52 * // bd describes data from the addition completely.
53 * // elements of the BlockData are lines
54 * bd.elementCount() == addBlock.totalAddedLines();
55 * // one cat obtain complete addition with
56 * byte[] everythingAdded = bd.asArray();
57 * // or iterate line by line
58 * for (int i = 0; i < bd.elementCount(); i++) {
59 * byte[] lineContent = bd.elementAt(i);
60 * String line = new String(lineContent, fileEncodingCharset);
61 * }
62 * where bd.elementAt(0) is the line at index addBlock.firstAddedLine()
63 * </pre>
64 *
65 * LineData or ChunkData?
66 */
67 public interface BlockData {
68 BlockData elementAt(int index);
69 int elementCount();
70 byte[] asArray();
71 }
72
73 /**
74 * {@link HgBlameInspector} may optionally request extra information about revisions
75 * being inspected, denoting itself as a {@link RevisionDescriptor.Recipient}. This class
76 * provides complete information about file revision under annotation now.
77 */
78 public interface RevisionDescriptor {
79 /**
80 * @return complete source of the diff origin, never <code>null</code>
81 */
82 BlockData origin();
83 /**
84 * @return complete source of the diff target, never <code>null</code>
85 */
86 BlockData target();
87 /**
88 * @return changeset revision index of original file, or {@link HgRepository#NO_REVISION} if it's the very first revision
89 */
90 int originChangesetIndex();
91 /**
92 * @return changeset revision index of the target file
93 */
94 int targetChangesetIndex();
95 /**
96 * @return <code>true</code> if this revision is merge
97 */
98 boolean isMerge();
99 /**
100 * @return changeset revision index of the second, merged parent
101 */
102 int mergeChangesetIndex();
103 /**
104 * @return revision index of the change in target file's revlog
105 */
106 int fileRevisionIndex();
107
108 /**
109 * @return file object under blame (target file)
110 */
111 HgDataFile file();
112
113 /**
114 * Implement to indicate interest in {@link RevisionDescriptor}.
115 *
116 * Note, instance of {@link RevisionDescriptor} is the same for
117 * {@link #start(RevisionDescriptor)} and {@link #done(RevisionDescriptor)}
118 * methods, and not necessarily a new one (i.e. <code>==</code>) for the next
119 * revision announced.
120 */
121 @Callback
122 public interface Recipient {
123 /**
124 * Comes prior to any change {@link Block blocks}
125 */
126 void start(RevisionDescriptor revisionDescription) throws HgCallbackTargetException;
127 /**
128 * Comes after all change {@link Block blocks} were dispatched
129 */
130 void done(RevisionDescriptor revisionDescription) throws HgCallbackTargetException;
131 }
132 }
133
134 /**
135 * Each change block comes from a single origin, blocks that are result of a merge
136 * have {@link #originChangesetIndex()} equal to {@link RevisionDescriptor#mergeChangesetIndex()}.
137 */
138 public interface Block {
139 int originChangesetIndex();
140 int targetChangesetIndex();
141 }
142
143 public interface EqualBlock extends Block {
144 int originStart();
145 int targetStart();
146 int length();
147 BlockData content();
148 }
149
150 public interface AddBlock extends Block {
151 /**
152 * @return line index in the origin where this block is inserted
153 */
154 int insertedAt();
155 /**
156 * @return line index of the first added line in the target revision
157 */
158 int firstAddedLine();
159 /**
160 * @return number of added lines in this block
161 */
162 int totalAddedLines();
163 /**
164 * @return content of added lines
165 */
166 BlockData addedLines();
167 }
168 public interface DeleteBlock extends Block {
169 /**
170 * @return line index in the target revision were this deleted block would be
171 */
172 int removedAt();
173 /**
174 * @return line index of the first removed line in the original revision
175 */
176 int firstRemovedLine();
177 /**
178 * @return number of deleted lines in this block
179 */
180 int totalRemovedLines();
181 /**
182 * @return content of deleted lines
183 */
184 BlockData removedLines();
185 }
186 public interface ChangeBlock extends AddBlock, DeleteBlock {
187 }
188 }