org.eclipse.core.resources.WorkspaceJob Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2003, 2011 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM - Initial API and implementation
*******************************************************************************/
package org.eclipse.core.resources;
import org.eclipse.core.internal.resources.InternalWorkspaceJob;
import org.eclipse.core.runtime.*;
import org.eclipse.core.runtime.jobs.ISchedulingRule;
/**
* A job that makes an atomic modification to the workspace. Clients must
* implement the abstract method runInWorkspace
instead
* of the usual Job.run
method.
*
* After running a method that modifies resources in the workspace,
* registered listeners receive after-the-fact notification of
* what just transpired, in the form of a resource change event.
* This method allows clients to call a number of
* methods that modify resources and only have resource
* change event notifications reported at the end of the entire
* batch. This mechanism is used to avoid unnecessary builds
* and notifications.
*
*
* Platform may decide to perform notifications during the operation.
* The reason for this is that it is possible for multiple threads
* to be modifying the workspace concurrently. When one thread finishes modifying
* the workspace, a notification is required to prevent responsiveness problems,
* even if the other operation has not yet completed.
*
*
* A WorkspaceJob is the asynchronous equivalent of IWorkspaceRunnable
*
*
* Note that the workspace is not locked against other threads during the execution
* of a workspace job. Other threads can be modifying the workspace concurrently
* with a workspace job. To obtain exclusive access to a portion of the workspace,
* set the scheduling rule on the job to be a resource scheduling rule. The
* interface IResourceRuleFactory is used to create a scheduling rule
* for a particular workspace modification operation.
*
* @see IWorkspaceRunnable
* @see org.eclipse.core.resources.IResourceRuleFactory
* @see IWorkspace#run(IWorkspaceRunnable, ISchedulingRule, int, IProgressMonitor)
* @since 3.0
*/
public abstract class WorkspaceJob extends InternalWorkspaceJob {
/**
* Creates a new workspace job with the specified name. The job name is
* a human-readable value that is displayed to users. The name does not
* need to be unique, but it must not be null
.
*
* @param name the name of the job
*/
public WorkspaceJob(String name) {
super(name);
}
/**
* Runs the operation, reporting progress to and accepting
* cancelation requests from the given progress monitor.
*
* Implementors of this method should check the progress monitor
* for cancelation when it is safe and appropriate to do so. The cancelation
* request should be propagated to the caller by throwing
* OperationCanceledException
.
*
*
* @param monitor a progress monitor, or null
if progress
* reporting and cancelation are not desired
* @return the result of running the operation
* @exception CoreException if this operation fails.
*/
public abstract IStatus runInWorkspace(IProgressMonitor monitor) throws CoreException;
}