Mercurial > jhg

annotate src/org/tmatesoft/hg/core/HgChangesetTreeHandler.java @ 556:e55f17a7a195

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
AnnotateFacility renamed to HgBlameFacility and exposed, API shapes out and got some javadoc
author Artem Tikhomirov <tikhomirov.artem@gmail.com>
date Fri, 22 Feb 2013 20:21:24 +0100
parents e6c8b9b654b2
children 6526d8adbc0f
rev   line source
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
1 /*
403
2747b0723867 FIXMEs: work on exceptions and javadoc
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 383
diff changeset
2 * Copyright (c) 2011-2012 TMate Software Ltd
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
3 *
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
4 * This program is free software; you can redistribute it and/or modify
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
5 * it under the terms of the GNU General Public License as published by
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
6 * the Free Software Foundation; version 2 of the License.
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
7 *
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
8 * This program is distributed in the hope that it will be useful,
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
11 * GNU General Public License for more details.
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
12 *
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
13 * For information on how to redistribute this software under
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
14 * the terms of a license other than GNU General Public License
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
15 * contact TMate Software at support@hg4j.com
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
16 */
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
17 package org.tmatesoft.hg.core;
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
18
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
19 import java.util.Collection;
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
20
423
9c9c442b5f2e Major refactoring of exception handling. Low-level API uses RuntimeExceptions, while checked are left for higher level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 403
diff changeset
21 import org.tmatesoft.hg.internal.Callback;
515
e6c8b9b654b2 Provide access to HgDataFile being iterated into HgChangesetTreeHandler.TreeElement to give context for renamed files
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 507
diff changeset
22 import org.tmatesoft.hg.repo.HgDataFile;
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
23 import org.tmatesoft.hg.util.Pair;
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
24
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
25 /**
403
2747b0723867 FIXMEs: work on exceptions and javadoc
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 383
diff changeset
26 * Handler to iterate file history (generally, any revlog) with access to parent-child relations between changesets.
2747b0723867 FIXMEs: work on exceptions and javadoc
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 383
diff changeset
27 *
2747b0723867 FIXMEs: work on exceptions and javadoc
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 383
diff changeset
28 * @see HgLogCommand#execute(HgChangesetTreeHandler)
2747b0723867 FIXMEs: work on exceptions and javadoc
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 383
diff changeset
29 *
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
30 * @author Artem Tikhomirov
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
31 * @author TMate Software Ltd.
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
32 */
423
9c9c442b5f2e Major refactoring of exception handling. Low-level API uses RuntimeExceptions, while checked are left for higher level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 403
diff changeset
33 @Callback
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
34 public interface HgChangesetTreeHandler {
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
35 /**
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
36 * @param entry access to various pieces of information about current tree node. Instances might be
370
a2341e761609 Let callback implementations deliver errors (e,g. own exceptions) to client code
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 366
diff changeset
37 * reused across calls and shall not be kept by client's code
423
9c9c442b5f2e Major refactoring of exception handling. Low-level API uses RuntimeExceptions, while checked are left for higher level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 403
diff changeset
38 * @throws HgCallbackTargetException wrapper for any exception user code may produce
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
39 */
427
31a89587eb04 FIXMEs: consistent names, throws for commands and their handlers. Use of checked exceptions in hi-level api
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 423
diff changeset
40 public void treeElement(HgChangesetTreeHandler.TreeElement entry) throws HgCallbackTargetException;
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
41
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
42 interface TreeElement {
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
43 /**
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
44 * Revision of the revlog being iterated. For example, when walking file history, return value represents file revisions.
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
45 *
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
46 * @return revision of the revlog being iterated.
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
47 */
423
9c9c442b5f2e Major refactoring of exception handling. Low-level API uses RuntimeExceptions, while checked are left for higher level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 403
diff changeset
48 public Nodeid fileRevision();
515
e6c8b9b654b2 Provide access to HgDataFile being iterated into HgChangesetTreeHandler.TreeElement to give context for renamed files
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 507
diff changeset
49
e6c8b9b654b2 Provide access to HgDataFile being iterated into HgChangesetTreeHandler.TreeElement to give context for renamed files
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 507
diff changeset
50 /**
e6c8b9b654b2 Provide access to HgDataFile being iterated into HgChangesetTreeHandler.TreeElement to give context for renamed files
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 507
diff changeset
51 * File node, provided revlog being iterated is a {@link HgDataFile}; {@link #fileRevision()}
e6c8b9b654b2 Provide access to HgDataFile being iterated into HgChangesetTreeHandler.TreeElement to give context for renamed files
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 507
diff changeset
52 * references revision from the history of this very {@link HgDataFile file}.
e6c8b9b654b2 Provide access to HgDataFile being iterated into HgChangesetTreeHandler.TreeElement to give context for renamed files
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 507
diff changeset
53 *
e6c8b9b654b2 Provide access to HgDataFile being iterated into HgChangesetTreeHandler.TreeElement to give context for renamed files
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 507
diff changeset
54 * Comes handy when file history with renames is being followed to find out
e6c8b9b654b2 Provide access to HgDataFile being iterated into HgChangesetTreeHandler.TreeElement to give context for renamed files
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 507
diff changeset
55 * file name for particular revision in the history.
e6c8b9b654b2 Provide access to HgDataFile being iterated into HgChangesetTreeHandler.TreeElement to give context for renamed files
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 507
diff changeset
56 *
e6c8b9b654b2 Provide access to HgDataFile being iterated into HgChangesetTreeHandler.TreeElement to give context for renamed files
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 507
diff changeset
57 * @return instance of the file being walked, or <code>null</code> if it's not a file but other revlog.
e6c8b9b654b2 Provide access to HgDataFile being iterated into HgChangesetTreeHandler.TreeElement to give context for renamed files
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 507
diff changeset
58 */
e6c8b9b654b2 Provide access to HgDataFile being iterated into HgChangesetTreeHandler.TreeElement to give context for renamed files
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 507
diff changeset
59 public HgDataFile file();
366
189dc6dc1c3e Use exceptions to expose errors reading mercurial data
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 328
diff changeset
60
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
61 /**
507
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
62 * @return changeset associated with the current file revision
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
63 */
423
9c9c442b5f2e Major refactoring of exception handling. Low-level API uses RuntimeExceptions, while checked are left for higher level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 403
diff changeset
64 public HgChangeset changeset();
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
65
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
66 /**
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
67 * Lightweight alternative to {@link #changeset()}, identifies changeset in which current file node has been modified
403
2747b0723867 FIXMEs: work on exceptions and javadoc
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 383
diff changeset
68 * @return changeset {@link Nodeid revision}
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
69 */
423
9c9c442b5f2e Major refactoring of exception handling. Low-level API uses RuntimeExceptions, while checked are left for higher level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 403
diff changeset
70 public Nodeid changesetRevision();
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
71
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
72 /**
507
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
73 * Identifies parent changes, changesets where file/revlog in question was modified prior to change being visited.
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
74 *
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
75 * Note, these are not necessarily in direct relation to parents of changeset from {@link #changeset()}
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
76 *
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
77 * Imagine next history (grows from bottom to top):
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
78 * <pre>
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
79 * o A o
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
80 * | \ |
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
81 * o B \/
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
82 * | o C
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
83 * | /
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
84 * o /
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
85 * | /
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
86 * o D
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
87 * </pre>
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
88 *
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
89 * When we are at {@link TreeElement} for <code>A</code>, <code>B</code> and <code>C</code> are changeset parents, naturally. However
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
90 * if the file/revlog we've been walking has not been changed in <code>B</code> and <code>C</code>, but e.g. in <code>D</code> only,
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
91 * then this {@link #parents()} call would return pair with single element only, pointing to <code>D</code>
a6435c1a42d0 Test for HgChangesetTreeHandler - make sure nothing is broken prior to adding --follow support
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 427
diff changeset
92 *
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
93 * @return changesets that correspond to parents of the current file node, either pair element may be <code>null</code>.
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
94 */
423
9c9c442b5f2e Major refactoring of exception handling. Low-level API uses RuntimeExceptions, while checked are left for higher level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 403
diff changeset
95 public Pair<HgChangeset, HgChangeset> parents();
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
96
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
97 /**
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
98 * Lightweight alternative to {@link #parents()}, give {@link Nodeid nodeids} only
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
99 * @return two values, neither is <code>null</code>, use {@link Nodeid#isNull()} to identify parent not set
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
100 */
423
9c9c442b5f2e Major refactoring of exception handling. Low-level API uses RuntimeExceptions, while checked are left for higher level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 403
diff changeset
101 public Pair<Nodeid, Nodeid> parentRevisions();
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
102
366
189dc6dc1c3e Use exceptions to expose errors reading mercurial data
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 328
diff changeset
103 /**
189dc6dc1c3e Use exceptions to expose errors reading mercurial data
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 328
diff changeset
104 * Changes that originate from the given change and bear it as their parent.
189dc6dc1c3e Use exceptions to expose errors reading mercurial data
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 328
diff changeset
105 * @return collection (possibly empty) of immediate children of the change
189dc6dc1c3e Use exceptions to expose errors reading mercurial data
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 328
diff changeset
106 */
423
9c9c442b5f2e Major refactoring of exception handling. Low-level API uses RuntimeExceptions, while checked are left for higher level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 403
diff changeset
107 public Collection<HgChangeset> children();
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
108
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
109 /**
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
110 * Lightweight alternative to {@link #children()}.
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
111 * @return never <code>null</code>
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
112 */
423
9c9c442b5f2e Major refactoring of exception handling. Low-level API uses RuntimeExceptions, while checked are left for higher level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 403
diff changeset
113 public Collection<Nodeid> childRevisions();
328
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
114 }
a674b8590362 Move file tree history to upper API level
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
115 }