Package 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
  • may implement IIncrementalProjectBuilder2
On creation, the setInitializationData method is called with any parameter data specified in the declaring plug-in's manifest.
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    AUTO_BUILD
    Build kind constant (value 9) indicating an automatic build request.
    static final int
    CLEAN_BUILD
    Build kind constant (value 15) indicating a clean build request.
    static final int
    FULL_BUILD
    Build kind constant (value 6) indicating a full build request.
    static final int
    INCREMENTAL_BUILD
    Build kind constant (value 10) indicating an incremental build request.

  • Constructor Summary

    Constructors
    Constructor
    Description
    IncrementalProjectBuilder()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected abstract IProject[]
    build(int kind, Map<String,String> 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.
    final void
    forgetLastBuiltState()
    Requests that this builder forget any state it may be retaining regarding previously built states.
    final IBuildConfiguration
    getBuildConfig()
    Returns the build configuration for which this build was invoked.
    final ICommand
    getCommand()
    Returns the build command associated with this builder.
    final IBuildContext
    getContext()
    Get the context for this invocation of the builder.
    final IResourceDelta
    getDelta(IProject project)
    Returns the resource delta recording the changes in the given project since the last time this builder was run.
    final IProject
    getProject()
    Returns the project for which this builder is defined.
    ISchedulingRule
    getRule(int kind, Map<String,String> args)
    Returns the scheduling rule that is required for building the project build configuration for which this builder is defined.
    final boolean
    hasBeenBuilt(IProject project)
    Returns whether the given project has already been built during this build iteration.
    final boolean
    isInterrupted()
    Returns whether an interrupt request has been made for this build.
    final void
    needRebuild()
    Indicates that this builder made changes that affect a build configuration that precedes this build configuration in the currently executing build order, and thus a rebuild will be necessary.
    final void
    rememberLastBuiltState()
    Requests that this builder remember any build invocation specific state.
    final void
    requestProjectRebuild(boolean processOtherBuilders)
    Indicates that this builder generated or detected new input for currently running project build, and thus a project rebuild will be necessary in the current build round.
    final void
    requestProjectsRebuild(Collection<IProject> projects)
    Indicates that this builder generated or detected new input for given projects and thus a rebuild for given projects will be necessary in the next build round.
    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 Details

  • Constructor Details

    • IncrementalProjectBuilder

      public IncrementalProjectBuilder()

  • Method Details

    • build

      protected abstract IProject[] build(int kind, Map<String,String> 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. A FULL_BUILD has no associated build delta.

      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 IResourceStatus.BUILD_FAILED status code along with a suitable message; another is to use a MultiStatus 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
      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:

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

      An alternative clean method that passes the build arguments is available in IIncrementalProjectBuilder2.clean(Map, IProgressMonitor) that can be implemented instead of overridding this clean method. This method will not be called if IIncrementalProjectBuilder2 is implemented.

      Specified by:
      clean in class org.eclipse.core.internal.events.InternalBuilder
      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:

    • 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. This supersedes a call to rememberLastBuiltState().
      Overrides:
      forgetLastBuiltState in class org.eclipse.core.internal.events.InternalBuilder

    • rememberLastBuiltState

      public final void rememberLastBuiltState()
      Requests that this builder remember any build invocation specific state. This means that the next time the builder runs, it will receive a delta which includes changes reported in the current getDelta(IProject).

      This can be used to indicate that a builder didn't run, even though there are changes, and the builder wishes that the delta be preserved until its next invocation.

      This is superseded by a call to forgetLastBuiltState().
      Overrides:
      rememberLastBuiltState in class org.eclipse.core.internal.events.InternalBuilder
      Since:
      3.7

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

      Overrides:
      getCommand in class org.eclipse.core.internal.events.InternalBuilder
      Since:
      3.1
      See Also:

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

      The delta does not include changes made while this builder is running. If getRule(int, Map) is overridden to return a scheduling rule other than the workspace root, changes performed in other threads during the build will not appear in the resource delta.

      Overrides:
      getDelta in class org.eclipse.core.internal.events.InternalBuilder
      Returns:
      the resource delta for the project or null
      See Also:

    • 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

    • getBuildConfig

      public final IBuildConfiguration getBuildConfig()
      Returns the build configuration for which this build was invoked.
      Overrides:
      getBuildConfig in class org.eclipse.core.internal.events.InternalBuilder
      Returns:
      the build configuration
      Since:
      3.7
      See Also:

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

      Overrides:
      hasBeenBuilt in class org.eclipse.core.internal.events.InternalBuilder
      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:

    • 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 org.eclipse.core.internal.events.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 build configuration that precedes this build configuration in the currently executing build order, and thus a rebuild will be necessary.

      Note: this method will schedule rebuild for all projects involved in the current build cycle!

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

      Overrides:
      needRebuild in class org.eclipse.core.internal.events.InternalBuilder
      Since:
      2.1
      See Also:

    • requestProjectRebuild

      public final void requestProjectRebuild(boolean processOtherBuilders)
      Indicates that this builder generated or detected new input for currently running project build, and thus a project rebuild will be necessary in the current build round.

      The builders configured to run after the current one will be still processed if processOtherBuilders is set to true. To force an immediate rebuild of a project processOtherBuilders argument should be set to false.

      Note if processOtherBuilders is set to false, the project that is built with current builder will be only rebuilt again, if this builder is not the first one configured to run.

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

      Overrides:
      requestProjectRebuild in class org.eclipse.core.internal.events.InternalBuilder
      Parameters:
      processOtherBuilders - to continue building project with other builders and not start project build from beginning immediately
      Since:
      3.17
      See Also:

    • requestProjectsRebuild

      public final void requestProjectsRebuild(Collection<IProject> projects)
      Indicates that this builder generated or detected new input for given projects and thus a rebuild for given projects will be necessary in the next build round.

      Note if the given collection contains the current project (that is currently built with current builder), the current project will be not rebuilt immediately, but scheduled for rebuild on next round. To perform immediate rebuild of the current project, use requestProjectRebuild(boolean).

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

      Overrides:
      requestProjectsRebuild in class org.eclipse.core.internal.events.InternalBuilder
      Since:
      3.17
      See Also:

    • 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 fails.
      See Also:

    • 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:

    • getRule

      public ISchedulingRule getRule(int kind, Map<String,String> args)
      Returns the scheduling rule that is required for building the project build configuration for which this builder is defined. The default is the workspace root rule.

      The scheduling rule determines which resources in the workspace are protected from being modified by other threads while the builder is running. Up until Eclipse 3.5, the entire workspace was always locked during a build; since Eclipse 3.6, builders can allow resources outside their scheduling rule to be modified.

      Notes:

      • The rule may be relaxed and in some cases let the builder be scheduled in parallel of any other operation using a rule based on IResource). A relaxed rule is a scheduling rule which does not contain the workspace root rule.
      • The rule returned here may have no effect if the build is invoked within the scope of another operation that locks the entire workspace.
      • If this method returns any rule other than the workspace root, resources outside of the rule scope can be modified concurrently with the build. The delta returned by getDelta(IProject) for any project outside the scope of the builder's rule may not contain changes that occurred concurrently with the build.

      Subclasses may override this method.

      Parameters:
      kind - the kind of build being requested. Valid values include:
      args - a table of builder-specific arguments keyed by argument name (key type: String, value type: String); null is equivalent to an empty map.
      Returns:
      a scheduling rule which is contained in the workspace root rule or null to indicate that no protection against resource modification during the build is needed.
      Since:
      3.6
      Restriction:
      This method is not intended to be referenced by clients.

    • getContext

      public final IBuildContext getContext()
      Get the context for this invocation of the builder. This is only valid in the context of a call to build(int, Map, IProgressMonitor)

      This can be used to discover which build configurations are being built before and after this build configuration.

      Overrides:
      getContext in class org.eclipse.core.internal.events.InternalBuilder
      Returns:
      the context for the most recent invocation of the builder
      Since:
      3.7
      See Also: