Copyright (c) 2000, 2014 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
IBM Corporation - initial API and implementation
/*******************************************************************************
* Copyright (c) 2000, 2014 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.core.resources;
import org.eclipse.core.runtime.IProgressMonitor;
Resource change events describe changes to resources.
There are currently five different types of resource change events:
-
Before-the-fact batch reports of arbitrary creations,
deletions and modifications to one or more resources expressed
as a hierarchical resource delta. Event type is
PRE_BUILD, and getDelta returns
the hierarchical delta rooted at the workspace root.
The getBuildKind method returns
the kind of build that is about to occur, and the getSource
method returns the scope of the build (either the workspace or a single project).
These events are broadcast to interested parties immediately
before each build operation. If autobuilding is not enabled, these events still
occur at times when autobuild would have occurred. The workspace is open
for change during notification of these events. The delta reported in this event
cycle is identical across all listeners registered for this type of event.
Resource changes attempted during a PRE_BUILD callback
must be done in the thread doing the notification.
-
After-the-fact batch reports of arbitrary creations,
deletions and modifications to one or more resources expressed
as a hierarchical resource delta. Event type is
POST_BUILD, and getDelta returns
the hierarchical delta rooted at the workspace root.
The getBuildKind method returns
the kind of build that occurred, and the getSource
method returns the scope of the build (either the workspace or a single project).
These events are broadcast to interested parties at the end of every build operation.
If autobuilding is not enabled, these events still occur at times when autobuild
would have occurred. The workspace is open for change during notification of
these events. The delta reported in this event cycle is identical across
all listeners registered for this type of event.
Resource changes attempted during a POST_BUILD callback
must be done in the thread doing the notification.
-
After-the-fact batch reports of arbitrary creations,
deletions and modifications to one or more resources expressed
as a hierarchical resource delta. Event type is
POST_CHANGE, and getDelta returns
the hierarchical delta. The resource delta is rooted at the
workspace root. These events are broadcast to interested parties after
a set of resource changes and happen whether or not autobuilding is enabled.
The workspace is closed for change during notification of these events.
The delta reported in this event cycle is identical across all listeners registered for
this type of event.
-
Before-the-fact reports of the impending closure of a single
project. Event type is
PRE_CLOSE,
and getResource returns the project being closed.
The workspace is closed for change during notification of these events.
-
Before-the-fact reports of the impending deletion of a single
project. Event type is
PRE_DELETE,
and getResource returns the project being deleted.
The workspace is closed for change during notification of these events.
-
Before-the-fact reports of the impending refresh of a single project or the workspace.
Event type is
PRE_REFRESH and the getSource
method returns the scope of the refresh (either the workspace or a single project).
If the event is fired by a project refresh the getResource
method returns the project being refreshed.
The workspace is closed for changes during notification of these events.
In order to handle additional event types that may be introduced
in future releases of the platform, clients should do not write code
that presumes the set of event types is closed.
@noimplement This interface is not intended to be implemented by clients. @noextend This interface is not intended to be extended by clients.
/**
* Resource change events describe changes to resources.
* <p>
* There are currently five different types of resource change events:
* <ul>
* <li>
* Before-the-fact batch reports of arbitrary creations,
* deletions and modifications to one or more resources expressed
* as a hierarchical resource delta. Event type is
* <code>PRE_BUILD</code>, and <code>getDelta</code> returns
* the hierarchical delta rooted at the workspace root.
* The <code>getBuildKind</code> method returns
* the kind of build that is about to occur, and the <code>getSource</code>
* method returns the scope of the build (either the workspace or a single project).
* These events are broadcast to interested parties immediately
* before each build operation. If autobuilding is not enabled, these events still
* occur at times when autobuild would have occurred. The workspace is open
* for change during notification of these events. The delta reported in this event
* cycle is identical across all listeners registered for this type of event.
* Resource changes attempted during a <code>PRE_BUILD</code> callback
* <b>must</b> be done in the thread doing the notification.
* </li>
* <li>
* After-the-fact batch reports of arbitrary creations,
* deletions and modifications to one or more resources expressed
* as a hierarchical resource delta. Event type is
* <code>POST_BUILD</code>, and <code>getDelta</code> returns
* the hierarchical delta rooted at the workspace root.
* The <code>getBuildKind</code> method returns
* the kind of build that occurred, and the <code>getSource</code>
* method returns the scope of the build (either the workspace or a single project).
* These events are broadcast to interested parties at the end of every build operation.
* If autobuilding is not enabled, these events still occur at times when autobuild
* would have occurred. The workspace is open for change during notification of
* these events. The delta reported in this event cycle is identical across
* all listeners registered for this type of event.
* Resource changes attempted during a <code>POST_BUILD</code> callback
* <b>must</b> be done in the thread doing the notification.
* </li>
* <li>
* After-the-fact batch reports of arbitrary creations,
* deletions and modifications to one or more resources expressed
* as a hierarchical resource delta. Event type is
* <code>POST_CHANGE</code>, and <code>getDelta</code> returns
* the hierarchical delta. The resource delta is rooted at the
* workspace root. These events are broadcast to interested parties after
* a set of resource changes and happen whether or not autobuilding is enabled.
* The workspace is closed for change during notification of these events.
* The delta reported in this event cycle is identical across all listeners registered for
* this type of event.
* </li>
* <li>
* Before-the-fact reports of the impending closure of a single
* project. Event type is <code>PRE_CLOSE</code>,
* and <code>getResource</code> returns the project being closed.
* The workspace is closed for change during notification of these events.
* </li>
* <li>
* Before-the-fact reports of the impending deletion of a single
* project. Event type is <code>PRE_DELETE</code>,
* and <code>getResource</code> returns the project being deleted.
* The workspace is closed for change during notification of these events.
* </li>
* <li>
* Before-the-fact reports of the impending refresh of a single project or the workspace.
* Event type is <code>PRE_REFRESH</code> and the <code>getSource</code>
* method returns the scope of the refresh (either the workspace or a single project).
* If the event is fired by a project refresh the <code>getResource</code>
* method returns the project being refreshed.
* The workspace is closed for changes during notification of these events.
* </li>
* </ul>
* <p>
* In order to handle additional event types that may be introduced
* in future releases of the platform, clients should do not write code
* that presumes the set of event types is closed.
* </p>
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface IResourceChangeEvent {
Event type constant (bit mask) indicating an after-the-fact
report of creations, deletions, and modifications
to one or more resources expressed as a hierarchical
resource delta as returned by getDelta.
See class comments for further details.
See Also: - getType()
- getDelta()
/**
* Event type constant (bit mask) indicating an after-the-fact
* report of creations, deletions, and modifications
* to one or more resources expressed as a hierarchical
* resource delta as returned by <code>getDelta</code>.
* See class comments for further details.
*
* @see #getType()
* @see #getDelta()
*/
int POST_CHANGE = 1;
Event type constant (bit mask) indicating a before-the-fact
report of the impending closure of a single
project as returned by getResource.
See class comments for further details.
See Also: - getType()
- getResource()
/**
* Event type constant (bit mask) indicating a before-the-fact
* report of the impending closure of a single
* project as returned by <code>getResource</code>.
* See class comments for further details.
*
* @see #getType()
* @see #getResource()
*/
int PRE_CLOSE = 2;
Event type constant (bit mask) indicating a before-the-fact
report of the impending deletion of a single
project as returned by getResource.
See class comments for further details.
See Also: - getType()
- getResource()
/**
* Event type constant (bit mask) indicating a before-the-fact
* report of the impending deletion of a single
* project as returned by <code>getResource</code>.
* See class comments for further details.
*
* @see #getType()
* @see #getResource()
*/
int PRE_DELETE = 4;
Deprecated: This event type has been renamed to
PRE_BUILD
/**
* @deprecated This event type has been renamed to
* <code>PRE_BUILD</code>
*/
@Deprecated int PRE_AUTO_BUILD = 8;
Event type constant (bit mask) indicating a before-the-fact
report of a build. The event contains a hierarchical resource delta
as returned by getDelta.
See class comments for further details.
See Also: - getBuildKind()
- getSource()
Since: 3.0
/**
* Event type constant (bit mask) indicating a before-the-fact
* report of a build. The event contains a hierarchical resource delta
* as returned by <code>getDelta</code>.
* See class comments for further details.
*
* @see #getBuildKind()
* @see #getSource()
* @since 3.0
*/
int PRE_BUILD = 8;
Deprecated: This event type has been renamed to
POST_BUILD
/**
* @deprecated This event type has been renamed to
* <code>POST_BUILD</code>
*/
@Deprecated int POST_AUTO_BUILD = 16;
Event type constant (bit mask) indicating an after-the-fact
report of a build. The event contains a hierarchical resource delta
as returned by getDelta.
See class comments for further details.
See Also: - getBuildKind()
- getSource()
Since: 3.0
/**
* Event type constant (bit mask) indicating an after-the-fact
* report of a build. The event contains a hierarchical resource delta
* as returned by <code>getDelta</code>.
* See class comments for further details.
*
* @see #getBuildKind()
* @see #getSource()
* @since 3.0
*/
int POST_BUILD = 16;
Event type constant (bit mask) indicating a before-the-fact
report of refreshing the workspace or a project.
See class comments for further details.
See Also: - getType()
- getSource()
- getResource()
Since: 3.4
/**
* Event type constant (bit mask) indicating a before-the-fact
* report of refreshing the workspace or a project.
* See class comments for further details.
*
* @see #getType()
* @see #getSource()
* @see #getResource()
* @since 3.4
*/
int PRE_REFRESH = 32;
Returns all marker deltas of the specified type that are associated
with resource deltas for this event. If includeSubtypes
is false, only marker deltas whose type exactly matches
the given type are returned. Returns an empty array if there
are no matching marker deltas.
Calling this method is equivalent to walking the entire resource
delta for this event, and collecting all marker deltas of a given type.
The speed of this method will be proportional to the number of changed
markers, regardless of the size of the resource delta tree.
Params: - type – the type of marker to consider, or
null to indicate all types - includeSubtypes – whether or not to consider sub-types of the given type
Returns: an array of marker deltas Since: 2.0
/**
* Returns all marker deltas of the specified type that are associated
* with resource deltas for this event. If <code>includeSubtypes</code>
* is <code>false</code>, only marker deltas whose type exactly matches
* the given type are returned. Returns an empty array if there
* are no matching marker deltas.
* <p>
* Calling this method is equivalent to walking the entire resource
* delta for this event, and collecting all marker deltas of a given type.
* The speed of this method will be proportional to the number of changed
* markers, regardless of the size of the resource delta tree.
* </p>
* @param type the type of marker to consider, or <code>null</code> to indicate all types
* @param includeSubtypes whether or not to consider sub-types of the given type
* @return an array of marker deltas
* @since 2.0
*/
IMarkerDelta[] findMarkerDeltas(String type, boolean includeSubtypes);
Returns the kind of build that caused this event,
or 0 if not applicable to this type of event.
If the event is a PRE_BUILD or POST_BUILD
then this will be the kind of build that occurred to cause the event.
See Also: Returns: the kind of build, or 0 if not applicable Since: 3.1
/**
* Returns the kind of build that caused this event,
* or <code>0</code> if not applicable to this type of event.
* <p>
* If the event is a <code>PRE_BUILD</code> or <code>POST_BUILD</code>
* then this will be the kind of build that occurred to cause the event.
* </p>
*
* @see IProject#build(int, IProgressMonitor)
* @see IWorkspace#build(int, IProgressMonitor)
* @see IncrementalProjectBuilder#AUTO_BUILD
* @see IncrementalProjectBuilder#FULL_BUILD
* @see IncrementalProjectBuilder#INCREMENTAL_BUILD
* @see IncrementalProjectBuilder#CLEAN_BUILD
* @return the kind of build, or <code>0</code> if not applicable
* @since 3.1
*/
int getBuildKind();
Returns a resource delta, rooted at the workspace, describing the set
of changes that happened to resources in the workspace.
Returns null if not applicable to this type of event.
Returns: the resource delta, or null if not
applicable
/**
* Returns a resource delta, rooted at the workspace, describing the set
* of changes that happened to resources in the workspace.
* Returns <code>null</code> if not applicable to this type of event.
*
* @return the resource delta, or <code>null</code> if not
* applicable
*/
IResourceDelta getDelta();
Returns the resource in question or null
if not applicable to this type of event.
If the event is of type PRE_CLOSE,
PRE_DELETE, or PRE_REFRESH, then the resource
will be the affected project. Otherwise the resource will be null.
Returns: the resource, or null if not applicable
/**
* Returns the resource in question or <code>null</code>
* if not applicable to this type of event.
* <p>
* If the event is of type <code>PRE_CLOSE</code>,
* <code>PRE_DELETE</code>, or <code>PRE_REFRESH</code>, then the resource
* will be the affected project. Otherwise the resource will be <code>null</code>.
* </p>
* @return the resource, or <code>null</code> if not applicable
*/
IResource getResource();
Returns an object identifying the source of this event.
If the event is a PRE_BUILD, POST_BUILD,
or PRE_REFRESH then this will be the scope of the build (either the IWorkspace or a single IProject).
See Also: Returns: an object identifying the source of this event
/**
* Returns an object identifying the source of this event.
* <p>
* If the event is a <code>PRE_BUILD</code>, <code>POST_BUILD</code>,
* or <code>PRE_REFRESH</code> then this will be the scope of the build
* (either the {@link IWorkspace} or a single {@link IProject}).
* </p>
*
* @return an object identifying the source of this event
* @see java.util.EventObject
*/
Object getSource();
Returns the type of event being reported.
See Also: Returns: one of the event type constants
/**
* Returns the type of event being reported.
*
* @return one of the event type constants
* @see #POST_CHANGE
* @see #POST_BUILD
* @see #PRE_BUILD
* @see #PRE_CLOSE
* @see #PRE_DELETE
* @see #PRE_REFRESH
*/
int getType();
}