File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\core\src\main\java\hudson\matrix\Axis.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.matrix;
25
26 import hudson.DescriptorExtensionList;
27 import hudson.ExtensionPoint;
28 import hudson.RestrictedSince;
29 import hudson.Util;
30 import hudson.matrix.MatrixBuild.MatrixBuildExecution;
31 import hudson.model.AbstractDescribableImpl;
32 import jenkins.model.Jenkins;
33 import hudson.util.QuotedStringTokenizer;
34 import org.kohsuke.accmod.Restricted;
35 import org.kohsuke.accmod.restrictions.NoExternalUse;
36 import org.kohsuke.stapler.StaplerRequest;
37 import org.kohsuke.stapler.DataBoundConstructor;
38
39 import java.util.ArrayList;
40 import java.util.Collections;
41 import java.util.Enumeration;
42 import java.util.Iterator;
43 import java.util.List;
44 import java.util.Arrays;
45 import java.util.Map;
46
47 /**
48 * Configuration axis.
49 *
50 * <p>
51 * This class represents a single dimension of the configuration matrix.
52 * For example, the JAX-WS RI test configuration might include
53 * one axis "container={glassfish,tomcat,jetty}" and another axis
54 * "stax={sjsxp,woodstox}", and so on.
55 *
56 * @author Kohsuke Kawaguchi
57 */
58 public class Axis extends AbstractDescribableImpl<Axis> implements Comparable<Axis>, Iterable<String>, ExtensionPoint {
59 /**
60 * Name of this axis.
61 * Used as a variable name.
62 *
63 * @deprecated as of 1.373
64 * Use {@link #getName()}
65 */
66 public final String name;
67
68 /**
69 * Possible values for this axis.
70 *
71 * @deprecated as of 1.373
72 * Use {@link #getValues()}
73 */
74 @Restricted(NoExternalUse.class)
75 @RestrictedSince("1.463")
76 public final List<String> values;
77
78 public Axis(String name, List<String> values) {
79 this.name = name;
80 this.values = new ArrayList<String>(values);
81 if(values.isEmpty())
82 throw new IllegalArgumentException(); // bug in the code
83 }
84
85 public Axis(String name, String... values) {
86 this(name,Arrays.asList(values));
87 }
88
89 /**
90 * Used to build {@link Axis} from form.
91 *
92 * Axis with empty values need to be removed later.
93 */
94 @DataBoundConstructor
95 public Axis(String name, String valueString) {
96 this.name = name;
97 this.values = new ArrayList<String>(Arrays.asList(Util.tokenize(valueString)));
98 }
99
100 /**
101 * Returns true if this axis is a system-reserved axis
102 * that <strike>has</strike> used to have af special treatment.
103 *
104 * @deprecated as of 1.373
105 * System vs user difference are generalized into extension point.
106 */
107 public boolean isSystem() {
108 return false;
109 }
110
111 public Iterator<String> iterator() {
112 return getValues().iterator();
113 }
114
115 public int size() {
116 return getValues().size();
117 }
118
119 public String value(int index) {
120 return getValues().get(index);
121 }
122
123 /**
124 * The inverse of {@link #value(int)}.
125 */
126 public int indexOf(String value) {
127 return values.indexOf(value);
128 }
129
130 /**
131 * Axis is fully ordered so that we can convert between a list of axis
132 * and a string unambiguously.
133 */
134 public int compareTo(Axis that) {
135 return this.name.compareTo(that.name);
136 }
137
138 /**
139 * Name of this axis.
140 * Used as a variable name.
141 */
142 public String getName() {
143 return name;
144 }
145
146 /**
147 * Possible values for this axis.
148 */
149 public List<String> getValues() {
150 return Collections.unmodifiableList(values);
151 }
152
153 /**
154 * Called right at the beginning of {@link MatrixBuild} execution to allow {@link Axis} to update {@link #values}
155 * based on the current build.
156 *
157 * <p>
158 * Historically, axes values are considered static. They were assumed to reflect what the user has typed in,
159 * and their values are changed only when the project is reconfigured. So abstractions are built around this
160 * notion, and so for example {@link MatrixProject} has the current axes and their values, which it uses
161 * to render its UI.
162 *
163 * <p>
164 * So when the need was identified to change the values of axes per build, we decided that this be represented
165 * as a kind of project configuration update (where a project gets reconfigured every time a build runs), and
166 * this call back was added to allow {@link Axis} to update the next return value from the {@link #getValues()}
167 * (which is typically done by updating {@link #values}.)
168 *
169 * <p>
170 * While it is not strictly required, because of these historical reasons, UI will look better if
171 * Future calls to {@link Axis#getValues()} return the same values as what this method returns (until
172 * the next rebuild call).
173 *
174 * @param context
175 * The ongoing build. Never null.
176 * @return
177 * Never null. Returns the updated set of values.
178 * @since 1.471
179 */
180 public List<String> rebuild(MatrixBuildExecution context) {
181 return getValues();
182 }
183
184 @Override
185 public AxisDescriptor getDescriptor() {
186 return (AxisDescriptor)super.getDescriptor();
187 }
188
189 @Override
190 public String toString() {
191 return new StringBuilder().append(name).append("={").append(Util.join(values,",")).append('}').toString();
192 }
193
194 /**
195 * Used for generating the config UI.
196 * If the axis is big and occupies a lot of space, use newline for separator
197 * to display multi-line text.
198 */
199 public String getValueString() {
200 int len=0;
201 for (String value : values)
202 len += value.length();
203 char delim = len>30 ? '\n' : ' ';
204 // Build string connected with delimiter, quoting as needed
205 StringBuilder buf = new StringBuilder(len+values.size()*3);
206 for (String value : values)
207 buf.append(delim).append(QuotedStringTokenizer.quote(value,""));
208 return buf.substring(1);
209 }
210
211 /**
212 * Parses the submitted form (where possible values are
213 * presented as a list of checkboxes) and creates an axis
214 */
215 public static Axis parsePrefixed(StaplerRequest req, String name) {
216 List<String> values = new ArrayList<String>();
217 String prefix = name+'.';
218
219 Enumeration e = req.getParameterNames();
220 while (e.hasMoreElements()) {
221 String paramName = (String) e.nextElement();
222 if(paramName.startsWith(prefix))
223 values.add(paramName.substring(prefix.length()));
224 }
225 if(values.isEmpty())
226 return null;
227 return new Axis(name,values);
228 }
229
230 /**
231 * Previously we used to persist {@link Axis}, but now those are divided into subtypes.
232 * So upon deserialization, resolve to the proper type.
233 */
234 public Object readResolve() {
235 if (getClass()!=Axis.class) return this;
236
237 /*
238 This method is necessary only because earlier versions of Jenkins treated
239 axis names "label" and "jdk" differently,
240 plus Axis was a concrete class, and we need to be able to read that back.
241 So this measure is not needed for newly added Axes.
242 */
243 if (getName().equals("jdk"))
244 return new JDKAxis(getValues());
245 if (getName().equals("label"))
246 return new LabelAxis(getName(),getValues());
247 return new TextAxis(getName(),getValues());
248 }
249
250 /**
251 * Returns all the registered {@link AxisDescriptor}s.
252 */
253 public static DescriptorExtensionList<Axis,AxisDescriptor> all() {
254 return Jenkins.getInstance().<Axis,AxisDescriptor>getDescriptorList(Axis.class);
255 }
256
257 /**
258 * Converts the selected value (which is among {@link #values}) and adds that to the given map,
259 * which serves as the build variables.
260 */
261 public void addBuildVariable(String value, Map<String,String> map) {
262 map.put(name,value);
263 }
264 }
265