/*******************************************************************************
 * 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.
 * <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 <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 <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 <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
	 * <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 <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
	 * <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 <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 #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 <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 <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 <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 <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.
	 * <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.
	 *
	 * @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();
}