File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\core\src\main\java\hudson\scm\ChangeLogAnnotator.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.ExtensionPoint;
27 import hudson.MarkupText;
28 import hudson.ExtensionListView;
29 import hudson.Extension;
30 import hudson.ExtensionList;
31 import hudson.util.CopyOnWriteList;
32 import hudson.scm.ChangeLogSet.Entry;
33 import hudson.model.AbstractBuild;
34 import jenkins.model.Jenkins;
35
36 import java.util.logging.Logger;
37
38 /**
39 * Performs mark up on changelog messages to be displayed.
40 *
41 * <p>
42 * SCM changelog messages are usually plain text, but when we display that in Hudson,
43 * it is often nice to be able to put mark up on the text (for example to link to
44 * external issue tracking system.)
45 *
46 * <p>
47 * Plugins that are interested in doing so may extend this class and put {@link Extension} on it.
48 * When multiple annotators are registered, their results will be combined.
49 *
50 * @author Kohsuke Kawaguchi
51 * @since 1.70
52 */
53 public abstract class ChangeLogAnnotator implements ExtensionPoint {
54 /**
55 * Called by Hudson to allow markups to be added to the changelog text.
56 *
57 * <p>
58 * This method is invoked each time a page is rendered, so implementations
59 * of this method should not take too long to execute. Also note that
60 * this method may be invoked concurrently by multiple threads.
61 *
62 * <p>
63 * If there's any error during the processing, it should be recorded in
64 * {@link Logger} and the method should return normally.
65 *
66 * @param build
67 * Build that owns this changelog. From here you can access broader contextual
68 * information, like the project, or it settings. Never null.
69 * @param change
70 * The changelog entry for which this method is adding markup.
71 * Never null.
72 * @param text
73 * The text and markups. Implementation of this method is expected to
74 * add additional annotations into this object. If other annotators
75 * are registered, the object may already contain some markups when this
76 * method is invoked. Never null. {@link MarkupText#getText()} on this instance
77 * will return the same string as {@link Entry#getMsgEscaped()}.
78 */
79 public abstract void annotate(AbstractBuild<?,?> build, Entry change, MarkupText text );
80
81 /**
82 * Registers this annotator, so that Hudson starts using this object
83 * for adding markup.
84 *
85 * @deprecated as of 1.286
86 * Prefer automatic registration via {@link Extension}
87 */
88 public final void register() {
89 all().add(this);
90 }
91
92 /**
93 * Unregisters this annotator, so that Hudson stops using this object.
94 */
95 public final boolean unregister() {
96 return all().remove(this);
97 }
98
99 /**
100 * All registered {@link ChangeLogAnnotator}s.
101 *
102 * @deprecated as of 1.286
103 * Use {@link #all()} for read access, and {@link Extension} for registration.
104 */
105 public static final CopyOnWriteList<ChangeLogAnnotator> annotators = ExtensionListView.createCopyOnWriteList(ChangeLogAnnotator.class);
106
107 /**
108 * Returns all the registered {@link ChangeLogAnnotator} descriptors.
109 */
110 public static ExtensionList<ChangeLogAnnotator> all() {
111 return Jenkins.getInstance().getExtensionList(ChangeLogAnnotator.class);
112 }
113 }
114