File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\core\src\main\java\hudson\scm\ChangeLogSet.java.html

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 * THE SOFTWARE.
23 */
24 package hudson.scm;
25
26 import hudson.MarkupText;
27 import hudson.Util;
28 import hudson.model.AbstractBuild;
29 import hudson.model.User;
30 import org.kohsuke.stapler.export.Exported;
31 import org.kohsuke.stapler.export.ExportedBean;
32
33 import java.util.ArrayList;
34 import java.util.Collection;
35 import java.util.Date;
36 import java.util.Iterator;
37 import java.util.List;
38 import java.util.logging.Logger;
39
40 /**
41 * Represents SCM change list.
42 *
43 * <p>
44 * Use the "index" view of this object to render the changeset detail page,
45 * and use the "digest" view of this object to render the summary page.
46 * For the change list at project level, see {@link SCM}.
47 *
48 * <p>
49 * {@link Iterator} is expected to return recent changes first.
50 *
51 * @author Kohsuke Kawaguchi
52 */
53 @ExportedBean(defaultVisibility=999)
54 public abstract class ChangeLogSet<T extends ChangeLogSet.Entry> implements Iterable<T> {
55
56 /**
57 * {@link AbstractBuild} whose change log this object represents.
58 */
59 public final AbstractBuild<?,?> build;
60
61 protected ChangeLogSet(AbstractBuild<?, ?> build) {
62 this.build = build;
63 }
64
65 /**
66 * Returns true if there's no change.
67 */
68 public abstract boolean isEmptySet();
69
70 /**
71 * All changes in this change set.
72 */
73 // method for the remote API.
74 @Exported
75 public final Object[] getItems() {
76 List<T> r = new ArrayList<T>();
77 for (T t : this)
78 r.add(t);
79 return r.toArray();
80 }
81
82 /**
83 * Optional identification of the kind of SCM being used.
84 * @return a short token, such as the SCM's main CLI executable name
85 * @since 1.284
86 */
87 @Exported
88 public String getKind() {
89 return null;
90 }
91
92 /**
93 * Constant instance that represents no changes.
94 */
95 public static ChangeLogSet<? extends ChangeLogSet.Entry> createEmpty(AbstractBuild build) {
96 return new EmptyChangeLogSet(build);
97 }
98
99 @ExportedBean(defaultVisibility=999)
100 public static abstract class Entry {
101 private ChangeLogSet parent;
102
103 public ChangeLogSet getParent() {
104 return parent;
105 }
106
107 /**
108 * Should be invoked before a {@link ChangeLogSet} is exposed to public.
109 */
110 protected void setParent(ChangeLogSet parent) {
111 this.parent = parent;
112 }
113
114 /**
115 * Returns a human readable display name of the commit number, revision number, and such thing
116 * that identifies this entry.
117 *
118 * <p>
119 * This method is primarily intended for visualization of the data.
120 *
121 * @return
122 * null if such a concept doesn't make sense for the implementation. For example,
123 * in CVS there's no single identifier for commits. Each file gets a different revision number.
124 * @since 1.405
125 */
126 @Exported
127 public String getCommitId() {
128 return null;
129 }
130
131 /**
132 * Returns the timestamp of this commit in the {@link Date#getTime()} format.
133 *
134 * <p>
135 * This method is primarily intended for visualization of the data.
136 *
137 * @return
138 * -1 if the implementation doesn't support it (for example, in CVS a commit
139 * spreads over time between multiple changes on multiple files, so there's no single timestamp.)
140 * @since 1.405
141 */
142 @Exported
143 public long getTimestamp() {
144 return -1;
145 }
146
147 /**
148 * Gets the "commit message".
149 *
150 * <p>
151 * The exact definition depends on the individual SCM implementation.
152 *
153 * @return
154 * Can be empty but never null.
155 */
156 @Exported
157 public abstract String getMsg();
158
159 /**
160 * The user who made this change.
161 *
162 * @return
163 * never null.
164 */
165 @Exported
166 public abstract User getAuthor();
167
168 /**
169 * Returns a set of paths in the workspace that was
170 * affected by this change.
171 *
172 * <p>
173 * Contains string like 'foo/bar/zot'. No leading/trailing '/',
174 * and separator must be normalized to '/'.
175 *
176 * @return never null.
177 */
178 @Exported
179 public abstract Collection<String> getAffectedPaths();
180
181 /**
182 * Returns a set of paths in the workspace that was
183 * affected by this change.
184 * <p>
185 * Noted: since this is a new interface, some of the SCMs may not have
186 * implemented this interface. The default implementation for this
187 * interface is throw UnsupportedOperationException
188 * <p>
189 * It doesn't throw NoSuchMethodException because I rather to throw a
190 * runtime exception
191 *
192 * @return AffectedFile never null.
193 * @since 1.309
194 */
195 public Collection<? extends AffectedFile> getAffectedFiles() {
196 String scm = "this SCM";
197 ChangeLogSet parent = getParent();
198 if ( null != parent ) {
199 String kind = parent.getKind();
200 if ( null != kind && kind.trim().length() > 0 ) scm = kind;
201 }
202 throw new UnsupportedOperationException("getAffectedFiles() is not implemented by " + scm);
203 }
204
205 /**
206 * Gets the text fully marked up by {@link ChangeLogAnnotator}.
207 */
208 public String getMsgAnnotated() {
209 MarkupText markup = new MarkupText(getMsg());
210 for (ChangeLogAnnotator a : ChangeLogAnnotator.all())
211 try {
212 a.annotate(parent.build,this,markup);
213 } catch(Exception e) {
214 LOGGER.fine("ChangeLogAnnotator " + a.toString() + " failed to annotate message '" + getMsg() + "'; " + e.getMessage());
215 }
216
217 return markup.toString(false);
218 }
219
220 /**
221 * Message escaped for HTML
222 */
223 public String getMsgEscaped() {
224 return Util.escape(getMsg());
225 }
226
227 static final Logger LOGGER = Logger.getLogger(ChangeLogSet.Entry.class.getName());
228 }
229
230 /**
231 * Represents a file change. Contains filename, edit type, etc.
232 *
233 * I checked the API names against some some major SCMs and most SCMs
234 * can adapt to this interface with very little changes
235 *
236 * @see ChangeLogSet.Entry#getAffectedFiles()
237 */
238 public interface AffectedFile {
239 /**
240 * The path in the workspace that was affected
241 * <p>
242 * Contains string like 'foo/bar/zot'. No leading/trailing '/',
243 * and separator must be normalized to '/'.
244 *
245 * @return never null.
246 */
247 String getPath();
248
249
250 /**
251 * Return whether the file is new/modified/deleted
252 */
253 EditType getEditType();
254 }
255 }
256