1 /*
2 StatCvs - CVS statistics generation
3 Copyright (C) 2002 Lukasz Pekacki <lukasz@pekacki.de>
4 http://statcvs.sf.net/
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Lesser General Public
8 License as published by the Free Software Foundation; either
9 version 2.1 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Lesser General Public License for more details.
15
16 You should have received a copy of the GNU Lesser General Public
17 License along with this library; if not, write to the Free Software
18 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 */
20 package net.sf.statsvn.input;
21
22 import java.util.Map;
23
24 /**
25 * <p>
26 * Interface for defining a Builder that constructs a data structure from a SVM
27 * logfile. {@link SvnLogfileParser} takes an instance of this interface and
28 * will call methods on the interface for every piece of data it encounters in
29 * the log.
30 * </p>
31 *
32 * <p>
33 * First, {@link #buildModule} will be called with the name of the module. Then,
34 * {@link #buildFile} will be called with the filename and other pieces of
35 * information of the first file in the log. Then, for every revision of this
36 * file, {@link #buildRevision} is called. The calls to <tt>buildFile</tt> and
37 * <tt>buildRevision</tt> are repeated for every file in the log.
38 * </p>
39 *
40 * <p>
41 * The files are in no particular order. The revisions of one file are ordered
42 * by time, beginning with the <em>most recent</em>.
43 * </p>
44 *
45 * @author Richard Cyganiak <richard@cyganiak.de>
46 * @author Tammo van Lessen
47 * @version $Id: SvnLogBuilder.java 351 2008-03-28 18:46:26Z benoitx $
48 */
49 public interface SvnLogBuilder {
50
51 /**
52 * Starts building a module.
53 *
54 * @param moduleName
55 * the name of the module
56 */
57 void buildModule(String moduleName);
58
59 /**
60 * Starts building a new file. The files are not processed in any particular
61 * order.
62 *
63 * @param filename
64 * the file's name with path relative to the module, for example
65 * "path/file.txt"
66 * @param isBinary
67 * <tt>true</tt> if it's a binary file
68 * @param isInAttic
69 * <tt>true</tt> if the file is dead on the main branch
70 * @param revBySymnames
71 * maps revision (string) by symbolic name (string)
72 * @param dateBySymnames
73 * maps date (date) by symbolic name (string)
74 */
75 void buildFile(String filename, boolean isBinary, boolean isInAttic, Map revBySymnames, final Map dateBySymnames);
76
77 /**
78 * Adds a revision to the last file that was built.. The revisions are added
79 * in SVN logfile order, that is starting with the most recent one.
80 *
81 * @param data
82 * the revision
83 */
84 void buildRevision(RevisionData data);
85
86 /**
87 * Adds a file to the attic. This method should only be called if our first
88 * invocation to (@link #buildFile(String, boolean, boolean, Map)) was given
89 * an invalid isInAttic field.
90 *
91 * This is a way to handle post-processing of implicit deletions at the same
92 * time as the implicit additions that can be found in Subversion.
93 *
94 * @param filename
95 * the filename to add to the attic.
96 */
97 void addToAttic(String filename);
98
99 /**
100 * New in StatSVN: We need to have access to FileBuilders after they have
101 * been created to populate them with version numbers later on.
102 *
103 * @todo Beef up this interface to better encapsulate the data structure.
104 *
105 * @return this builder's contained (@link FileBuilder)s.
106 */
107 Map getFileBuilders();
108
109 /**
110 * New in StatSVN: Updates a particular revision for a file with new line
111 * count information. If the file or revision does not exist, action will do
112 * nothing.
113 *
114 * Necessary because line counts are not given in the log file and hence can
115 * only be added in a second pass.
116 *
117 * @param filename
118 * the file to be updated
119 * @param revisionNumber
120 * the revision number to be updated
121 * @param linesAdded
122 * the lines that were added
123 * @param linesRemoved
124 * the lines that were removed
125 */
126 void updateRevision(String filename, String revisionNumber, int linesAdded, int linesRemoved);
127
128 /**
129 * Matches a filename against the include and exclude patterns. If no
130 * include pattern was specified, all files will be included. If no exclude
131 * pattern was specified, no files will be excluded.
132 *
133 * @param filename
134 * a filename
135 * @return <tt>true</tt> if the filename matches one of the include
136 * patterns and does not match any of the exclude patterns. If it
137 * matches an include and an exclude pattern, <tt>false</tt> will
138 * be returned.
139 */
140 boolean matchesPatterns(final String filename);
141
142 /**
143 * Matches a tag against the tag patterns.
144 *
145 * @param tag
146 * a tag
147 * @return <tt>true</tt> if the tag matches the tag pattern.
148 */
149 boolean matchesTagPatterns(final String tag);
150 }