KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > hudson > tasks > BuildStep


1 package hudson.tasks;
2
3 import hudson.Launcher;
4 import hudson.model.Action;
5 import hudson.model.Build;
6 import hudson.model.BuildListener;
7 import hudson.model.Descriptor;
8 import hudson.model.Project;
9 import hudson.tasks.junit.JUnitResultArchiver;
10
11 import java.io.IOException JavaDoc;
12 import java.util.ArrayList JavaDoc;
13 import java.util.Collection JavaDoc;
14 import java.util.List JavaDoc;
15
16 /**
17  * One step of the whole build process.
18  *
19  * <h2>Persistence</h2>
20  * <p>
21  * These objects are persisted as a part of {@link Project} by XStream.
22  * The save operation happens without any notice, and the restore operation
23  * happens without calling the constructor, just like Java serialization.
24  *
25  * <p>
26  * So generally speaking, derived classes should use instance variables
27  * only for keeping configuration. You can still store objects you use
28  * for processing, like a parser of some sort, but they need to be marked
29  * as <tt>transient</tt>, and the code needs to be aware that they might
30  * be null (which is the case when you access the field for the first time
31  * the object is restored.)
32  *
33  * @author Kohsuke Kawaguchi
34  */
35 public interface BuildStep {
36
37     /**
38      * Runs before the build begins.
39      *
40      * @return
41      * true if the build can continue, false if there was an error
42      * and the build needs to be aborted.
43      */
44     boolean prebuild( Build build, BuildListener listener );
45
46     /**
47      * Runs the step over the given build and reports the progress to the listener.
48      *
49      * <p>
50      * A plugin can contribute the action object to {@link Build#getActions()}
51      * so that a 'report' becomes a part of the persisted data of {@link Build}.
52      * This is how JUnit plugin attaches the test report to a build page, for example.
53      *
54      * @return
55      * true if the build can continue, false if there was an error
56      * and the build needs to be aborted.
57      *
58      * @throws InterruptedException
59      * If the build is interrupted by the user (in an attempt to abort the build.)
60      * Normally the {@link BuildStep} implementations may simply forward the exception
61      * it got from its lower-level functions.
62      * @throws IOException
63      * If the implementation wants to abort the processing when an {@link IOException}
64      * happens, it can simply propagate the exception to the caller. This will cause
65      * the build to fail, with the default error message.
66      * Implementations are encouraged to catch {@link IOException} on its own to
67      * provide a better error message, if it can do so, so that users have better
68      * understanding on why it failed.
69      */
70     boolean perform(Build build, Launcher launcher, BuildListener listener) throws InterruptedException JavaDoc, IOException JavaDoc;
71
72     /**
73      * Returns an action object if this {@link BuildStep} has an action
74      * to contribute to a {@link Project}.
75      *
76      * <p>
77      * {@link Project} calls this method for every {@link BuildStep} that
78      * it owns when the rendering is requested.
79      *
80      * @param project
81      * {@link Project} that owns this build step,
82      * since {@link BuildStep} object doesn't usually have this "parent" pointer.
83      *
84      * @return
85      * null if there's no action to be contributed.
86      */
87     Action getProjectAction(Project project);
88
89     /**
90      * List of all installed builders.
91      *
92      * Builders are invoked to perform the build itself.
93      */
94     public static final List JavaDoc<Descriptor<Builder>> BUILDERS = Descriptor.toList(
95         Shell.DESCRIPTOR,
96         BatchFile.DESCRIPTOR,
97         Ant.DESCRIPTOR,
98         Maven.DESCRIPTOR
99     );
100
101     /**
102      * List of all installed publishers.
103      *
104      * Publishers are invoked after the build is completed, normally to perform
105      * some post-actions on build results, such as sending notifications, collecting
106      * results, etc.
107      *
108      * @see PublisherList#addNotifier(Descriptor)
109      * @see PublisherList#addRecorder(Descriptor)
110      */
111     public static final PublisherList PUBLISHERS = new PublisherList(Descriptor.toList(
112         ArtifactArchiver.DESCRIPTOR,
113         Fingerprinter.DESCRIPTOR,
114         JavadocArchiver.DESCRIPTOR,
115         JUnitResultArchiver.DescriptorImpl.DESCRIPTOR,
116         BuildTrigger.DESCRIPTOR,
117         Mailer.DESCRIPTOR
118     ));
119
120     /**
121      * List of publisher descriptor.
122      */
123     public static final class PublisherList extends ArrayList JavaDoc<Descriptor<Publisher>> {
124         public PublisherList(Collection JavaDoc<? extends Descriptor<Publisher>> c) {
125             super(c);
126         }
127
128         /**
129          * Adds a new publisher descriptor, which (generally speaking)
130          * shouldn't alter the build result, but just report the build result
131          * by some means, such as e-mail, IRC, etc.
132          *
133          * <p>
134          * This method adds the descriptor after all the "recorders".
135          *
136          * @see #addRecorder(Descriptor)
137          */
138         public void addNotifier( Descriptor<Publisher> d ) {
139             add(d);
140         }
141         
142         /**
143          * Adds a new publisher descriptor, which (generally speaking)
144          * alter the build result based on some artifacts of the build.
145          *
146          * <p>
147          * This method adds the descriptor before all the "notifiers".
148          *
149          * @see #addNotifier(Descriptor)
150          */
151         public void addRecorder( Descriptor<Publisher> d ) {
152             int idx = super.indexOf(Mailer.DESCRIPTOR);
153             add(idx,d);
154         }
155     }
156 }
157
Popular Tags