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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2010, Sun Microsystems, Inc.
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.console;
25
26 import hudson.MarkupText;
27
28 import java.io.Serializable;
29 import java.util.ArrayList;
30 import java.util.Collection;
31 import java.util.List;
32 import java.util.ListIterator;
33
34 /**
35 * Annotates one line of console output.
36 *
37 * <p>
38 * In Hudson, console output annotation is done line by line, and
39 * we model this as a state machine &mdash;
40 * the code encapsulates some state, and it uses that to annotate one line (and possibly update the state.)
41 *
42 * <p>
43 * A {@link ConsoleAnnotator} instance encapsulates this state, and the {@link #annotate(Object, MarkupText)}
44 * method is used to annotate the next line based on the current state. The method returns another
45 * {@link ConsoleAnnotator} instance that represents the altered state for annotating the next line.
46 *
47 * <p>
48 * {@link ConsoleAnnotator}s are run when a browser requests console output, and the above-mentioned chain
49 * invocation is done for each client request separately. Therefore, logically you can think of this process as:
50 *
51 * <pre>
52 * ConsoleAnnotator ca = ...;
53 * ca.annotate(context,line1).annotate(context,line2)...
54 * </pre>
55 *
56 * <p>
57 * Because of a browser can request console output incrementally, in addition to above a console annotator
58 * can be serialized at any point and deserialized back later to continue annotation where it left off.
59 *
60 * <p>
61 * {@link ConsoleAnnotator} instances can be created in a few different ways. See {@link ConsoleNote}
62 * and {@link ConsoleAnnotatorFactory}.
63 *
64 * @author Kohsuke Kawaguchi
65 * @see ConsoleAnnotatorFactory
66 * @see ConsoleNote
67 * @since 1.349
68 */
69 public abstract class ConsoleAnnotator<T> implements Serializable {
70 /**
71 * Annotates one line.
72 *
73 * @param context
74 * The object that owns the console output. Never null.
75 * @param text
76 * Contains a single line of console output, and defines convenient methods to add markup.
77 * The callee should put markup into this object. Never null.
78 * @return
79 * The {@link ConsoleAnnotator} object that will annotate the next line of the console output.
80 * To indicate that you are not interested in the following lines, return null.
81 */
82 public abstract ConsoleAnnotator annotate(T context, MarkupText text );
83
84 /**
85 * Cast operation that restricts T.
86 */
87 public static <T> ConsoleAnnotator<T> cast(ConsoleAnnotator<? super T> a) {
88 return (ConsoleAnnotator)a;
89 }
90
91 /**
92 * Bundles all the given {@link ConsoleAnnotator} into a single annotator.
93 */
94 public static <T> ConsoleAnnotator<T> combine(Collection<? extends ConsoleAnnotator<? super T>> all) {
95 switch (all.size()) {
96 case 0: return null; // none
97 case 1: return cast(all.iterator().next()); // just one
98 }
99
100 class Aggregator extends ConsoleAnnotator<T> {
101 List<ConsoleAnnotator<T>> list;
102
103 Aggregator(Collection list) {
104 this.list = new ArrayList<ConsoleAnnotator<T>>(list);
105 }
106
107 public ConsoleAnnotator annotate(T context, MarkupText text) {
108 ListIterator<ConsoleAnnotator<T>> itr = list.listIterator();
109 while (itr.hasNext()) {
110 ConsoleAnnotator a = itr.next();
111 ConsoleAnnotator b = a.annotate(context,text);
112 if (a!=b) {
113 if (b==null) itr.remove();
114 else itr.set(b);
115 }
116 }
117
118 switch (list.size()) {
119 case 0: return null; // no more annotator left
120 case 1: return list.get(0); // no point in aggregating
121 default: return this;
122 }
123 }
124 }
125 return new Aggregator(all);
126 }
127
128 /**
129 * Returns the all {@link ConsoleAnnotator}s for the given context type aggregated into a single
130 * annotator.
131 */
132 public static <T> ConsoleAnnotator<T> initial(T context) {
133 return combine(_for(context));
134 }
135
136 /**
137 * List all the console annotators that can work for the specified context type.
138 */
139 public static <T> List<ConsoleAnnotator<T>> _for(T context) {
140 List<ConsoleAnnotator<T>> r = new ArrayList<ConsoleAnnotator<T>>();
141 for (ConsoleAnnotatorFactory f : ConsoleAnnotatorFactory.all()) {
142 if (f.type().isInstance(context)) {
143 ConsoleAnnotator ca = f.newInstance(context);
144 if (ca!=null)
145 r.add(ca);
146 }
147 }
148 return r;
149 }
150
151 private static final long serialVersionUID = 1L;
152 }
153