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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2010, 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.model;
25
26 import hudson.ExtensionPoint;
27 import hudson.Launcher;
28 import hudson.Plugin;
29 import hudson.model.Descriptor.FormException;
30 import hudson.model.queue.SubTask;
31 import hudson.tasks.BuildStep;
32 import hudson.tasks.Builder;
33 import hudson.tasks.Publisher;
34 import hudson.tasks.BuildStepMonitor;
35
36 import java.io.IOException;
37 import java.util.Collection;
38 import java.util.Collections;
39
40 import jenkins.model.Jenkins;
41 import net.sf.json.JSONObject;
42 import org.kohsuke.stapler.StaplerRequest;
43 import org.kohsuke.stapler.export.ExportedBean;
44
45 /**
46 * Extensible property of {@link Job}.
47 *
48 * <p>
49 * {@link Plugin}s can extend this to define custom properties
50 * for {@link Job}s. {@link JobProperty}s show up in the user
51 * configuration screen, and they are persisted with the job object.
52 *
53 * <p>
54 * Configuration screen should be defined in <tt>config.jelly</tt>.
55 * Within this page, the {@link JobProperty} instance is available
56 * as <tt>instance</tt> variable (while <tt>it</tt> refers to {@link Job}.
57 *
58 * <p>
59 * Starting 1.150, {@link JobProperty} implements {@link BuildStep},
60 * meaning it gets the same hook as {@link Publisher} and {@link Builder}.
61 * The primary intention of this mechanism is so that {@link JobProperty}s
62 * can add actions to the new build. The {@link #perform(AbstractBuild, Launcher, BuildListener)}
63 * and {@link #prebuild(AbstractBuild, BuildListener)} are invoked after those
64 * of {@link Publisher}s.
65 *
66 * @param <J>
67 * When you restrict your job property to be only applicable to a certain
68 * subtype of {@link Job}, you can use this type parameter to improve
69 * the type signature of this class. See {@link JobPropertyDescriptor#isApplicable(Class)}.
70 *
71 * @author Kohsuke Kawaguchi
72 * @see JobPropertyDescriptor
73 * @since 1.72
74 */
75 @ExportedBean
76 public abstract class JobProperty<J extends Job<?,?>> implements ReconfigurableDescribable<JobProperty<?>>, BuildStep, ExtensionPoint {
77 /**
78 * The {@link Job} object that owns this property.
79 * This value will be set by the Hudson code.
80 * Derived classes can expect this value to be always set.
81 */
82 protected transient J owner;
83
84 /**
85 * Hook for performing post-initialization action.
86 *
87 * <p>
88 * This method is invoked in two cases. One is when the {@link Job} that owns
89 * this property is loaded from disk, and the other is when a job is re-configured
90 * and all the {@link JobProperty} instances got re-created.
91 */
92 protected void setOwner(J owner) {
93 this.owner = owner;
94 }
95
96 /**
97 * {@inheritDoc}
98 */
99 public JobPropertyDescriptor getDescriptor() {
100 return (JobPropertyDescriptor) Jenkins.getInstance().getDescriptorOrDie(getClass());
101 }
102
103 /**
104 * @deprecated
105 * as of 1.341. Override {@link #getJobActions(Job)} instead.
106 */
107 public Action getJobAction(J job) {
108 return null;
109 }
110
111 /**
112 * {@link Action}s to be displayed in the job page.
113 *
114 * <p>
115 * Returning actions from this method allows a job property to add them
116 * to the left navigation bar in the job page.
117 *
118 * <p>
119 * {@link Action} can implement additional marker interface to integrate
120 * with the UI in different ways.
121 *
122 * @param job
123 * Always the same as {@link #owner} but passed in anyway for backward compatibility (I guess.)
124 * You really need not use this value at all.
125 * @return
126 * can be empty but never null.
127 * @since 1.341
128 * @see ProminentProjectAction
129 * @see PermalinkProjectAction
130 */
131 public Collection<? extends Action> getJobActions(J job) {
132 // delegate to getJobAction (singular) for backward compatible behavior
133 Action a = getJobAction(job);
134 if (a==null) return Collections.emptyList();
135 return Collections.singletonList(a);
136 }
137
138 //
139 // default no-op implementation
140 //
141
142 public boolean prebuild(AbstractBuild<?,?> build, BuildListener listener) {
143 return true;
144 }
145
146 /**
147 * {@inheritDoc}
148 *
149 * <p>
150 * Invoked after {@link Publisher}s have run.
151 */
152 public boolean perform(AbstractBuild<?,?> build, Launcher launcher, BuildListener listener) throws InterruptedException, IOException {
153 return true;
154 }
155
156 /**
157 * Returns {@link BuildStepMonitor#NONE} by default, as {@link JobProperty}s normally don't depend
158 * on its previous result.
159 */
160 public BuildStepMonitor getRequiredMonitorService() {
161 return BuildStepMonitor.NONE;
162 }
163
164 public final Action getProjectAction(AbstractProject<?,?> project) {
165 return getJobAction((J)project);
166 }
167
168 public final Collection<? extends Action> getProjectActions(AbstractProject<?,?> project) {
169 return getJobActions((J)project);
170 }
171
172 /** @see Job#getOverrides */
173 public Collection<?> getJobOverrides() {
174 return Collections.emptyList();
175 }
176
177 public JobProperty<?> reconfigure(StaplerRequest req, JSONObject form) throws FormException {
178 return form==null ? null : getDescriptor().newInstance(req,form);
179 }
180
181 /**
182 * Contributes {@link SubTask}s to {@link AbstractProject#getSubTasks()}
183 *
184 * @since 1.377
185 */
186 public Collection<? extends SubTask> getSubTasks() {
187 return Collections.emptyList();
188 }
189 }
190