BuildWrapper


1   package hudson.tasks;
2   
3   import hudson.ExtensionPoint;
4   import hudson.Launcher;
5   import hudson.model.Build;
6   import hudson.model.BuildListener;
7   import hudson.model.Describable;
8   import hudson.model.Project;
9   
10  import java.io.IOException  ;
11  import java.util.Map  ;
12  
13  /**
14   * Pluggability point for performing pre/post actions for the build process.
15   *
16   * <p>
17   * <b>STILL EXPERIMENTAL. SUBJECT TO CHANGE</b>
18   *
19   * <p>
20   * This extension point enables a plugin to set up / tear down additional
21   * services needed to perform a build, such as setting up local X display,
22   * or launching and stopping application servers for testing.
23   *
24   * <p>
25   * An instance of {@link BuildWrapper} is associated with a {@link Project}
26   * with configuration information as its state. An instance is persisted
27   * along with {@link Project}.
28   *
29   * <p>
30   * The {@link #setUp(Build,Launcher,BuildListener)} method is invoked for each build.
31   *
32   * @author Kohsuke Kawaguchi
33   */
34  public abstract class BuildWrapper implements ExtensionPoint, Describable<BuildWrapper> {
35      /**
36       * Represents the environment set up by {@link BuildWrapper#setUp(Build,Launcher,BuildListener)}.
37       *
38       * <p>
39       * It is expected that the subclasses of {@link BuildWrapper} extends this
40       * class and implements its own semantics.
41       */
42      public abstract class Environment {
43          /**
44           * Adds environmental variables for the builds to the given map.
45           *
46           * <p>
47           * If the {@link Environment} object wants to pass in information
48           * to the build that runs, it can do so by exporting additional
49           * environment variables to the map.
50           *
51           * <p>
52           * When this method is invoked, the map already contains the
53           * current "planned export" list.
54           *
55           * @param env
56           *      never null. 
57           */
58          public void buildEnvVars(Map  <String  ,String  > env) {
59              // no-op by default
60          }
61  
62          /**
63           * Runs after the {@link Builder} completes, and performs a tear down.
64           *
65           * <p>
66           * This method is invoked even when the build failed, so that the
67           * clean up operation can be performed regardless of the build result
68           * (for example, you'll want to stop application server even if a build
69           * fails.)
70           *
71           * @param build
72           *      The same {@link Build} object given to the set up method.
73           * @param listener
74           *      The same {@link BuildListener} object given to the set up method.
75           * @return
76           *      true if the build can continue, false if there was an error
77           *      and the build needs to be aborted.
78           * @throws IOException
79           *      terminates the build abnormally. Hudson will handle the exception
80           *      and reports a nice error message.
81           */
82          public abstract boolean tearDown( Build build, BuildListener listener ) throws IOException  ;
83      }
84  
85      /**
86       * Runs before the {@link Builder} runs, and performs a set up.
87       *
88       * @param build
89       *      The build in progress for which an {@link Environment} object is created.
90       *      Never null.
91       * @param launcher
92       *      This launcher can be used to launch processes for this build.
93       *      If the build runs remotely, launcher will also run a job on that remote machine.
94       *      Never null.
95       * @param listener
96       *      Can be used to send any message.
97       * @return
98       *      non-null if the build can continue, null if there was an error
99       *      and the build needs to be aborted.
100      * @throws IOException
101      *      terminates the build abnormally. Hudson will handle the exception
102      *      and reports a nice error message.
103      */
104     public abstract Environment setUp( Build build, Launcher launcher, BuildListener listener ) throws IOException  ;
105 }
106
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags