KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > resources > WorkspaceJob


1 /*******************************************************************************
2  * Copyright (c) 2003, 2005 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM - Initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.core.resources;
12
13 import org.eclipse.core.internal.resources.InternalWorkspaceJob;
14 import org.eclipse.core.runtime.*;
15 import org.eclipse.core.runtime.jobs.ISchedulingRule;
16
17 /**
18  * A job that makes an atomic modification to the workspace. Clients must
19  * implement the abstract method <code>runInWorkspace</code> instead
20  * of the usual <code>Job.run</code> method.
21  * <p>
22  * After running a method that modifies resources in the workspace,
23  * registered listeners receive after-the-fact notification of
24  * what just transpired, in the form of a resource change event.
25  * This method allows clients to call a number of
26  * methods that modify resources and only have resource
27  * change event notifications reported at the end of the entire
28  * batch.
29  * </p>
30  * <p>
31  * A WorkspaceJob is the asynchronous equivalent of IWorkspaceRunnable
32  * </p>
33  * <p>
34  * Note that the workspace is not locked against other threads during the execution
35  * of a workspace job. Other threads can be modifying the workspace concurrently
36  * with a workspace job. To obtain exclusive access to a portion of the workspace,
37  * set the scheduling rule on the job to be a resource scheduling rule. The
38  * interface <tt>IResourceRuleFactory</tt> is used to create a scheduling rule
39  * for a particular workspace modification operation.
40  * </p>
41  * @see IWorkspaceRunnable
42  * @see org.eclipse.core.resources.IResourceRuleFactory
43  * @see IWorkspace#run(IWorkspaceRunnable, ISchedulingRule, int, IProgressMonitor)
44  * @since 3.0
45  */
46 public abstract class WorkspaceJob extends InternalWorkspaceJob {
47     /**
48      * Creates a new workspace job.
49      * @param name the name of the job
50      */
51     public WorkspaceJob(String JavaDoc name) {
52         super(name);
53     }
54
55     /**
56      * Runs the operation, reporting progress to and accepting
57      * cancelation requests from the given progress monitor.
58      * <p>
59      * Implementors of this method should check the progress monitor
60      * for cancelation when it is safe and appropriate to do so. The cancelation
61      * request should be propagated to the caller by throwing
62      * <code>OperationCanceledException</code>.
63      * </p>
64      *
65      * @param monitor a progress monitor, or <code>null</code> if progress
66      * reporting and cancelation are not desired
67      * @return the result of running the operation
68      * @exception CoreException if this operation fails.
69      */
70     public abstract IStatus runInWorkspace(IProgressMonitor monitor) throws CoreException;
71 }
72
Popular Tags