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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi, Stephen Connolly
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.slaves;
25
26 import hudson.ExtensionPoint;
27 import hudson.Extension;
28 import hudson.model.*;
29 import hudson.remoting.Channel;
30 import hudson.util.DescriptorList;
31 import hudson.util.StreamTaskListener;
32
33 import java.io.*;
34 import java.util.regex.Matcher;
35 import java.util.regex.Pattern;
36 import org.apache.tools.ant.util.DeweyDecimal;
37
38 /**
39 * Extension point to allow control over how {@link Computer}s are "launched",
40 * meaning how they get connected to their slave agent program.
41 *
42 * <h2>Associated View</h2>
43 * <dl>
44 * <dt>main.jelly</dt>
45 * <dd>
46 * This page will be rendered into the top page of the computer (/computer/NAME/)
47 * Useful for showing launch related commands and status reports.
48 * </dl>
49 *
50 * @author Stephen Connolly
51 * @since 24-Apr-2008 22:12:35
52 * @see ComputerConnector
53 */
54 public abstract class ComputerLauncher extends AbstractDescribableImpl<ComputerLauncher> implements ExtensionPoint {
55 /**
56 * Returns true if this {@link ComputerLauncher} supports
57 * programatic launch of the slave agent in the target {@link Computer}.
58 */
59 public boolean isLaunchSupported() {
60 return true;
61 }
62
63 /**
64 * Launches the slave agent for the given {@link Computer}.
65 *
66 * <p>
67 * If the slave agent is launched successfully, {@link SlaveComputer#setChannel(InputStream, OutputStream, TaskListener, Channel.Listener)}
68 * should be invoked in the end to notify Hudson of the established connection.
69 * The operation could also fail, in which case there's no need to make any callback notification,
70 * (except to notify the user of the failure through {@link StreamTaskListener}.)
71 * Also note that the normal return of this method call does not necessarily signify a successful launch.
72 * If someone programmatically calls this method and wants to find out if the launch was a success,
73 * use {@link SlaveComputer#isOnline()} at the end.
74 *
75 * <p>
76 * This method must operate synchronously. Asynchrony is provided by {@link Computer#connect(boolean)} and
77 * its correct operation depends on this.
78 *
79 * @param listener
80 * The progress of the launch, as well as any error, should be sent to this listener.
81 *
82 * @throws IOException
83 * if the method throws an {@link IOException} or {@link InterruptedException}, the launch was considered
84 * a failure and the stack trace is reported into the listener. This handling is just so that the implementation
85 * of this method doesn't have to dilligently catch those exceptions.
86 */
87 public void launch(SlaveComputer computer, TaskListener listener) throws IOException , InterruptedException {
88 // to remain compatible with the legacy implementation that overrides the old signature
89 launch(computer,cast(listener));
90 }
91
92 /**
93 * @deprecated as of 1.304
94 * Use {@link #launch(SlaveComputer, TaskListener)}
95 */
96 public void launch(SlaveComputer computer, StreamTaskListener listener) throws IOException , InterruptedException {
97 throw new UnsupportedOperationException(getClass()+" must implement the launch method");
98 }
99
100 /**
101 * Allows the {@link ComputerLauncher} to tidy-up after a disconnect.
102 *
103 * <p>
104 * This method is invoked after the {@link Channel} to this computer is terminated.
105 *
106 * <p>
107 * Disconnect operation is performed asynchronously, so there's no guarantee
108 * that the corresponding {@link SlaveComputer} exists for the duration of the
109 * operation.
110 */
111 public void afterDisconnect(SlaveComputer computer, TaskListener listener) {
112 // to remain compatible with the legacy implementation that overrides the old signature
113 afterDisconnect(computer,cast(listener));
114 }
115
116 /**
117 * @deprecated as of 1.304
118 * Use {@link #afterDisconnect(SlaveComputer, TaskListener)}
119 */
120 public void afterDisconnect(SlaveComputer computer, StreamTaskListener listener) {
121 }
122
123 /**
124 * Allows the {@link ComputerLauncher} to prepare for a disconnect.
125 *
126 * <p>
127 * This method is invoked before the {@link Channel} to this computer is terminated,
128 * thus the channel is still accessible from {@link SlaveComputer#getChannel()}.
129 * If the channel is terminated unexpectedly, this method will not be invoked,
130 * as the channel is already gone.
131 *
132 * <p>
133 * Disconnect operation is performed asynchronously, so there's no guarantee
134 * that the corresponding {@link SlaveComputer} exists for the duration of the
135 * operation.
136 */
137 public void beforeDisconnect(SlaveComputer computer, TaskListener listener) {
138 // to remain compatible with the legacy implementation that overrides the old signature
139 beforeDisconnect(computer,cast(listener));
140 }
141
142 /**
143 * @deprecated as of 1.304
144 * Use {@link #beforeDisconnect(SlaveComputer, TaskListener)}
145 */
146 public void beforeDisconnect(SlaveComputer computer, StreamTaskListener listener) {
147 }
148
149 private StreamTaskListener cast(TaskListener listener) {
150 if (listener instanceof StreamTaskListener)
151 return (StreamTaskListener) listener;
152 return new StreamTaskListener(listener.getLogger());
153 }
154
155 /**
156 * All registered {@link ComputerLauncher} implementations.
157 *
158 * @deprecated as of 1.281
159 * Use {@link Extension} for registration, and use
160 * {@link jenkins.model.Jenkins#getDescriptorList(Class)} for read access.
161 */
162 public static final DescriptorList<ComputerLauncher> LIST = new DescriptorList<ComputerLauncher>(ComputerLauncher.class);
163
164 /**
165 * Given the output of "java -version" in <code>r</code>, determine if this
166 * version of Java is supported, or throw {@link IOException}.
167 *
168 * @param logger
169 * where to log the output
170 * @param javaCommand
171 * the command executed, used for logging
172 * @param r
173 * the output of "java -version"
174 */
175 protected static void checkJavaVersion(final PrintStream logger, String javaCommand,
176 final BufferedReader r)
177 throws IOException {
178 String line;
179 Pattern p = Pattern.compile("(?i)(?:java|openjdk) version \"([0-9.]+).*\"");
180 while (null != (line = r.readLine())) {
181 Matcher m = p.matcher(line);
182 if (m.matches()) {
183 final String versionStr = m.group(1);
184 logger.println(Messages.ComputerLauncher_JavaVersionResult(javaCommand, versionStr));
185 try {
186 if (new DeweyDecimal(versionStr).isLessThan(new DeweyDecimal("1.5"))) {
187 throw new IOException(Messages
188 .ComputerLauncher_NoJavaFound(line));
189 }
190 } catch (NumberFormatException x) {
191 throw new IOException(Messages.ComputerLauncher_NoJavaFound(line));
192 }
193 return;
194 }
195 }
196 logger.println(Messages.ComputerLauncher_UknownJavaVersion(javaCommand));
197 throw new IOException(Messages.ComputerLauncher_UknownJavaVersion(javaCommand));
198 }
199 }
200