Copyright (c) 2004, 2015 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 - Initial API and implementation
/*******************************************************************************
 *  Copyright (c) 2004, 2015 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 - Initial API and implementation
 *******************************************************************************/
package org.eclipse.core.resources;

import org.eclipse.core.runtime.ICoreRunnable;
import org.eclipse.core.runtime.jobs.ISchedulingRule;

A resource rule factory returns scheduling rules for API methods
that modify the workspace. These rules can be used when creating jobs
or other operations that perform a series of modifications on the workspace.
This allows clients to implement two phase commit semantics, where all
necessary rules are obtained prior to executing a long running operation.

Note that simple use of the workspace APIs does not require use of scheduling
rules.  All workspace API methods that modify the workspace will automatically
obtain any scheduling rules needed to perform the modification.  However, if you
are aggregating a set of changes to the workspace using WorkspaceJob
or ICoreRunnable you can use scheduling rules to lock a
portion of the workspace for the duration of the job or runnable.  If you
provide a non-null scheduling rule, a runtime exception will occur if you try to
modify a portion of the workspace that is not covered by the rule for the runnable or job.

If more than one rule is needed, they can be aggregated using the
MultiRule.combine method.  Simplifying a group of rules does not change
the set of resources that are covered, but can improve job scheduling performance.

Note that null is a valid scheduling rule (indicating that no
resources need to be locked), and thus all methods in this class may
return null.
See Also:
WorkspaceJob
IWorkspace.run(ICoreRunnable, ISchedulingRule, int, IProgressMonitor)
MultiRule.combine(ISchedulingRule, ISchedulingRule)
Since:
3.0
@noimplement
This interface is not intended to be implemented by clients.
@noextend
This interface is not intended to be extended by clients./**
 * A resource rule factory returns scheduling rules for API methods
 * that modify the workspace. These rules can be used when creating jobs
 * or other operations that perform a series of modifications on the workspace.
 * This allows clients to implement two phase commit semantics, where all
 * necessary rules are obtained prior to executing a long running operation.
 * <p>
 * Note that simple use of the workspace APIs does not require use of scheduling
 * rules.  All workspace API methods that modify the workspace will automatically
 * obtain any scheduling rules needed to perform the modification.  However, if you
 * are aggregating a set of changes to the workspace using <code>WorkspaceJob</code>
 * or <code>ICoreRunnable</code> you can use scheduling rules to lock a
 * portion of the workspace for the duration of the job or runnable.  If you
 * provide a non-null scheduling rule, a runtime exception will occur if you try to
 * modify a portion of the workspace that is not covered by the rule for the runnable or job.
 * <p>
 * If more than one rule is needed, they can be aggregated using the
 * <code>MultiRule.combine</code> method.  Simplifying a group of rules does not change
 * the set of resources that are covered, but can improve job scheduling performance.
 * <p>
 * Note that <code>null</code> is a valid scheduling rule (indicating that no
 * resources need to be locked), and thus all methods in this class may
 * return <code>null</code>.
 *
 * @see WorkspaceJob
 * @see IWorkspace#run(ICoreRunnable, ISchedulingRule, int, org.eclipse.core.runtime.IProgressMonitor)
 * @see org.eclipse.core.runtime.jobs.MultiRule#combine(ISchedulingRule, ISchedulingRule)
 * @since 3.0
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface IResourceRuleFactory {
	
Returns the scheduling rule that is required for creating a project, folder,
or file.
Params:
resource – the resource being created
Returns:
a scheduling rule, or null/**
	 * Returns the scheduling rule that is required for creating a project, folder,
	 * or file.
	 *
	 * @param resource the resource being created
	 * @return a scheduling rule, or <code>null</code>
	 */
	ISchedulingRule createRule(IResource resource);

	
Returns the scheduling rule that is required for building a project or the
entire workspace.
Returns:
a scheduling rule, or null/**
	 * Returns the scheduling rule that is required for building a project or the
	 * entire workspace.
	 *
	 * @return a scheduling rule, or <code>null</code>
	 */
	ISchedulingRule buildRule();

	
Returns the scheduling rule that is required for changing the charset
setting for a file or the default charset setting for a container.
Params:
resource – the resource for which the charset will be changed
Returns:
a scheduling rule, or null
Since:
3.1/**
	 * Returns the scheduling rule that is required for changing the charset
	 * setting for a file or the default charset setting for a container.
	 *
	 * @param resource the resource for which the charset will be changed
	 * @return a scheduling rule, or <code>null</code>
	 * @since 3.1
	 */
	ISchedulingRule charsetRule(IResource resource);

	
Returns the scheduling rule that is required for changing the derived flag
on a resource.
Params:
resource – the resource for which the derived flag will be changed
Returns:
a scheduling rule, or null
Since:
3.6/**
	 * Returns the scheduling rule that is required for changing the derived flag
	 * on a resource.
	 *
	 * @param resource the resource for which the derived flag will be changed
	 * @return a scheduling rule, or <code>null</code>
	 * @since 3.6
	 */
	ISchedulingRule derivedRule(IResource resource);

	
Returns the scheduling rule that is required for copying a resource.
Params:
source – the source of the copy
destination – the destination of the copy
Returns:
a scheduling rule, or null/**
	 * Returns the scheduling rule that is required for copying a resource.
	 *
	 * @param source the source of the copy
	 * @param destination the destination of the copy
	 * @return a scheduling rule, or <code>null</code>
	 */
	ISchedulingRule copyRule(IResource source, IResource destination);

	
Returns the scheduling rule that is required for deleting a resource.
Params:
resource – the resource to be deleted
Returns:
a scheduling rule, or null/**
	 * Returns the scheduling rule that is required for deleting a resource.
	 *
	 * @param resource the resource to be deleted
	 * @return a scheduling rule, or <code>null</code>
	 */
	ISchedulingRule deleteRule(IResource resource);

	
Returns the scheduling rule that is required for creating, modifying, or
deleting markers on a resource.
Params:
resource – the resource owning the marker to be modified
Returns:
a scheduling rule, or null/**
	 * Returns the scheduling rule that is required for creating, modifying, or
	 * deleting markers on a resource.
	 *
	 * @param resource the resource owning the marker to be modified
	 * @return a scheduling rule, or <code>null</code>
	 */
	ISchedulingRule markerRule(IResource resource);

	
Returns the scheduling rule that is required for modifying a resource. For files, modification includes setting and appending contents. For projects, modification includes opening or closing the project, or setting the project description using the IResource.AVOID_NATURE_CONFIG flag. For all resources touch is considered to be a modification.
Params:
resource – the resource being modified
Returns:
a scheduling rule, or null/**
	 * Returns the scheduling rule that is required for modifying a resource.
	 * For files, modification includes setting and appending contents. For
	 * projects, modification includes opening or closing the project, or
	 * setting the project description using the
	 * {@link IResource#AVOID_NATURE_CONFIG} flag. For all resources
	 * <code>touch</code> is considered to be a modification.
	 *
	 * @param resource the resource being modified
	 * @return a scheduling rule, or <code>null</code>
	 */
	ISchedulingRule modifyRule(IResource resource);

	
Returns the scheduling rule that is required for moving a resource.
Params:
source – the source of the move
destination – the destination of the move
Returns:
a scheduling rule, or null/**
	 * Returns the scheduling rule that is required for moving a resource.
	 *
	 * @param source the source of the move
	 * @param destination the destination of the move
	 * @return a scheduling rule, or <code>null</code>
	 */
	ISchedulingRule moveRule(IResource source, IResource destination);

	
Returns the scheduling rule that is required for performing
refreshLocal on a resource.
Params:
resource – the resource to refresh
Returns:
a scheduling rule, or null/**
	 * Returns the scheduling rule that is required for performing
	 * <code>refreshLocal</code> on a resource.
	 *
	 * @param resource the resource to refresh
	 * @return a scheduling rule, or <code>null</code>
	 */
	ISchedulingRule refreshRule(IResource resource);

	
Returns the scheduling rule that is required for a validateEdit
Params:
resources – the resources to be validated
Returns:
a scheduling rule, or null/**
	 * Returns the scheduling rule that is required for a <code>validateEdit</code>
	 *
	 * @param resources the resources to be validated
	 * @return a scheduling rule, or <code>null</code>
	 */
	ISchedulingRule validateEditRule(IResource[] resources);
}