Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 (value 9) indicating an automatic build request.
`static int` | `CLEAN_BUILD` Build kind constant (value 15) indicating a build clean 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
`protected abstract IProject[]` | `build(int kind, Map args, IProgressMonitor monitor)` Runs this builder in the specified manner.
`protected void` | `clean(IProgressMonitor monitor)` Clean is an opportunity for a builder to discard any additional state that has been computed as a result of previous builds.
`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.
`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 preceeds this project in the currently executing build order, and thus a rebuild will be necessary.
`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 (value 10) indicating an incremental build request.

  See Also:
    `IProject.build(int, IProgressMonitor)`, `IProject.build(int, String, Map, IProgressMonitor)`, `IWorkspace.build(int, IProgressMonitor)`, Constant Field Values

### FULL_BUILD

    public static final int FULL_BUILD

  Build kind constant (value 6) indicating a full build request.

  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.

  See Also:
    Constant Field Values

### CLEAN_BUILD

    public static final int CLEAN_BUILD

  Build kind constant (value 15) indicating a build clean request

  Since:
    3.0
  See Also:
    `IProject.build(int, IProgressMonitor)`, `IProject.build(int, String, Map, IProgressMonitor)`, `IWorkspace.build(int, 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 in the specified manner. Subclasses should implement this method to do the processing they require.

  If the build kind is `INCREMENTAL_BUILD` or `AUTO_BUILD`, the `getDelta` method can be used during the invocation of this method to obtain information about what changes have occurred since the last invocation of this method. 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. Cancelation 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.

  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, String, Map, IProgressMonitor)`

### clean

    protected void clean(IProgressMonitor monitor)
                  throws CoreException

  Clean is an opportunity for a builder to discard any additional state that has been computed as a result of previous builds. It is recommended that builders override this method to delete all derived resources created by previous builds, and to remove all markers of type `IMarker.PROBLEM` that were created by previous invocations of the builder. The platform will take care of discarding the builder's last built state (there is no need to call `forgetLastBuiltState`).

  This method is called as a result of invocations of `IWorkspace.build` or `IProject.build` where the build kind is `CLEAN_BUILD`.

  This default implementation does nothing. Subclasses may override.

  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. Cancelation requests should be propagated to the caller by throwing `OperationCanceledException`.

  Parameters:
    `monitor` - a progress monitor, or `null` if progress reporting and cancellation are not desired
  Throws:
    `CoreException` - if this build fails.
  Since:
    3.0
  See Also:
    `IWorkspace.build(int, IProgressMonitor)`, `CLEAN_BUILD`

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

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

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

  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 preceeds 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(IConfigurationElement config,
                                      String propertyName,
                                      Object data)
                               throws 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 `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(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.

  See Also:
    `setInitializationData(IConfigurationElement, String, Object)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.