core/plugins/org.eclipse.dltk.core/model/org/eclipse/dltk/core/WorkingCopyOwner.java

/*******************************************************************************
 * Copyright (c) 2000, 2007 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
 *
 
 *******************************************************************************/
package org.eclipse.dltk.core;

import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.Path;
import org.eclipse.dltk.internal.core.BufferManager;
import org.eclipse.dltk.internal.core.DefaultWorkingCopyOwner;
import org.eclipse.dltk.internal.core.ExternalScriptProject;
import org.eclipse.dltk.internal.core.ModelElement;
import org.eclipse.dltk.internal.core.SourceModule;

/**
 * The owner of an <code>ISourceModule</code> handle in working copy mode. An
 * owner is used to identify a working copy and to create its buffer.
 * <p>
 * Clients should subclass this class to instantiate a working copy owner that
 * is specific to their need and that they can pass in to various APIs (e.g.
 * <code>IType.resolveType(String, WorkingCopyOwner)</code>. Clients can also
 * override the default implementation of
 * <code>createBuffer(ISourceModule)</code>.
 * </p>
 * <p>
 * Note: even though this class has no abstract method, which means that it
 * provides functional default behavior, it is still an abstract class, as
 * clients are intended to own their owner implementation.
 * </p>
 * 
 * @see ISourceModule#becomeWorkingCopy(IProblemRequestor,
 *      org.eclipse.core.runtime.IProgressMonitor)
 * @see ISourceModule#discardWorkingCopy()
 * @see ISourceModule#getWorkingCopy(org.eclipse.core.runtime.IProgressMonitor)
 * 
 */
public abstract class WorkingCopyOwner {

	/**
	 * Sets the buffer provider of the primary working copy owner. Note that
	 * even if the buffer provider is a working copy owner, only its
	 * <code>createBuffer(ISourceModule)</code> method is used by the primary
	 * working copy owner. It doesn't replace the internal primary working
	 * owner.
	 * <p>
	 * This method is for internal use by the dltk-related plug-ins. Clients
	 * outside of the dltk should not reference this method.
	 * </p>
	 * 
	 * @param primaryBufferProvider
	 *            the primary buffer provider
	 */
	public static void setPrimaryBufferProvider(
			WorkingCopyOwner primaryBufferProvider) {
		DefaultWorkingCopyOwner.PRIMARY.primaryBufferProvider = primaryBufferProvider;
	}

	/**
	 * Creates a buffer for the given working copy. The new buffer will be
	 * initialized with the contents of the underlying file if and only if it
	 * was not already initialized by the compilation owner (a buffer is
	 * uninitialized if its content is <code>null</code>).
	 * <p>
	 * Note: This buffer will be associated to the working copy for its entire
	 * life-cycle. Another working copy on same unit but owned by a different
	 * owner would not share the same buffer unless its owner decided to
	 * implement such a sharing behaviour.
	 * </p>
	 * 
	 * @param workingCopy
	 *            the working copy of the buffer
	 * @return IBuffer the created buffer for the given working copy
	 * @see IBuffer
	 */
	public IBuffer createBuffer(ISourceModule workingCopy) {
		return BufferManager.createBuffer(workingCopy);
	}

	/**
	 * Returns a new working copy with the given name using this working copy
	 * owner to create its buffer.
	 * <p>
	 * This working copy always belongs to the default package in a package
	 * fragment root that corresponds to its DLTK project, and this DLTK project
	 * never exists. However this DLTK project has the given buildpath that is
	 * used when resolving names in this working copy.
	 * </p>
	 * <p>
	 * A DOM AST created using this working copy will have bindings resolved
	 * using the given buildpath, and problem are reported to the given problem
	 * requestor.
	 * <p>
	 * </p>
	 * <code>DLTKCore#getOptions()</code> is used to create the DOM AST as it is
	 * not possible to set the options on the non-existing DLTK project. </p>
	 * <p>
	 * When the working copy instance is created, an
	 * {@link IModelElementDelta#ADDED added delta} is reported on this working
	 * copy.
	 * </p>
	 * <p>
	 * Once done with the working copy, users of this method must discard it
	 * using {@link ISourceModule#discardWorkingCopy()}.
	 * </p>
	 * <p>
	 * Note that when such working copy is committed, only its buffer is saved
	 * (see {@link IBuffer#save(IProgressMonitor, boolean)}) but no resource is
	 * created.
	 * </p>
	 * <p>
	 * This method is not intended to be overriden by clients.
	 * </p>
	 * 
	 * @param name
	 *            the name of the working copy (e.g. "X.java")
	 * @param buildpath
	 *            the buildpath used to resolve names in this working copy
	 * @param problemRequestor
	 *            a requestor which will get notified of problems detected
	 *            during reconciling as they are discovered. The requestor can
	 *            be set to <code>null</code> indicating that the client is not
	 *            interested in problems.
	 * @param monitor
	 *            a progress monitor used to report progress while opening the
	 *            working copy or <code>null</code> if no progress should be
	 *            reported
	 * @throws ModelException
	 *             if the contents of this working copy can not be determined.
	 * @return a new working copy
	 * @see ISourceModule#becomeWorkingCopy(IProblemRequestor, IProgressMonitor)
	 * 
	 */
	public final ISourceModule newWorkingCopy(String name,
			IBuildpathEntry[] buildpath, IProblemRequestor problemRequestor,
			IProgressMonitor monitor) throws ModelException {
		ExternalScriptProject project = new ExternalScriptProject(buildpath);
		IProjectFragment fragment = project.getProjectFragment(Path.EMPTY);
		IScriptFolder parent = fragment
				.getScriptFolder(IProjectFragment.DEFAULT_SCRIPT_FOLDER_NAME);
		SourceModule result = new SourceModule((ModelElement) parent, name,
				this);
		result.becomeWorkingCopy(problemRequestor, monitor);
		return result;
	}

}