org.eclipse.core.resources
Class IncrementalProjectBuilder

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

All Implemented Interfaces:

IExecutableExtension

public abstract class IncrementalProjectBuilder

extends org.eclipse.core.internal.events.InternalBuilder

implements 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 indicating an automatic build request.
static int	FULL_BUILD Build kind constant indicating a full build request.
static int	INCREMENTAL_BUILD Build kind constant indicating an incremental build request.

Constructor Summary

IncrementalProjectBuilder()

Method Summary

protected abstract IProject[]	build(int kind, Map args, IProgressMonitor monitor) Runs this builder on the given changes in the specified manner.
void	forgetLastBuiltState() Requests that this builder forget any state it may be retaining regarding previously built states.
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.
void	setInitializationData(IConfigurationElement config, String propertyName, Object data) Sets initialization data for this builder.
protected void	startupOnInitialize() Informs this builder that it is being started by the build management infrastructure.

Methods inherited from class java.lang.Object

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

Field Detail

INCREMENTAL_BUILD

public static final int INCREMENTAL_BUILD

Build kind constant indicating an incremental build request.

See Also:

IProject.build(int, java.lang.String, java.util.Map, org.eclipse.core.runtime.IProgressMonitor), Constant Field Values

FULL_BUILD

public static final int FULL_BUILD

Build kind constant indicating a full build request.

See Also:

IProject.build(int, java.lang.String, java.util.Map, org.eclipse.core.runtime.IProgressMonitor), Constant Field Values

AUTO_BUILD

public static final int AUTO_BUILD

Build kind constant indicating an automatic build request.

See Also:

IProject.build(int, java.lang.String, java.util.Map, org.eclipse.core.runtime.IProgressMonitor), Constant Field Values

Constructor Detail

IncrementalProjectBuilder

public IncrementalProjectBuilder()

Method Detail

build

protected abstract IProject[] build(int kind,
                                    Map args,
                                    IProgressMonitor monitor)
                             throws CoreException

Runs this builder on the given changes in the specified manner. Subclasses should implement this method to do the processing they require.

When invoked in response to a call to one of the IProject.build methods, the resource delta is rooted at the project. When invoked to do an auto-build, the kind will be AUTO_BUILD.

Any resource delta acquired is valid only for the duration of the invocation of this method.

After completing a build, this builder may return a list of projects for which it requires a resource delta the next time it is run. This builder's project is implicitly included and need not be specified. The build mechanism will attempt to maintain and compute deltas relative to the identified projects when asked the next time this builder is run. Builders must re-specify the list of interesting projects every time they are run as this is not carried forward beyond the next build. Projects mentioned in return value but which do not exist will be ignored and no delta will be made available for them.

This method is long-running; progress and cancellation are provided by the given progress monitor. All builders should report their progress and honor cancel requests in a timely manner. Cancellation requests should be propagated to the caller by throwing OperationCanceledException.

All builders should try to be robust in the face of trouble. In situations where failing the build by throwing CoreException is the only option, a builder has a choice of how best to communicate the problem back to the caller. One option is to use the BUILD_FAILED status code along with a suitable message; another is to use a multi-status containing finer-grained problem diagnoses.

Specified by:

build in class org.eclipse.core.internal.events.InternalBuilder

Parameters:

kind - the kind of build being requested. Valid values are

• FULL_BUILD - indicates a full build.
• INCREMENTAL_BUILD - indicates an incremental build.
• AUTO_BUILD - indicates an automatically triggered incremental build (auto-building on).

args - a table of builder-specific arguments keyed by argument name (key type: String, value type: String); null is equivalent to an empty map

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Returns:

the list of projects for which this builder would like deltas the next time it is run or null if none

Throws:

CoreException - if this build fails.

See Also:

IProject.build(int, java.lang.String, java.util.Map, org.eclipse.core.runtime.IProgressMonitor)

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.

Overrides:

forgetLastBuiltState in class org.eclipse.core.internal.events.InternalBuilder

See Also:

forgetLastBuiltState()

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. 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.

Overrides:

getDelta in class org.eclipse.core.internal.events.InternalBuilder

Returns:

the resource delta for the project or null

getProject

public final IProject getProject()

Returns the project for which this builder is defined.

Overrides:

getProject in class org.eclipse.core.internal.events.InternalBuilder

Returns:

the project

setInitializationData

public void setInitializationData(IConfigurationElement config,
                                  String propertyName,
                                  Object data)
                           throws CoreException

Sets initialization data for this builder.

This methods 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 IExecutableExtension

Parameters:

config - the configuration element used to trigger this execution. It can be queried by the executable extension for specific configuration properties

propertyName - the name of an attribute of the configuration element used on the createExecutableExtension(String) call. This argument can be used in the cases where a single configuration element is used to define multiple executable extensions.

data - adapter data in the form of a String, a Hashtable, or null.

Throws:

CoreException - if error(s) detected during initialization processing

See Also:

IConfigurationElement.createExecutableExtension(java.lang.String)

startupOnInitialize

protected void startupOnInitialize()

Informs this builder that it is being started by the build management infrastructure. By the time this method is run, the builder's project is available and setInitializationData has been called. The default implementation should be called by all overriding methods.

Specified by:

startupOnInitialize in class org.eclipse.core.internal.events.InternalBuilder

See Also:

setInitializationData(org.eclipse.core.runtime.IConfigurationElement, java.lang.String, java.lang.Object)