Mercurial > hg4j

comparison src/org/tmatesoft/hg/core/HgChangesetTreeHandler.java @ 403:2747b0723867

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
FIXMEs: work on exceptions and javadoc
author Artem Tikhomirov <tikhomirov.artem@gmail.com>
date Mon, 05 Mar 2012 14:50:51 +0100
parents 994b5813a925
children 9c9c442b5f2e
comparison
equal deleted inserted replaced
402:1fcc7f7b6d65 403:2747b0723867
1 /* 1 /*
2 * Copyright (c) 2011 TMate Software Ltd 2 * Copyright (c) 2011-2012 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 *
20 20
21 import org.tmatesoft.hg.util.CancelledException; 21 import org.tmatesoft.hg.util.CancelledException;
22 import org.tmatesoft.hg.util.Pair; 22 import org.tmatesoft.hg.util.Pair;
23 23
24 /** 24 /**
25 * 25 * Handler to iterate file history (generally, any revlog) with access to parent-child relations between changesets.
26 *
27 * @see HgLogCommand#execute(HgChangesetTreeHandler)
28 *
26 * @author Artem Tikhomirov 29 * @author Artem Tikhomirov
27 * @author TMate Software Ltd. 30 * @author TMate Software Ltd.
28 */ 31 */
29 public interface HgChangesetTreeHandler { 32 public interface HgChangesetTreeHandler {
30 /** 33 /**
31 * @param entry access to various pieces of information about current tree node. Instances might be 34 * @param entry access to various pieces of information about current tree node. Instances might be
32 * reused across calls and shall not be kept by client's code 35 * reused across calls and shall not be kept by client's code
36 * @throws HgException allows implementers propagate errors from {@link TreeElement} or other parts of the library.
33 * @throws HgCallbackTargetException.Wrap wrapper object for any exception user code may produce. Wrapped exception would get re-thrown with {@link HgCallbackTargetException} 37 * @throws HgCallbackTargetException.Wrap wrapper object for any exception user code may produce. Wrapped exception would get re-thrown with {@link HgCallbackTargetException}
34 * @throws CancelledException if execution of the operation was cancelled 38 * @throws CancelledException if execution of the operation was cancelled
35 */ 39 */
36 public void next(HgChangesetTreeHandler.TreeElement entry) throws HgCallbackTargetException.Wrap, CancelledException; 40 public void next(HgChangesetTreeHandler.TreeElement entry) throws HgException, HgCallbackTargetException.Wrap, CancelledException;
37 41
38 interface TreeElement { 42 interface TreeElement {
39 /** 43 /**
40 * Revision of the revlog being iterated. For example, when walking file history, return value represents file revisions. 44 * Revision of the revlog being iterated. For example, when walking file history, return value represents file revisions.
41 * 45 *
42 * @return revision of the revlog being iterated. 46 * @return revision of the revlog being iterated.
47 * @throws HgException to indicate failure dealing with Mercurial data
43 */ 48 */
44 public Nodeid fileRevision(); 49 public Nodeid fileRevision() throws HgException;
45 50
46 /** 51 /**
47 * @return changeset associated with the current revision 52 * @return changeset associated with the current revision
48 * @throws HgException indicates failure dealing with Mercurial data 53 * @throws HgException to indicate failure dealing with Mercurial data
49 */ 54 */
50 public HgChangeset changeset() throws HgException; 55 public HgChangeset changeset() throws HgException;
51 56
52 /** 57 /**
53 * Lightweight alternative to {@link #changeset()}, identifies changeset in which current file node has been modified 58 * Lightweight alternative to {@link #changeset()}, identifies changeset in which current file node has been modified
54 * @return changeset {@link Nodeid} 59 * @return changeset {@link Nodeid revision}
60 * @throws HgException to indicate failure dealing with Mercurial data
55 */ 61 */
56 public Nodeid changesetRevision(); 62 public Nodeid changesetRevision() throws HgException;
57 63
58 /** 64 /**
59 * Node, these are not necessarily in direct relation to parents of changeset from {@link #changeset()} 65 * Node, these are not necessarily in direct relation to parents of changeset from {@link #changeset()}
60 * @return changesets that correspond to parents of the current file node, either pair element may be <code>null</code>. 66 * @return changesets that correspond to parents of the current file node, either pair element may be <code>null</code>.
61 * @throws HgException indicates failure dealing with Mercurial data 67 * @throws HgException to indicate failure dealing with Mercurial data
62 */ 68 */
63 public Pair<HgChangeset, HgChangeset> parents() throws HgException; 69 public Pair<HgChangeset, HgChangeset> parents() throws HgException;
64 70
65 /** 71 /**
66 * Lightweight alternative to {@link #parents()}, give {@link Nodeid nodeids} only 72 * Lightweight alternative to {@link #parents()}, give {@link Nodeid nodeids} only
67 * @return two values, neither is <code>null</code>, use {@link Nodeid#isNull()} to identify parent not set 73 * @return two values, neither is <code>null</code>, use {@link Nodeid#isNull()} to identify parent not set
74 * @throws HgException to indicate failure dealing with Mercurial data
68 */ 75 */
69 public Pair<Nodeid, Nodeid> parentRevisions(); 76 public Pair<Nodeid, Nodeid> parentRevisions() throws HgException;
70 77
71 /** 78 /**
72 * Changes that originate from the given change and bear it as their parent. 79 * Changes that originate from the given change and bear it as their parent.
73 * @return collection (possibly empty) of immediate children of the change 80 * @return collection (possibly empty) of immediate children of the change
74 * @throws HgException indicates failure dealing with Mercurial data 81 * @throws HgException to indicate failure dealing with Mercurial data
75 */ 82 */
76 public Collection<HgChangeset> children() throws HgException; 83 public Collection<HgChangeset> children() throws HgException;
77 84
78 /** 85 /**
79 * Lightweight alternative to {@link #children()}. 86 * Lightweight alternative to {@link #children()}.
80 * @return never <code>null</code> 87 * @return never <code>null</code>
88 * @throws HgException to indicate failure dealing with Mercurial data
81 */ 89 */
82 public Collection<Nodeid> childRevisions(); 90 public Collection<Nodeid> childRevisions() throws HgException;
83 } 91 }
84 } 92 }