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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2009-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
25 package hudson.tools;
26
27 import hudson.ExtensionPoint;
28 import hudson.FilePath;
29 import hudson.Util;
30 import hudson.model.Describable;
31 import jenkins.model.Jenkins;
32 import hudson.model.Label;
33 import hudson.model.Node;
34 import hudson.model.TaskListener;
35
36 import java.io.File;
37 import java.io.IOException;
38
39 import org.kohsuke.stapler.DataBoundConstructor;
40
41 /**
42 * An object which can ensure that a generic {@link ToolInstallation} in fact exists on a node.
43 *
44 * The subclass should have a {@link ToolInstallerDescriptor}.
45 * A {@code config.jelly} should be provided to customize specific fields;
46 * {@code <t:label xmlns:t="/hudson/tools"/>} to customize {@code label}.
47 * @see <a href="http://wiki.jenkins-ci.org/display/JENKINS/Tool+Auto-Installation">Tool Auto-Installation</a>
48 * @since 1.305
49 */
50 public abstract class ToolInstaller implements Describable<ToolInstaller>, ExtensionPoint {
51
52 private final String label;
53
54 protected transient ToolInstallation tool;
55
56 /**
57 * Subclasses should pass these parameters in using {@link DataBoundConstructor}.
58 */
59 protected ToolInstaller(String label) {
60 this.label = Util.fixEmptyAndTrim(label);
61 }
62
63 /**
64 * Called during the initialization to tell {@link ToolInstaller} what {@link ToolInstallation}
65 * it is configured against.
66 */
67 protected void setTool(ToolInstallation t) {
68 this.tool = t;
69 }
70
71 /**
72 * Label to limit which nodes this installation can be performed on.
73 * Can be null to not impose a limit.
74 */
75 public final String getLabel() {
76 return label;
77 }
78
79 /**
80 * Checks whether this installer can be applied to a given node.
81 * (By default, just checks the label.)
82 */
83 public boolean appliesTo(Node node) {
84 Label l = Jenkins.getInstance().getLabel(label);
85 return l == null || l.contains(node);
86 }
87
88 /**
89 * Ensure that the configured tool is really installed.
90 * If it is already installed, do nothing.
91 * Called only if {@link #appliesTo(Node)} are true.
92 * @param tool the tool being installed
93 * @param node the computer on which to install the tool
94 * @param log any status messages produced by the installation go here
95 * @return the (directory) path at which the tool can be found,
96 * typically coming from {@link #preferredLocation}
97 * @throws IOException if installation fails
98 * @throws InterruptedException if communication with a slave is interrupted
99 */
100 public abstract FilePath performInstallation(ToolInstallation tool, Node node, TaskListener log) throws IOException, InterruptedException;
101
102 /**
103 * Convenience method to find a location to install a tool.
104 * @param tool the tool being installed
105 * @param node the computer on which to install the tool
106 * @return {@link ToolInstallation#getHome} if specified, else a path within the local
107 * Jenkins work area named according to {@link ToolInstallation#getName}
108 * @since 1.310
109 */
110 protected final FilePath preferredLocation(ToolInstallation tool, Node node) {
111 if (node == null) {
112 throw new IllegalArgumentException("must pass non-null node");
113 }
114 String home = Util.fixEmptyAndTrim(tool.getHome());
115 if (home == null) {
116 home = sanitize(tool.getDescriptor().getId()) + File.separatorChar + sanitize(tool.getName());
117 }
118 FilePath root = node.getRootPath();
119 if (root == null) {
120 throw new IllegalArgumentException("Node " + node.getDisplayName() + " seems to be offline");
121 }
122 return root.child("tools").child(home);
123 }
124
125 private String sanitize(String s) {
126 return s != null ? s.replaceAll("[^A-Za-z0-9_.-]+", "_") : null;
127 }
128
129 public ToolInstallerDescriptor<?> getDescriptor() {
130 return (ToolInstallerDescriptor) Jenkins.getInstance().getDescriptorOrDie(getClass());
131 }
132 }
133