PageRenderTime 17ms CodeModel.GetById 11ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/hudson-core/src/main/java/hudson/model/JobProperty.java

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