File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\core\src\main\java\hudson\slaves\ComputerListener.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.slaves;
25
26 import hudson.model.Computer;
27 import jenkins.model.Jenkins;
28 import hudson.model.TaskListener;
29 import hudson.model.Node;
30 import hudson.ExtensionPoint;
31 import hudson.Extension;
32 import hudson.ExtensionList;
33 import hudson.FilePath;
34 import hudson.remoting.Channel;
35 import hudson.AbortException;
36
37 import java.io.IOException;
38
39 /**
40 * Receives notifications about status changes of {@link Computer}s.
41 *
42 * @author Kohsuke Kawaguchi
43 * @since 1.246
44 */
45 public abstract class ComputerListener implements ExtensionPoint {
46 /**
47 * Called before a {@link ComputerLauncher} is asked to launch a connection with {@link Computer}.
48 *
49 * <p>
50 * This enables you to do some configurable checks to see if we
51 * want to bring this slave online or if there are considerations
52 * that would keep us from doing so.
53 *
54 * <p>
55 * Throwing {@link AbortException} would let you veto the launch operation. Other thrown exceptions
56 * will also have the same effect, but their stack trace will be dumped, so they are meant for error situation.
57 *
58 * @param c
59 * Computer that's being launched. Never null.
60 * @param taskListener
61 * Connected to the slave console log. Useful for reporting progress/errors on a lengthy operation.
62 * Never null.
63 * @throws AbortException
64 * Exceptions will be recorded to the listener, and
65 * the computer will not become online.
66 *
67 * @since 1.402
68 */
69 public void preLaunch(Computer c, TaskListener taskListener) throws IOException, InterruptedException {
70 }
71
72 /**
73 * Called when a slave attempted to connect via {@link ComputerLauncher} but it failed.
74 *
75 * @param c
76 * Computer that was trying to launch. Never null.
77 * @param taskListener
78 * Connected to the slave console log. Useful for reporting progress/errors on a lengthy operation.
79 * Never null.
80 *
81 * @since 1.402
82 */
83 public void onLaunchFailure(Computer c, TaskListener taskListener) throws IOException, InterruptedException {
84 }
85
86 /**
87 * Called before a {@link Computer} is marked online.
88 *
89 * <p>
90 * This enables you to do some work on all the slaves
91 * as they get connected. Unlike {@link #onOnline(Computer, TaskListener)},
92 * a failure to carry out this function normally will prevent
93 * a computer from marked as online.
94 *
95 * @param channel
96 * This is the channel object to talk to the slave.
97 * (This is the same object returned by {@link Computer#getChannel()} once
98 * it's connected.
99 * @param root
100 * The directory where this slave stores files.
101 * The same as {@link Node#getRootPath()}, except that method returns
102 * null until the slave is connected. So this parameter is passed explicitly instead.
103 * @param listener
104 * This is connected to the launch log of the computer.
105 * Since this method is called synchronously from the thread
106 * that launches a computer, if this method performs a time-consuming
107 * operation, this listener should be notified of the progress.
108 * This is also a good listener for reporting problems.
109 *
110 * @throws IOException
111 * Exceptions will be recorded to the listener, and
112 * the computer will not become online.
113 * @throws InterruptedException
114 * Exceptions will be recorded to the listener, and
115 * the computer will not become online.
116 *
117 * @since 1.295
118 * @see #onOnline(Computer, TaskListener)
119 */
120 public void preOnline(Computer c, Channel channel, FilePath root, TaskListener listener) throws IOException, InterruptedException {
121 }
122
123 /**
124 * Called right after a {@link Computer} comes online.
125 *
126 * @deprecated as of 1.292
127 * Use {@link #onOnline(Computer, TaskListener)}
128 */
129 public void onOnline(Computer c) {}
130
131 /**
132 * Called right after a {@link Computer} comes online.
133 *
134 * <p>
135 * This enables you to do some work on all the slaves
136 * as they get connected.
137 *
138 * <p>
139 * Starting Hudson 1.312, this method is also invoked for the master, not just for slaves.
140 *
141 * @param listener
142 * This is connected to the launch log of the computer.
143 * Since this method is called synchronously from the thread
144 * that launches a computer, if this method performs a time-consuming
145 * operation, this listener should be notified of the progress.
146 * This is also a good listener for reporting problems.
147 *
148 * @throws IOException
149 * Exceptions will be recorded to the listener. Note that
150 * throwing an exception doesn't put the computer offline.
151 * @throws InterruptedException
152 * Exceptions will be recorded to the listener. Note that
153 * throwing an exception doesn't put the computer offline.
154 *
155 * @see #preOnline(Computer, Channel, FilePath, TaskListener)
156 */
157 public void onOnline(Computer c, TaskListener listener) throws IOException, InterruptedException {
158 // compatibility
159 onOnline(c);
160 }
161
162 /**
163 * Called right after a {@link Computer} went offline.
164 */
165 public void onOffline(Computer c) {}
166
167 /**
168 * Indicates that the computer was marked as temporarily online by the administrator.
169 * This is the reverse operation of {@link #onTemporarilyOffline(Computer)}
170 *
171 * @since 1.452
172 */
173 public void onTemporarilyOnline(Computer c) {}
174 /**
175 * Indicates that the computer was marked as temporarily online by the administrator.
176 * This is the reverse operation of {@link #onTemporarilyOffline(Computer)}
177 *
178 * @since 1.452
179 */
180 public void onTemporarilyOffline(Computer c, OfflineCause cause) {}
181
182 /**
183 * Called when configuration of the node was changed, a node is added/removed, etc.
184 *
185 * <p>
186 * This callback is to signal when there's any change to the list of slaves registered to the system,
187 * including addition, removal, changing of the setting, and so on.
188 *
189 * @since 1.377
190 */
191 public void onConfigurationChange() {}
192
193 /**
194 * Registers this {@link ComputerListener} so that it will start receiving events.
195 *
196 * @deprecated as of 1.286
197 * put {@link Extension} on your class to have it auto-registered.
198 */
199 public final void register() {
200 all().add(this);
201 }
202
203 /**
204 * Unregisters this {@link ComputerListener} so that it will never receive further events.
205 *
206 * <p>
207 * Unless {@link ComputerListener} is unregistered, it will never be a subject of GC.
208 */
209 public final boolean unregister() {
210 return all().remove(this);
211 }
212
213 /**
214 * All the registered {@link ComputerListener}s.
215 */
216 public static ExtensionList<ComputerListener> all() {
217 return Jenkins.getInstance().getExtensionList(ComputerListener.class);
218 }
219 }
220