IncrementalProjectBuilder


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.core.resources;
12  
13  import java.util.Map  ;
14  import org.eclipse.core.internal.events.InternalBuilder;
15  import org.eclipse.core.runtime.*;
16  
17  /**
18   * The abstract base class for all incremental project builders. This class
19   * provides the infrastructure for defining a builder and fulfills the contract
20   * specified by the <code>org.eclipse.core.resources.builders</code> standard
21   * extension point.
22   * <p>
23   * All builders must subclass this class according to the following guidelines:
24   * <ul>
25   * <li>must re-implement at least <code>build</code></li>
26   * <li>may implement other methods</li>
27   * <li>must supply a public, no-argument constructor</li>
28   * </ul>
29   * On creation, the <code>setInitializationData</code> method is called with
30   * any parameter data specified in the declaring plug-in's manifest.
31   */
32  public abstract class IncrementalProjectBuilder extends InternalBuilder implements IExecutableExtension {
33      /**
34       * Build kind constant (value 6) indicating a full build request.  A full
35       * build discards all previously built state and builds all resources again.
36       * Resource deltas are not applicable for this kind of build.
37       * 
38       * @see IProject#build(int, IProgressMonitor)
39       * @see IProject#build(int, String, Map, IProgressMonitor)
40       * @see IWorkspace#build(int, IProgressMonitor)
41       */
42      public static final int FULL_BUILD = 6;
43      /**
44       * Build kind constant (value 9) indicating an automatic build request.  When
45       * autobuild is turned on, these builds are triggered automatically whenever
46       * resources change.  Apart from the method by which autobuilds are triggered,
47       * they otherwise operate like an incremental build.
48       * 
49       * @see IWorkspaceDescription#setAutoBuilding(boolean)
50       * @see IWorkspace#isAutoBuilding()
51       */
52      public static final int AUTO_BUILD = 9;
53      /**
54       * Build kind constant (value 10) indicating an incremental build request.
55       * Incremental builds use an {@link IResourceDelta} that describes what
56       * resources have changed since the last build.  The builder calculates
57       * what resources are affected by the delta, and rebuilds the affected resources.
58       * 
59       * @see IProject#build(int, IProgressMonitor)
60       * @see IProject#build(int, String, Map, IProgressMonitor)
61       * @see IWorkspace#build(int, IProgressMonitor)
62       */
63      public static final int INCREMENTAL_BUILD = 10;
64      /**
65       * Build kind constant (value 15) indicating a clean build request.  A clean
66       * build discards any additional state that has  been computed as a result of 
67       * previous builds, and returns the project to a clean slate. Resource
68       * deltas are not applicable for this kind of build.
69       * 
70       * @see IProject#build(int, IProgressMonitor)
71       * @see IProject#build(int, String, Map, IProgressMonitor)
72       * @see IWorkspace#build(int, IProgressMonitor)
73       * @see #clean(IProgressMonitor)
74       * @since 3.0
75       */
76      public static final int CLEAN_BUILD = 15;
77  
78      /**
79       * Runs this builder in the specified manner. Subclasses should implement
80       * this method to do the processing they require.
81       * <p>
82       * If the build kind is {@link #INCREMENTAL_BUILD} or
83       * {@link #AUTO_BUILD}, the <code>getDelta</code> method can be
84       * used during the invocation of this method to obtain information about
85       * what changes have occurred since the last invocation of this method. Any
86       * resource delta acquired is valid only for the duration of the invocation
87       * of this method.
88       * </p>
89       * <p>
90       * After completing a build, this builder may return a list of projects for
91       * which it requires a resource delta the next time it is run. This
92       * builder's project is implicitly included and need not be specified. The
93       * build mechanism will attempt to maintain and compute deltas relative to
94       * the identified projects when asked the next time this builder is run.
95       * Builders must re-specify the list of interesting projects every time they
96       * are run as this is not carried forward beyond the next build. Projects
97       * mentioned in return value but which do not exist will be ignored and no
98       * delta will be made available for them.
99       * </p>
100      * <p>
101      * This method is long-running; progress and cancellation are provided by
102      * the given progress monitor. All builders should report their progress and
103      * honor cancel requests in a timely manner. Cancelation requests should be
104      * propagated to the caller by throwing
105      * <code>OperationCanceledException</code>.
106      * </p>
107      * <p>
108      * All builders should try to be robust in the face of trouble. In
109      * situations where failing the build by throwing <code>CoreException</code>
110      * is the only option, a builder has a choice of how best to communicate the
111      * problem back to the caller. One option is to use the
112      * {@link IResourceStatus#BUILD_FAILED} status code along with a suitable message;
113      * another is to use a {@link MultiStatus} containing finer-grained problem
114      * diagnoses.
115      * </p>
116      * 
117      * @param kind the kind of build being requested. Valid values are
118      * <ul>
119      * <li>{@link #FULL_BUILD} - indicates a full build.</li>
120      * <li>{@link #INCREMENTAL_BUILD}- indicates an incremental build.</li>
121      * <li>{@link #AUTO_BUILD} - indicates an automatically triggered
122      * incremental build (autobuilding on).</li>
123      * </ul>
124      * @param args a table of builder-specific arguments keyed by argument name
125      * (key type: <code>String</code>, value type: <code>String</code>);
126      * <code>null</code> is equivalent to an empty map
127      * @param monitor a progress monitor, or <code>null</code> if progress
128      * reporting and cancellation are not desired
129      * @return the list of projects for which this builder would like deltas the
130      * next time it is run or <code>null</code> if none
131      * @exception CoreException if this build fails.
132      * @see IProject#build(int, String, Map, IProgressMonitor)
133      */
134     protected abstract IProject[] build(int kind, Map   args, IProgressMonitor monitor) throws CoreException;
135 
136     /**
137      * Clean is an opportunity for a builder to discard any additional state that has 
138      * been computed as a result of previous builds. It is recommended that builders 
139      * override this method to delete all derived resources created by previous builds, 
140      * and to remove all markers of type {@link IMarker#PROBLEM} that 
141      * were created by previous invocations of the builder. The platform will
142      * take care of discarding the builder's last built state (there is no need
143      * to call <code>forgetLastBuiltState</code>).
144      * </p>
145      * <p>
146      * This method is called as a result of invocations of
147      * <code>IWorkspace.build</code> or <code>IProject.build</code> where
148      * the build kind is {@link #CLEAN_BUILD}.
149      * <p>
150      * This default implementation does nothing. Subclasses may override. 
151      * <p>
152      * This method is long-running; progress and cancellation are provided by
153      * the given progress monitor. All builders should report their progress and
154      * honor cancel requests in a timely manner. Cancelation requests should be
155      * propagated to the caller by throwing
156      * <code>OperationCanceledException</code>.
157      * </p>
158      * 
159      * @param monitor a progress monitor, or <code>null</code> if progress
160      * reporting and cancellation are not desired
161      * @exception CoreException if this build fails.
162      * @see IWorkspace#build(int, IProgressMonitor)
163      * @see #CLEAN_BUILD
164      * @since 3.0
165      */
166     protected void clean(IProgressMonitor monitor) throws CoreException {
167         //default implementation does nothing
168         if (false)
169             throw new CoreException(Status.OK_STATUS);//thwart compiler warning
170     }
171 
172     /**
173      * Requests that this builder forget any state it may be retaining regarding
174      * previously built states. Typically this means that the next time the
175      * builder runs, it will have to do a full build since it does not have any
176      * state upon which to base an incremental build.
177      */
178     public final void forgetLastBuiltState() {
179         super.forgetLastBuiltState();
180     }
181 
182     /**
183      * Returns the build command associated with this builder.  The returned
184      * command may or may not be in the build specification for the project
185      * on which this builder operates.
186      * <p>
187      * Any changes made to the returned command will only take effect if
188      * the modified command is installed on a project build spec.
189      * </p>
190      * 
191      * @see IProjectDescription#setBuildSpec(ICommand [])
192      * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor)
193      * @since 3.1
194      */
195     public final ICommand getCommand() {
196         return super.getCommand();
197     }
198 
199     /**
200      * Returns the resource delta recording the changes in the given project
201      * since the last time this builder was run. <code>null</code> is returned
202      * if no such delta is available. An empty delta is returned if no changes
203      * have occurred, or if deltas are not applicable for the current build kind.
204      * If <code>null</code> is returned, clients should assume
205      * that unspecified changes have occurred and take the appropriate action.
206      * <p>
207      * The system reserves the right to trim old state in an effort to conserve
208      * space. As such, callers should be prepared to receive <code>null</code>
209      * even if they previously requested a delta for a particular project by
210      * returning that project from a <code>build</code> call.
211      * </p>
212      * <p>
213      * A non- <code>null</code> delta will only be supplied for the given
214      * project if either the result returned from the previous
215      * <code>build</code> included the project or the project is the one
216      * associated with this builder.
217      * </p>
218      * <p>
219      * If the given project was mentioned in the previous <code>build</code>
220      * and subsequently deleted, a non- <code>null</code> delta containing the
221      * deletion will be returned. If the given project was mentioned in the
222      * previous <code>build</code> and was subsequently created, the returned
223      * value will be <code>null</code>.
224      * </p>
225      * <p>
226      * A valid delta will be returned only when this method is called during a
227      * build. The delta returned will be valid only for the duration of the
228      * enclosing build execution.
229      * </p>
230      * 
231      * @return the resource delta for the project or <code>null</code>
232      */
233     public final IResourceDelta getDelta(IProject project) {
234         return super.getDelta(project);
235     }
236 
237     /**
238      * Returns the project for which this builder is defined.
239      * 
240      * @return the project
241      */
242     public final IProject getProject() {
243         return super.getProject();
244     }
245 
246     /**
247      * Returns whether the given project has already been built during this
248      * build iteration.
249      * <p>
250      * When the entire workspace is being built, the projects are built in
251      * linear sequence. This method can be used to determine if another project
252      * precedes this builder's project in that build sequence. If only a single
253      * project is being built, then there is no build order and this method will
254      * always return <code>false</code>.
255      * </p>
256      * 
257      * @param project the project to check against in the current build order
258      * @return <code>true</code> if the given project has been built in this
259      * iteration, and <code>false</code> otherwise.
260      * @see #needRebuild()
261      * @since 2.1
262      */
263     public final boolean hasBeenBuilt(IProject project) {
264         return super.hasBeenBuilt(project);
265     }
266 
267     /**
268      * Returns whether an interrupt request has been made for this build.
269      * Background autobuild is interrupted when another thread tries to modify
270      * the workspace concurrently with the build thread. When this occurs, the
271      * build cycle is flagged as interrupted and the build will be terminated at
272      * the earliest opportunity. This method allows long running builders to
273      * respond to this interruption in a timely manner. Builders are not
274      * required to respond to interruption requests.
275      * <p>
276      * 
277      * @return <code>true</code> if the build cycle has been interrupted, and
278      * <code>false</code> otherwise.
279      * @since 3.0
280      */
281     public final boolean isInterrupted() {
282         return super.isInterrupted();
283     }
284 
285     /**
286      * Indicates that this builder made changes that affect a project that
287      * precedes this project in the currently executing build order, and thus a
288      * rebuild will be necessary.
289      * <p>
290      * This is an advanced feature that builders should use with caution. This
291      * can cause workspace builds to iterate until no more builders require
292      * rebuilds.
293      * </p>
294      * 
295      * @see #hasBeenBuilt(IProject)
296      * @since 2.1
297      */
298     public final void needRebuild() {
299         super.needRebuild();
300     }
301 
302     /**
303      * Sets initialization data for this builder.
304      * <p>
305      * This method is part of the {@link IExecutableExtension} interface.
306      * </p>
307      * <p>
308      * Subclasses are free to extend this method to pick up initialization
309      * parameters from the plug-in plug-in manifest (<code>plugin.xml</code>)
310      * file, but should be sure to invoke this method on their superclass.
311      * <p>
312      * For example, the following method looks for a boolean-valued parameter
313      * named "trace":
314      * 
315      * <pre>
316      * public void setInitializationData(IConfigurationElement cfig, String propertyName, Object data) throws CoreException {
317      *  super.setInitializationData(cfig, propertyName, data);
318      *  if (data instanceof Hashtable) {
319      *      Hashtable args = (Hashtable) data;
320      *      String traceValue = (String) args.get(&quot;trace&quot;);
321      *      TRACING = (traceValue != null &amp;&amp; traceValue.equals(&quot;true&quot;));
322      *  }
323      * }
324      * </pre>
325      * 
326      * </p>
327      */
328     public void setInitializationData(IConfigurationElement config, String   propertyName, Object   data) throws CoreException {
329         //thwart compiler warning
330         if (false)
331             throw new CoreException(Status.OK_STATUS);
332     }
333 
334     /**
335      * Informs this builder that it is being started by the build management
336      * infrastructure. By the time this method is run, the builder's project is
337      * available and <code>setInitializationData</code> has been called. The
338      * default implementation should be called by all overriding methods.
339      * 
340      * @see #setInitializationData(IConfigurationElement, String, Object)
341      */
342     protected void startupOnInitialize() {
343         // reserved for future use
344     }
345 }
346
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags