/*******************************************************************************
 * Copyright (c) 2008, 2010 Freescale Semiconductor 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:
 *     Serge Beauchamp (Freescale Semiconductor) - initial API and implementation
 *     IBM - ongoing development
 *******************************************************************************/
package org.eclipse.core.resources;

import org.eclipse.core.runtime.*;

/**
 * A description of a resource filter.
 *
 * A filter determines which file system objects will be visible when a local refresh is
 * performed for an IContainer.
 *
 * @see IContainer#getFilters()
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 * @since 3.6
 */
public interface IResourceFilterDescription {

	/*====================================================================
	 * Constants defining which members are wanted:
	 *====================================================================*/

	/**
	 * Flag for resource filters indicating that the filter list includes only
	 * the files matching the filters. All INCLUDE_ONLY filters are applied to
	 * the resource list with an logical OR operation.
	 */
	int INCLUDE_ONLY = 1;

	/**
	 * Flag for resource filters indicating that the filter list excludes all
	 * the files matching the filters.  All EXCLUDE_ALL filters are applied to
	 * the resource list with an logical AND operation.
	 */
	int EXCLUDE_ALL = 2;

	/**
	 * Flag for resource filters indicating that this filter applies to files.
	 */
	int FILES = 4;

	/**
	 * Flag for resource filters indicating that this filter applies to folders.
	 */
	int FOLDERS = 8;

	/**
	 * Flag for resource filters indicating that the container children of the
	 * path inherit from this filter as well.
	 */
	int INHERITABLE = 16;

	/**
	 * Returns the description of the file info matcher corresponding to this resource
	 * filter.
	 * @return the file info matcher description for this resource filter
	 */
	FileInfoMatcherDescription getFileInfoMatcherDescription();

	/**
	 * Return the resource towards which this filter is set.
	 *
	 * @return the resource towards which this filter is set
	 */
	IResource getResource();

	/**
	 * Return the filter type, either INCLUDE_ONLY or EXCLUDE_ALL
	 *
	 * @return (INCLUDE_ONLY or EXCLUDE_ALL) and/or INHERITABLE
	 */
	int getType();

	/**
	 * Deletes this filter description from its associated resource.
	 * <p>
	 * The {@link IResource#BACKGROUND_REFRESH} update flag controls when
	 * changes to the resource hierarchy under this container resulting from the filter
	 * removal take effect. If this flag is specified, the resource hierarchy is updated in a
	 * separate thread after this method returns. If the flag is not specified, any resource
	 * changes resulting from the filter removal will occur before this method returns.
	 * </p>
	 * <p>
	 * This operation changes resources; these changes will be reported
	 * in a subsequent resource change event that will include an indication
	 * of any resources that have been added as a result of the filter removal.
	 * </p>
	 * <p>
	 * This operation is long-running; progress and cancellation are provided
	 * by the given progress monitor.
	 * </p>
	 *
	 * @param updateFlags bit-wise or of update flag constants
	 *   ({@link IResource#BACKGROUND_REFRESH})
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception CoreException if this filter could not be removed. Reasons include:
	 * <ul>
	 * <li> Resource changes are disallowed during certain types of resource change
	 *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
	 * </ul>
	 * @exception OperationCanceledException if the operation is canceled.
	 * Cancelation can occur even if no progress monitor is provided.
	 * @see IContainer#getFilters()
	 * @see IContainer#createFilter(int, FileInfoMatcherDescription, int, IProgressMonitor)
	 */
	void delete(int updateFlags, IProgressMonitor monitor) throws CoreException;

}