Mercurial > hg4j

comparison src/org/tmatesoft/hg/core/HgChangesetTreeHandler.java @ 628:6526d8adbc0f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Explicit HgRuntimeException to facilitate easy switch from runtime to checked exceptions
author Artem Tikhomirov <tikhomirov.artem@gmail.com>
date Wed, 22 May 2013 15:52:31 +0200
parents e6c8b9b654b2
children
comparison
equal deleted inserted replaced
627:5153eb73b18d 628:6526d8adbc0f
1 /* 1 /*
2 * Copyright (c) 2011-2012 TMate Software Ltd 2 * Copyright (c) 2011-2013 TMate Software Ltd
3 * 3 *
4 * This program is free software; you can redistribute it and/or modify 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 5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; version 2 of the License. 6 * the Free Software Foundation; version 2 of the License.
7 * 7 *
18 18
19 import java.util.Collection; 19 import java.util.Collection;
20 20
21 import org.tmatesoft.hg.internal.Callback; 21 import org.tmatesoft.hg.internal.Callback;
22 import org.tmatesoft.hg.repo.HgDataFile; 22 import org.tmatesoft.hg.repo.HgDataFile;
23 import org.tmatesoft.hg.repo.HgRuntimeException;
23 import org.tmatesoft.hg.util.Pair; 24 import org.tmatesoft.hg.util.Pair;
24 25
25 /** 26 /**
26 * Handler to iterate file history (generally, any revlog) with access to parent-child relations between changesets. 27 * Handler to iterate file history (generally, any revlog) with access to parent-child relations between changesets.
27 * 28 *
34 public interface HgChangesetTreeHandler { 35 public interface HgChangesetTreeHandler {
35 /** 36 /**
36 * @param entry access to various pieces of information about current tree node. Instances might be 37 * @param entry access to various pieces of information about current tree node. Instances might be
37 * reused across calls and shall not be kept by client's code 38 * reused across calls and shall not be kept by client's code
38 * @throws HgCallbackTargetException wrapper for any exception user code may produce 39 * @throws HgCallbackTargetException wrapper for any exception user code may produce
40 * @throws HgRuntimeException propagates library issues. <em>Runtime exception</em>
39 */ 41 */
40 public void treeElement(HgChangesetTreeHandler.TreeElement entry) throws HgCallbackTargetException; 42 public void treeElement(HgChangesetTreeHandler.TreeElement entry) throws HgCallbackTargetException, HgRuntimeException;
41 43
42 interface TreeElement { 44 interface TreeElement {
43 /** 45 /**
44 * Revision of the revlog being iterated. For example, when walking file history, return value represents file revisions. 46 * Revision of the revlog being iterated. For example, when walking file history, return value represents file revisions.
45 * 47 *
46 * @return revision of the revlog being iterated. 48 * @return revision of the revlog being iterated.
49 * @throws HgRuntimeException subclass thereof to indicate issues with the library. <em>Runtime exception</em>
47 */ 50 */
48 public Nodeid fileRevision(); 51 public Nodeid fileRevision() throws HgRuntimeException;
49 52
50 /** 53 /**
51 * File node, provided revlog being iterated is a {@link HgDataFile}; {@link #fileRevision()} 54 * File node, provided revlog being iterated is a {@link HgDataFile}; {@link #fileRevision()}
52 * references revision from the history of this very {@link HgDataFile file}. 55 * references revision from the history of this very {@link HgDataFile file}.
53 * 56 *
54 * Comes handy when file history with renames is being followed to find out 57 * Comes handy when file history with renames is being followed to find out
55 * file name for particular revision in the history. 58 * file name for particular revision in the history.
56 * 59 *
57 * @return instance of the file being walked, or <code>null</code> if it's not a file but other revlog. 60 * @return instance of the file being walked, or <code>null</code> if it's not a file but other revlog.
61 * @throws HgRuntimeException subclass thereof to indicate issues with the library. <em>Runtime exception</em>
58 */ 62 */
59 public HgDataFile file(); 63 public HgDataFile file() throws HgRuntimeException;
60 64
61 /** 65 /**
62 * @return changeset associated with the current file revision 66 * @return changeset associated with the current file revision
67 * @throws HgRuntimeException subclass thereof to indicate issues with the library. <em>Runtime exception</em>
63 */ 68 */
64 public HgChangeset changeset(); 69 public HgChangeset changeset() throws HgRuntimeException;
65 70
66 /** 71 /**
67 * Lightweight alternative to {@link #changeset()}, identifies changeset in which current file node has been modified 72 * Lightweight alternative to {@link #changeset()}, identifies changeset in which current file node has been modified
68 * @return changeset {@link Nodeid revision} 73 * @return changeset {@link Nodeid revision}
74 * @throws HgRuntimeException subclass thereof to indicate issues with the library. <em>Runtime exception</em>
69 */ 75 */
70 public Nodeid changesetRevision(); 76 public Nodeid changesetRevision() throws HgRuntimeException;
71 77
72 /** 78 /**
73 * Identifies parent changes, changesets where file/revlog in question was modified prior to change being visited. 79 * Identifies parent changes, changesets where file/revlog in question was modified prior to change being visited.
74 * 80 *
75 * Note, these are not necessarily in direct relation to parents of changeset from {@link #changeset()} 81 * Note, these are not necessarily in direct relation to parents of changeset from {@link #changeset()}
89 * When we are at {@link TreeElement} for <code>A</code>, <code>B</code> and <code>C</code> are changeset parents, naturally. However 95 * When we are at {@link TreeElement} for <code>A</code>, <code>B</code> and <code>C</code> are changeset parents, naturally. However
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, 96 * 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,
91 * then this {@link #parents()} call would return pair with single element only, pointing to <code>D</code> 97 * then this {@link #parents()} call would return pair with single element only, pointing to <code>D</code>
92 * 98 *
93 * @return changesets that correspond to parents of the current file node, either pair element may be <code>null</code>. 99 * @return changesets that correspond to parents of the current file node, either pair element may be <code>null</code>.
100 * @throws HgRuntimeException subclass thereof to indicate issues with the library. <em>Runtime exception</em>
94 */ 101 */
95 public Pair<HgChangeset, HgChangeset> parents(); 102 public Pair<HgChangeset, HgChangeset> parents() throws HgRuntimeException;
96 103
97 /** 104 /**
98 * Lightweight alternative to {@link #parents()}, give {@link Nodeid nodeids} only 105 * Lightweight alternative to {@link #parents()}, give {@link Nodeid nodeids} only
99 * @return two values, neither is <code>null</code>, use {@link Nodeid#isNull()} to identify parent not set 106 * @return two values, neither is <code>null</code>, use {@link Nodeid#isNull()} to identify parent not set
107 * @throws HgRuntimeException subclass thereof to indicate issues with the library. <em>Runtime exception</em>
100 */ 108 */
101 public Pair<Nodeid, Nodeid> parentRevisions(); 109 public Pair<Nodeid, Nodeid> parentRevisions() throws HgRuntimeException;
102 110
103 /** 111 /**
104 * Changes that originate from the given change and bear it as their parent. 112 * Changes that originate from the given change and bear it as their parent.
105 * @return collection (possibly empty) of immediate children of the change 113 * @return collection (possibly empty) of immediate children of the change
114 * @throws HgRuntimeException subclass thereof to indicate issues with the library. <em>Runtime exception</em>
106 */ 115 */
107 public Collection<HgChangeset> children(); 116 public Collection<HgChangeset> children() throws HgRuntimeException;
108 117
109 /** 118 /**
110 * Lightweight alternative to {@link #children()}. 119 * Lightweight alternative to {@link #children()}.
111 * @return never <code>null</code> 120 * @return never <code>null</code>
121 * @throws HgRuntimeException subclass thereof to indicate issues with the library. <em>Runtime exception</em>
112 */ 122 */
113 public Collection<Nodeid> childRevisions(); 123 public Collection<Nodeid> childRevisions() throws HgRuntimeException;
114 } 124 }
115 } 125 }