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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2009, 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 package hudson.slaves;
25
26 import hudson.EnvVars;
27 import hudson.ExtensionPoint;
28 import hudson.FilePath;
29 import hudson.Launcher;
30 import hudson.DescriptorExtensionList;
31 import hudson.model.Descriptor.FormException;
32 import hudson.model.Queue.BuildableItem;
33 import hudson.model.ReconfigurableDescribable;
34 import hudson.model.TaskListener;
35 import hudson.model.queue.CauseOfBlockage;
36 import hudson.scm.SCM;
37 import hudson.model.AbstractBuild;
38 import hudson.model.BuildListener;
39 import hudson.model.Environment;
40 import jenkins.model.Jenkins;
41 import hudson.model.Node;
42 import hudson.model.Queue.Task;
43 import net.sf.json.JSONObject;
44 import org.kohsuke.stapler.StaplerRequest;
45
46 import java.io.File;
47 import java.io.IOException;
48 import java.util.List;
49 import java.util.Map;
50
51 /**
52 * Extensible property of {@link Node}.
53 *
54 * <p>
55 * Plugins can contribute this extension point to add additional data or UI actions to {@link Node}.
56 * {@link NodeProperty}s show up in the configuration screen of a node, and they are persisted with the {@link Node} object.
57 *
58 *
59 * <h2>Views</h2>
60 * <dl>
61 * <dt>config.jelly</dt>
62 * <dd>Added to the configuration page of the node.
63 * <dt>global.jelly</dt>
64 * <dd>Added to the system configuration page.
65 * <dt>summary.jelly (optional)</dt>
66 * <dd>Added to the index page of the {@link hudson.model.Computer} associated with the node
67 * </dl>
68 *
69 * @param <N>
70 * {@link NodeProperty} can choose to only work with a certain subtype of {@link Node}, and this 'N'
71 * represents that type. Also see {@link NodePropertyDescriptor#isApplicable(Class)}.
72 *
73 * @since 1.286
74 */
75 public abstract class NodeProperty<N extends Node> implements ReconfigurableDescribable<NodeProperty<?>>, ExtensionPoint {
76
77 protected transient N node;
78
79 protected void setNode(N node) { this.node = node; }
80
81 public NodePropertyDescriptor getDescriptor() {
82 return (NodePropertyDescriptor) Jenkins.getInstance().getDescriptorOrDie(getClass());
83 }
84
85 /**
86 * Called by the {@link Node} to help determine whether or not it should
87 * take the given task. Individual properties can return a non-null value
88 * here if there is some reason the given task should not be run on its
89 * associated node. By default, this method returns <code>null</code>.
90 *
91 * @since 1.360
92 * @deprecated as of 1.413
93 * Use {@link #canTake(BuildableItem)}
94 */
95 public CauseOfBlockage canTake(Task task) {
96 return null;
97 }
98
99 /**
100 * Called by the {@link Node} to help determine whether or not it should
101 * take the given task. Individual properties can return a non-null value
102 * here if there is some reason the given task should not be run on its
103 * associated node. By default, this method returns <code>null</code>.
104 *
105 * @since 1.413
106 */
107 public CauseOfBlockage canTake(BuildableItem item) {
108 return canTake(item.task); // backward compatible behaviour
109 }
110
111 /**
112 * Runs before the {@link SCM#checkout(AbstractBuild, Launcher, FilePath, BuildListener, File)} runs, and performs a set up.
113 * Can contribute additional properties to the environment.
114 *
115 * @param build
116 * The build in progress for which an {@link Environment} object is created.
117 * Never null.
118 * @param launcher
119 * This launcher can be used to launch processes for this build.
120 * If the build runs remotely, launcher will also run a job on that remote machine.
121 * Never null.
122 * @param listener
123 * Can be used to send any message.
124 * @return
125 * non-null if the build can continue, null if there was an error
126 * and the build needs to be aborted.
127 * @throws IOException
128 * terminates the build abnormally. Hudson will handle the exception
129 * and reports a nice error message.
130 */
131 public Environment setUp( AbstractBuild build, Launcher launcher, BuildListener listener ) throws IOException, InterruptedException {
132 return new Environment() {};
133 }
134
135 /**
136 * Creates environment variable override for launching child processes in this node.
137 *
138 * <p>
139 * Whereas {@link #setUp(AbstractBuild, Launcher, BuildListener)} is used specifically for
140 * executing builds, this method is used for other process launch activities that happens
141 * outside the context of a build, such as polling, one time action (tagging, deployment, etc.)
142 *
143 * <p>
144 * Starting 1.489, this method and {@link #setUp(AbstractBuild, Launcher, BuildListener)} are
145 * layered properly. That is, for launching processes for a build, this method
146 * is called first and then {@link Environment#buildEnvVars(Map)} will be added on top.
147 * This allows implementations to put node-scoped environment variables here, then
148 * build scoped variables to {@link #setUp(AbstractBuild, Launcher, BuildListener)}.
149 *
150 * <p>
151 * Unfortunately, Jenkins core earlier than 1.488 only calls {@link #setUp(AbstractBuild, Launcher, BuildListener)},
152 * so if the backward compatibility with these earlier versions is important, implementations
153 * should invoke this method from {@link Environment#buildEnvVars(Map)}.
154 *
155 * @param env
156 * Manipulate this variable (normally by adding more entries.)
157 * Note that this is an override, so it doesn't contain environment variables that are
158 * currently set for the slave process itself.
159 * @param listener
160 * Can be used to send messages.
161 *
162 * @since 1.489
163 */
164 public void buildEnvVars(EnvVars env, TaskListener listener) throws IOException,InterruptedException {
165 // default is no-op
166 }
167
168 public NodeProperty<?> reconfigure(StaplerRequest req, JSONObject form) throws FormException {
169 return form==null ? null : getDescriptor().newInstance(req, form);
170 }
171
172 /**
173 * Lists up all the registered {@link NodeDescriptor}s in the system.
174 */
175 public static DescriptorExtensionList<NodeProperty<?>,NodePropertyDescriptor> all() {
176 return (DescriptorExtensionList) Jenkins.getInstance().getDescriptorList(NodeProperty.class);
177 }
178
179 /**
180 * List up all {@link NodePropertyDescriptor}s that are applicable for the
181 * given project.
182 */
183 public static List<NodePropertyDescriptor> for_(Node node) {
184 return NodePropertyDescriptor.for_(all(),node);
185 }
186 }
187