public abstract class IncrementalProjectBuilder extends org.eclipse.core.internal.events.InternalBuilder implements IExecutableExtension
org.eclipse.core.resources.builders
standard
extension point.
All builders must subclass this class according to the following guidelines:
build
setInitializationData
method is called with
any parameter data specified in the declaring plug-in's manifest.Modifier and Type | Field and Description |
---|---|
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 and Description |
---|
IncrementalProjectBuilder() |
Modifier and Type | Method and 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.
|
void |
forgetLastBuiltState()
Requests that this builder forget any state it may be retaining regarding
previously built states.
|
IBuildConfiguration |
getBuildConfig()
Returns the build configuration for which this build was invoked.
|
ICommand |
getCommand()
Returns the build command associated with this builder.
|
IBuildContext |
getContext()
Get the context for this invocation of the 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.
|
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.
|
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 build configuration that
precedes this build configuration in the currently executing build order, and thus a
rebuild will be necessary.
|
void |
rememberLastBuiltState()
Requests that this builder remember any build invocation specific state.
|
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.
|
public static final int FULL_BUILD
Note: If there is no previous delta, a request for INCREMENTAL_BUILD
or AUTO_BUILD
will result in the builder being called with FULL_BUILD
build kind.
public static final int AUTO_BUILD
public static final int INCREMENTAL_BUILD
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.public static final int CLEAN_BUILD
protected abstract IProject[] build(int kind, Map<String,String> args, IProgressMonitor monitor) throws CoreException
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.
build
in class org.eclipse.core.internal.events.InternalBuilder
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 (autobuilding on).args
- a table of builder-specific arguments keyed by argument name
(key type: String
, value type: String
);
null
is equivalent to an empty mapmonitor
- a progress monitor, or null
if progress
reporting and cancellation are not desirednull
if noneCoreException
- if this build fails.IProject.build(int, String, Map, IProgressMonitor)
protected void clean(IProgressMonitor monitor) throws CoreException
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
.
clean
in class org.eclipse.core.internal.events.InternalBuilder
monitor
- a progress monitor, or null
if progress
reporting and cancellation are not desiredCoreException
- if this build fails.IWorkspace.build(int, IProgressMonitor)
,
CLEAN_BUILD
public final void forgetLastBuiltState()
rememberLastBuiltState()
.forgetLastBuiltState
in class org.eclipse.core.internal.events.InternalBuilder
public final void rememberLastBuiltState()
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 toforgetLastBuiltState()
.rememberLastBuiltState
in class org.eclipse.core.internal.events.InternalBuilder
public final ICommand getCommand()
Any changes made to the returned command will only take effect if the modified command is installed on a project build spec.
getCommand
in class org.eclipse.core.internal.events.InternalBuilder
IProjectDescription.setBuildSpec(ICommand [])
,
IProject.setDescription(IProjectDescription, int, IProgressMonitor)
public final IResourceDelta getDelta(IProject project)
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.
getDelta
in class org.eclipse.core.internal.events.InternalBuilder
null
forgetLastBuiltState()
,
rememberLastBuiltState()
public final IProject getProject()
getProject
in class org.eclipse.core.internal.events.InternalBuilder
public final IBuildConfiguration getBuildConfig()
getBuildConfig
in class org.eclipse.core.internal.events.InternalBuilder
getBuildConfig()
public final boolean hasBeenBuilt(IProject project)
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
.
hasBeenBuilt
in class org.eclipse.core.internal.events.InternalBuilder
project
- the project to check against in the current build ordertrue
if the given project has been built in this
iteration, and false
otherwise.needRebuild()
public final boolean isInterrupted()
isInterrupted
in class org.eclipse.core.internal.events.InternalBuilder
true
if the build cycle has been interrupted, and
false
otherwise.public final void needRebuild()
This is an advanced feature that builders should use with caution. This can cause workspace builds to iterate until no more builders require rebuilds.
needRebuild
in class org.eclipse.core.internal.events.InternalBuilder
hasBeenBuilt(IProject)
public void setInitializationData(IConfigurationElement config, String propertyName, Object data) throws CoreException
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")); } }
setInitializationData
in interface IExecutableExtension
config
- the configuration element used to trigger this execution.
It can be queried by the executable extension for specific
configuration propertiespropertyName
- 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
.CoreException
- if fails.IConfigurationElement.createExecutableExtension(String)
protected void startupOnInitialize()
setInitializationData
has been called. The
default implementation should be called by all overriding methods.startupOnInitialize
in class org.eclipse.core.internal.events.InternalBuilder
setInitializationData(IConfigurationElement, String, Object)
public ISchedulingRule getRule(int kind, Map<String,String> args)
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:
null
it must be "contained" in the workspace root rule.
I.e. ISchedulingRule.contains(ISchedulingRule)
must return
true
when invoked on the workspace root with the builder rule.
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.
kind
- the kind of build being requested. Valid values include:
FULL_BUILD
- indicates a full build.INCREMENTAL_BUILD
- indicates an incremental build.AUTO_BUILD
- indicates an automatically triggered
incremental build (autobuilding on).CLEAN_BUILD
- indicates a clean request.args
- a table of builder-specific arguments keyed by argument name
(key type: String
, value type: String
);
null
is equivalent to an empty map.null
to indicate that no protection against resource
modification during the build is needed.public final IBuildContext getContext()
build(int, Map, IProgressMonitor)
This can be used to discover which build configurations are being built before and after this build configuration.
getContext
in class org.eclipse.core.internal.events.InternalBuilder
getContext()
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.