org.eclipse.core.resources
Class IncrementalProjectBuilder

java.lang.Object
  org.eclipse.core.internal.events.InternalBuilder
      org.eclipse.core.resources.IncrementalProjectBuilder

All Implemented Interfaces:

org.eclipse.core.runtime.IExecutableExtension

Direct Known Subclasses:

JavaBuilder, SignaledBuilder, SimpleBuilder, TestBuilder

public abstract class IncrementalProjectBuilder
extends InternalBuilder
implements org.eclipse.core.runtime.IExecutableExtension

The abstract base class for all incremental project builders. This class provides the infrastructure for defining a builder and fulfills the contract specified by the org.eclipse.core.resources.builders standard extension point.

All builders must subclass this class according to the following guidelines:

• must re-implement at least build
• may implement other methods
• must supply a public, no-argument constructor

On creation, the setInitializationData method is called with any parameter data specified in the declaring plug-in's manifest.

Field Summary

static int	AUTO_BUILD Build kind constant (value 9) indicating an automatic build request.
static int	CLEAN_BUILD Build kind constant (value 15) indicating a clean build request.
static int	FULL_BUILD Build kind constant (value 6) indicating a full build request.
static int	INCREMENTAL_BUILD Build kind constant (value 10) indicating an incremental build request.

Constructor Summary

IncrementalProjectBuilder()

Method Summary

void	forgetLastBuiltState() Requests that this builder forget any state it may be retaining regarding previously built states.
ICommand	getCommand() Returns the build command associated with this builder.
IResourceDelta	getDelta(IProject project) Returns the resource delta recording the changes in the given project since the last time this builder was run.
IProject	getProject() Returns the project for which this builder is defined.
org.eclipse.core.runtime.jobs.ISchedulingRule	getRule() Returns the scheduling rule that is required for building the project for which this builder is defined.
boolean	hasBeenBuilt(IProject project) Returns whether the given project has already been built during this build iteration.
boolean	isInterrupted() Returns whether an interrupt request has been made for this build.
void	needRebuild() Indicates that this builder made changes that affect a project that precedes this project in the currently executing build order, and thus a rebuild will be necessary.
void	setInitializationData(org.eclipse.core.runtime.IConfigurationElement config, java.lang.String propertyName, java.lang.Object data) Sets initialization data for this builder.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FULL_BUILD

public static final int FULL_BUILD

Build kind constant (value 6) indicating a full build request. A full build discards all previously built state and builds all resources again. Resource deltas are not applicable for this kind of build.

See Also:

IProject.build(int, IProgressMonitor), IProject.build(int, String, Map, IProgressMonitor), IWorkspace.build(int, IProgressMonitor), Constant Field Values

AUTO_BUILD

public static final int AUTO_BUILD

Build kind constant (value 9) indicating an automatic build request. When autobuild is turned on, these builds are triggered automatically whenever resources change. Apart from the method by which autobuilds are triggered, they otherwise operate like an incremental build.

See Also:

IWorkspaceDescription.setAutoBuilding(boolean), IWorkspace.isAutoBuilding(), Constant Field Values

INCREMENTAL_BUILD

public static final int INCREMENTAL_BUILD

Build kind constant (value 10) indicating an incremental build request. Incremental builds use an IResourceDelta that describes what resources have changed since the last build. The builder calculates what resources are affected by the delta, and rebuilds the affected resources.

See Also:

IProject.build(int, IProgressMonitor), IProject.build(int, String, Map, IProgressMonitor), IWorkspace.build(int, IProgressMonitor), Constant Field Values

CLEAN_BUILD

public static final int CLEAN_BUILD

Build kind constant (value 15) indicating a clean build request. A clean build discards any additional state that has been computed as a result of previous builds, and returns the project to a clean slate. Resource deltas are not applicable for this kind of build.

Since:

3.0

See Also:

IProject.build(int, IProgressMonitor), IProject.build(int, String, Map, IProgressMonitor), IWorkspace.build(int, IProgressMonitor), clean(IProgressMonitor), Constant Field Values

Constructor Detail

IncrementalProjectBuilder

public IncrementalProjectBuilder()

Method Detail

forgetLastBuiltState

public final void forgetLastBuiltState()

Requests that this builder forget any state it may be retaining regarding previously built states. Typically this means that the next time the builder runs, it will have to do a full build since it does not have any state upon which to base an incremental build.

getCommand

public final ICommand getCommand()

Returns the build command associated with this builder. The returned command may or may not be in the build specification for the project on which this builder operates.

Any changes made to the returned command will only take effect if the modified command is installed on a project build spec.

Since:

3.1

See Also:

IProjectDescription.setBuildSpec(ICommand []), IProject.setDescription(IProjectDescription, int, IProgressMonitor)

getDelta

public final IResourceDelta getDelta(IProject project)

Returns the resource delta recording the changes in the given project since the last time this builder was run. null is returned if no such delta is available. An empty delta is returned if no changes have occurred, or if deltas are not applicable for the current build kind. If null is returned, clients should assume that unspecified changes have occurred and take the appropriate action.

The system reserves the right to trim old state in an effort to conserve space. As such, callers should be prepared to receive null even if they previously requested a delta for a particular project by returning that project from a build call.

A non- null delta will only be supplied for the given project if either the result returned from the previous build included the project or the project is the one associated with this builder.

If the given project was mentioned in the previous build and subsequently deleted, a non- null delta containing the deletion will be returned. If the given project was mentioned in the previous build and was subsequently created, the returned value will be null.

A valid delta will be returned only when this method is called during a build. The delta returned will be valid only for the duration of the enclosing build execution.

Returns:

the resource delta for the project or null

getProject

public final IProject getProject()

Returns the project for which this builder is defined.

Returns:

the project

hasBeenBuilt

public final boolean hasBeenBuilt(IProject project)

Returns whether the given project has already been built during this build iteration.

When the entire workspace is being built, the projects are built in linear sequence. This method can be used to determine if another project precedes this builder's project in that build sequence. If only a single project is being built, then there is no build order and this method will always return false.

Parameters:

project - the project to check against in the current build order

Returns:

true if the given project has been built in this iteration, and false otherwise.

Since:

2.1

See Also:

needRebuild()

isInterrupted

public final boolean isInterrupted()

Returns whether an interrupt request has been made for this build. Background autobuild is interrupted when another thread tries to modify the workspace concurrently with the build thread. When this occurs, the build cycle is flagged as interrupted and the build will be terminated at the earliest opportunity. This method allows long running builders to respond to this interruption in a timely manner. Builders are not required to respond to interruption requests.

Overrides:

isInterrupted in class InternalBuilder

Returns:

true if the build cycle has been interrupted, and false otherwise.

Since:

3.0

needRebuild

public final void needRebuild()

Indicates that this builder made changes that affect a project that precedes this project in the currently executing build order, and thus a rebuild will be necessary.

This is an advanced feature that builders should use with caution. This can cause workspace builds to iterate until no more builders require rebuilds.

Since:

2.1

See Also:

hasBeenBuilt(IProject)

setInitializationData

public void setInitializationData(org.eclipse.core.runtime.IConfigurationElement config,
                                  java.lang.String propertyName,
                                  java.lang.Object data)
                           throws org.eclipse.core.runtime.CoreException

Sets initialization data for this builder.

This method is part of the IExecutableExtension interface.

Subclasses are free to extend this method to pick up initialization parameters from the plug-in plug-in manifest (plugin.xml) file, but should be sure to invoke this method on their superclass.

For example, the following method looks for a boolean-valued parameter named "trace":

 public void setInitializationData(IConfigurationElement cfig, String propertyName, Object data) throws CoreException {
        super.setInitializationData(cfig, propertyName, data);
        if (data instanceof Hashtable) {
                Hashtable args = (Hashtable) data;
                String traceValue = (String) args.get("trace");
                TRACING = (traceValue != null && traceValue.equals("true"));
        }
 }
 

Specified by:

setInitializationData in interface org.eclipse.core.runtime.IExecutableExtension

Throws:

org.eclipse.core.runtime.CoreException - if fails.

getRule

public org.eclipse.core.runtime.jobs.ISchedulingRule getRule()

Returns the scheduling rule that is required for building the project for which this builder is defined. The default is the workspace root rule.

Returns:

scheduling rule

Since:

3.5