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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2010, Sun Microsystems, Inc., Tom Huybrechts
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
25 package hudson.tools;
26
27 import hudson.DescriptorExtensionList;
28 import hudson.EnvVars;
29 import hudson.Extension;
30 import hudson.ExtensionPoint;
31 import hudson.diagnosis.OldDataMonitor;
32 import hudson.model.*;
33 import hudson.slaves.NodeSpecific;
34 import hudson.util.DescribableList;
35 import hudson.util.StreamTaskListener;
36 import hudson.util.XStream2;
37
38 import java.io.Serializable;
39 import java.io.IOException;
40 import java.util.List;
41
42 import com.thoughtworks.xstream.annotations.XStreamSerializable;
43 import com.thoughtworks.xstream.converters.UnmarshallingContext;
44 import jenkins.model.Jenkins;
45
46 /**
47 * Formalization of a tool installed in nodes used for builds.
48 * (Examples include things like JDKs, Ants, Mavens, and Groovys.)
49 *
50 * <p>
51 * You can define such a concept in your plugin entirely on your own, without extending from
52 * this class, but choosing this class as a base class has several benefits:
53 *
54 * <ul>
55 * <li>Hudson allows admins to specify different locations for tools on some slaves.
56 * For example, JDK on the master might be on /usr/local/java but on a Windows slave
57 * it could be at c:\Program Files\Java
58 * <li>Hudson can verify the existence of tools and provide warnings and diagnostics for
59 * admins. (TBD)
60 * <li>Hudson can perform automatic installations for users. (TBD)
61 * </ul>
62 *
63 * <p>
64 * Implementations of this class are strongly encouraged to also implement {@link NodeSpecific}
65 * (by using {@link #translateFor(Node, TaskListener)}) and
66 * {@link EnvironmentSpecific} (by using {@link EnvVars#expand(String)}.)
67 * Callers such as build steps can then use {@link #translate(AbstractBuild,TaskListener)}
68 * and cast to the desired {@link ToolInstallation} subtype, or just call
69 * {@link NodeSpecific#forNode} and {@link EnvironmentSpecific#forEnvironment} directly.
70 *
71 * <p>
72 * To contribute an extension point, put {@link Extension} on your {@link ToolDescriptor} class.
73 *
74 * @author huybrechts
75 * @since 1.286
76 */
77 public abstract class ToolInstallation extends AbstractDescribableImpl<ToolInstallation> implements Serializable, ExtensionPoint {
78 private final String name;
79 private /*almost final*/ String home;
80
81 /**
82 * {@link ToolProperty}s that are associated with this tool.
83 */
84 @XStreamSerializable
85 private transient /*almost final*/ DescribableList<ToolProperty<?>,ToolPropertyDescriptor> properties
86 = new DescribableList<ToolProperty<?>,ToolPropertyDescriptor>(Saveable.NOOP);
87
88 /**
89 * @deprecated
90 * as of 1.302. Use {@link #ToolInstallation(String, String, List)}
91 */
92 public ToolInstallation(String name, String home) {
93 this.name = name;
94 this.home = home;
95 }
96
97 public ToolInstallation(String name, String home, List<? extends ToolProperty<?>> properties) {
98 this.name = name;
99 this.home = home;
100 if(properties!=null) {
101 try {
102 this.properties.replaceBy(properties);
103 for (ToolProperty<?> p : properties)
104 _setTool(p,this);
105 } catch (IOException e) {
106 throw new AssertionError(e); // no Saveable, so can't happen
107 }
108 }
109 }
110
111 // helper function necessary to avoid a warning
112 private <T extends ToolInstallation> void _setTool(ToolProperty<T> prop, ToolInstallation t) {
113 prop.setTool(prop.type().cast(t));
114 }
115
116 /**
117 * Gets the human readable name that identifies this tool among other {@link ToolInstallation}s of the same kind.
118 */
119 public String getName() {
120 return name;
121 }
122
123 /**
124 * Gets the home directory of this tool.
125 *
126 * The path can be in Unix format as well as in Windows format.
127 * Must be absolute.
128 */
129 public String getHome() {
130 return home;
131 }
132
133 /**
134 * Expose any environment variables that this tool installation wants the build to see.
135 *
136 * <p>
137 * To add entry to PATH, do {@code envVars.put("PATH+XYZ",path)} where 'XYZ' is something unique.
138 * Variable names of the form 'A+B' is interpreted as adding the value to the existing PATH.
139 *
140 * @since 1.460
141 */
142 public void buildEnvVars(EnvVars env) {
143 }
144
145 public DescribableList<ToolProperty<?>,ToolPropertyDescriptor> getProperties() {
146 assert properties!=null;
147 return properties;
148 }
149
150 /**
151 * Performs a necessary variable/environment/context expansion.
152 *
153 * @param node
154 * Node that this tool is used in.
155 * @param envs
156 * Set of environment variables to expand any references.
157 * @param listener
158 * Any lengthy operation (such as auto-installation) will report its progress here.
159 * @return
160 * {@link ToolInstallation} object that is fully specialized.
161 * @see NodeSpecific
162 * @see EnvironmentSpecific
163 * @since 1.460
164 */
165 public ToolInstallation translate(Node node, EnvVars envs, TaskListener listener) throws IOException, InterruptedException {
166 ToolInstallation t = this;
167 if (t instanceof NodeSpecific) {
168 NodeSpecific n = (NodeSpecific) t;
169 t = (ToolInstallation)n.forNode(node,listener);
170 }
171 if (t instanceof EnvironmentSpecific) {
172 EnvironmentSpecific e = (EnvironmentSpecific) t;
173 t = (ToolInstallation)e.forEnvironment(envs);
174 }
175 return t;
176 }
177
178 /**
179 * Convenient version of {@link #translate(Node, EnvVars, TaskListener)} that just takes a build object in progress.
180 * @since 1.460
181 */
182 public ToolInstallation translate(AbstractBuild<?,?> buildInProgress, TaskListener listener) throws IOException, InterruptedException {
183 assert buildInProgress.isBuilding();
184 return translate(buildInProgress.getBuiltOn(),buildInProgress.getEnvironment(listener),listener);
185 }
186
187 /**
188 * Finds a tool on a node.
189 * Checks if the location of the tool is overridden for the given node, and if so,
190 * return the node-specific home directory.
191 * Also checks available {@link ToolLocationTranslator}s.
192 * Otherwise returns {@code installation.getHome()}.
193 *
194 * <p>
195 * This is the core logic behind {@link NodeSpecific#forNode(Node, TaskListener)} for {@link ToolInstallation},
196 * and meant to be used by the {@code forNode} implementations.
197 *
198 * @return
199 * never null.
200 */
201 @SuppressWarnings("deprecation")
202 protected String translateFor(Node node, TaskListener log) throws IOException, InterruptedException {
203 return ToolLocationNodeProperty.getToolHome(node, this, log);
204 }
205
206 /**
207 * Invoked by XStream when this object is read into memory.
208 */
209 protected Object readResolve() {
210 if(properties==null)
211 properties = new DescribableList<ToolProperty<?>,ToolPropertyDescriptor>(Saveable.NOOP);
212 for (ToolProperty<?> p : properties)
213 _setTool(p, this);
214 return this;
215 }
216
217 /**
218 * Subclasses can extend this for data migration from old field storing home directory.
219 */
220 protected static abstract class ToolConverter extends XStream2.PassthruConverter<ToolInstallation> {
221 public ToolConverter(XStream2 xstream) { super(xstream); }
222 protected void callback(ToolInstallation obj, UnmarshallingContext context) {
223 String s;
224 if (obj.home == null && (s = oldHomeField(obj)) != null) {
225 obj.home = s;
226 OldDataMonitor.report(context, "1.286");
227 }
228 }
229 protected abstract String oldHomeField(ToolInstallation obj);
230 }
231
232 /**
233 * Returns all the registered {@link ToolDescriptor}s.
234 */
235 public static DescriptorExtensionList<ToolInstallation,ToolDescriptor<?>> all() {
236 // use getDescriptorList and not getExtensionList to pick up legacy instances
237 return Jenkins.getInstance().<ToolInstallation,ToolDescriptor<?>>getDescriptorList(ToolInstallation.class);
238 }
239
240 private static final long serialVersionUID = 1L;
241 }
242