org.eclipse.jdt/org.eclipse.jdt.core/3.20.0 : org/eclipse/jdt/core/WorkingCopyOwner.java

WorkingCopyOwner
http://www.eclipse.org/jdt: Java Development Tools Core (Eclipse Foundation)
Eclipse Public License - v 2.0
Copyright (c) 2000, 2019 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 Corporation - initial API and implementation
/*******************************************************************************
 * Copyright (c) 2000, 2019 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 Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jdt.core;

import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.jdt.core.compiler.CharOperation;
import org.eclipse.jdt.internal.core.BufferManager;
import org.eclipse.jdt.internal.core.CompilationUnit;
import org.eclipse.jdt.internal.core.DefaultWorkingCopyOwner;
import org.eclipse.jdt.internal.core.ExternalJavaProject;
import org.eclipse.jdt.internal.core.PackageFragment;
import org.eclipse.jdt.internal.core.PackageFragmentRoot;

The owner of an ICompilationUnit handle in working copy mode. An owner is used to identify a working copy and to create its buffer.  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. IType.resolveType(String, WorkingCopyOwner). Clients can also override the default implementation of createBuffer(ICompilationUnit). 

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.

See Also: ICompilationUnit.becomeWorkingCopy(IProgressMonitor)
ICompilationUnit.discardWorkingCopy()
ICompilationUnit.getWorkingCopy(IProgressMonitor)
Since: 3.0/**
 * The owner of an {@link ICompilationUnit} 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. {@link IType#resolveType(String, WorkingCopyOwner)}.
 * Clients can also override the default implementation of {@link #createBuffer(ICompilationUnit)}.
 * </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 ICompilationUnit#becomeWorkingCopy(org.eclipse.core.runtime.IProgressMonitor)
 * @see ICompilationUnit#discardWorkingCopy()
 * @see ICompilationUnit#getWorkingCopy(org.eclipse.core.runtime.IProgressMonitor)
 * @since 3.0
 */
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 createBuffer(ICompilationUnit)
method is used by the primary working copy owner. It doesn't replace the internal primary
working owner.

This method is for internal use by the jdt-related plug-ins.
Clients outside of the jdt should not reference this method.

Params: primaryBufferProvider – the primary buffer provider/**
	 * 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(ICompilationUnit)</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 jdt-related plug-ins.
	 * Clients outside of the jdt 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 null).

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.

Params: workingCopy – the working copy of the buffer
See Also: IBuffer
Returns: IBuffer the created buffer for the given working copy/**
	 * 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(ICompilationUnit workingCopy) {

		return BufferManager.createBuffer(workingCopy);
	}

	Returns the problem requestor used by a working copy of this working copy owner.

By default, no problem requestor is configured. Clients can override this
method to provide a requestor.

Params: workingCopy – The problem requestor used for the given working copy.
Returns: the problem requestor to be used by working copies of this working
copy owner or null if no problem requestor is configured.
Since: 3.3/**
	 * Returns the problem requestor used by a working copy of this working copy owner.
	 * <p>
	 * By default, no problem requestor is configured. Clients can override this
	 * method to provide a requestor.
	 * </p>
	 *
	 * @param workingCopy The problem requestor used for the given working copy.
	 * @return the problem requestor to be used by working copies of this working
	 * copy owner or <code>null</code> if no problem requestor is configured.
	 *
	 * @since 3.3
	 */
	public IProblemRequestor getProblemRequestor(ICompilationUnit workingCopy) {
		return null;
	}
	
	Returns the source of the compilation unit that defines the given type in
the given package, or null if the type is unknown to this
owner.
This method is called before the normal lookup (i.e. before looking 
at the project's classpath and before looking at the working copies of this 
owner.)
This allows to provide types that are not normally available, or to hide 
types that would normally be available by returning an empty source for 
the given type and package.
Example of use:
WorkingCopyOwner owner = new WorkingCopyOwner() {
  public String findSource(String typeName, String packageName) {
    if ("to.be".equals(packageName) && "Generated".equals(typeName)) {
      return
        "package to.be;\n" +
        "public class Generated {\n" +
        "}";
    }
    return super.findSource(typeName, packageName);
  }
  public boolean isPackage(String[] pkg) {
    switch (pkg.length) {
    case 1:
      return "to".equals(pkg[0]);
    case 2:
      return "to".equals(pkg[0]) && "be".equals(pkg[1]);
    }
    return false;
  }
};
// Working copy on X.java with the following contents:
//    public class X extends to.be.Generated {
//    }
ICompilationUnit workingCopy = ... 
ASTParser parser = ASTParser.newParser(AST.JLS3);
parser.setSource(workingCopy);
parser.setResolveBindings(true);
parser.setWorkingCopyOwner(owner);
CompilationUnit cu = (CompilationUnit) parser.createAST(null);
assert cu.getProblems().length == 0;

Params: typeName – the simple name of the type to lookup
packageName – the dot-separated name of the package of type
See Also: isPackage(String[])
Returns: the source of the compilation unit that defines the given type in
the given package, or null if the type is unknown
Since: 3.5/**
	 * Returns the source of the compilation unit that defines the given type in
	 * the given package, or <code>null</code> if the type is unknown to this
	 * owner.
	 * <p>This method is called before the normal lookup (i.e. before looking 
	 * at the project's classpath and before looking at the working copies of this 
	 * owner.)</p>
	 * <p>This allows to provide types that are not normally available, or to hide 
	 * types that would normally be available by returning an empty source for 
	 * the given type and package.</p>
	 * <p>Example of use:
	 * <pre>
	 * WorkingCopyOwner owner = new WorkingCopyOwner() {
	 *   public String findSource(String typeName, String packageName) {
	 *     if ("to.be".equals(packageName) && "Generated".equals(typeName)) {
	 *       return
	 *         "package to.be;\n" +
	 *         "public class Generated {\n" +
	 *         "}";
	 *     }
	 *     return super.findSource(typeName, packageName);
	 *   }
	 *   public boolean isPackage(String[] pkg) {
	 *     switch (pkg.length) {
	 *     case 1:
	 *       return "to".equals(pkg[0]);
	 *     case 2:
	 *       return "to".equals(pkg[0]) && "be".equals(pkg[1]);
	 *     }
	 *     return false;
	 *   }
	 * };
	 * // Working copy on X.java with the following contents:
	 * //    public class X extends to.be.Generated {
	 * //    }
	 * ICompilationUnit workingCopy = ... 
	 * ASTParser parser = ASTParser.newParser(AST.JLS3);
	 * parser.setSource(workingCopy);
	 * parser.setResolveBindings(true);
	 * parser.setWorkingCopyOwner(owner);
	 * CompilationUnit cu = (CompilationUnit) parser.createAST(null);
	 * assert cu.getProblems().length == 0;
	 * </pre>
	 * 
	 * @param typeName the simple name of the type to lookup
	 * @param packageName the dot-separated name of the package of type
	 * @return the source of the compilation unit that defines the given type in
	 * the given package, or <code>null</code> if the type is unknown
	 * @see #isPackage(String[])
	 * @since 3.5
	 */
	public String findSource(String typeName, String packageName) {
		return null;
	}
	
	Returns whether the given package segments represent a package.
This method is called before the normal lookup (i.e. before looking 
at the project's classpath and before looking at the working copies of this 
owner.)
This allows to provide packages that are not normally available.
If false is returned, then normal lookup is used on 
this package.
Params: pkg – the segments of a package to lookup
See Also: findSource(String, String)
Returns: whether the given package segments represent a package.
Since: 3.5/**
	 * Returns whether the given package segments represent a package.
	 * <p>This method is called before the normal lookup (i.e. before looking 
	 * at the project's classpath and before looking at the working copies of this 
	 * owner.)</p>
	 * <p>This allows to provide packages that are not normally available.</p>
	 * <p>If <code>false</code> is returned, then normal lookup is used on 
	 * this package.</p>
	 * 
	 * @param pkg the segments of a package to lookup
	 * @return whether the given package segments represent a package.
	 * @see #findSource(String, String)
	 * @since 3.5
	 */
	public boolean isPackage(String[] pkg) {
		return false;
	}

	Returns a new working copy with the given name using this working copy owner to
create its buffer.

This working copy always belongs to the default package in a package
fragment root that corresponds to its Java project, and this Java project never exists.
However this Java project has the given classpath that is used when resolving names
in this working copy.

A DOM AST created using this working copy will have bindings resolved using the given
classpath, and problem are reported to the given problem requestor.

JavaCore#getOptions() is used to create the DOM AST as it is not
possible to set the options on the non-existing Java project.
 When the working copy instance is created, an added delta is reported on this working copy. 
 Once done with the working copy, users of this method must discard it using ICompilationUnit.discardWorkingCopy(). 
 Note that when such working copy is committed, only its buffer is saved (see IBuffer.save(IProgressMonitor, boolean)) but no resource is created. 

This method is not intended to be overriden by clients.

Params: name – the name of the working copy (e.g. "X.java")
classpath – the classpath used to resolve names in this working copy
problemRequestor – a requestor which will get notified of problems detected during
	reconciling as they are discovered. The requestor can be set to null indicating
	that the client is not interested in problems.
monitor – a progress monitor used to report progress while opening the working copy
	or null if no progress should be reported
Throws: JavaModelException – if the contents of this working copy can
  not be determined.
See Also: ICompilationUnit.becomeWorkingCopy(IProblemRequestor, IProgressMonitor)
Returns: a new working copy
Since: 3.2
Deprecated: Use newWorkingCopy(String, IClasspathEntry[], IProgressMonitor) instead. Note that if this deprecated method is used, problems may be reported twice if the given requestor is not the same as the current working copy owner one./**
	 * 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 Java project, and this Java project never exists.
	 * However this Java project has the given classpath 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
	 * classpath, and problem are reported to the given problem requestor.
	 * </p><p>
	 * <code>JavaCore#getOptions()</code> is used to create the DOM AST as it is not
	 * possible to set the options on the non-existing Java project.
	 * </p><p>
	 * When the working copy instance is created, an {@link IJavaElementDelta#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 ICompilationUnit#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 classpath the classpath 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 JavaModelException if the contents of this working copy can
	 *   not be determined.
	 * @return a new working copy
	 * @see ICompilationUnit#becomeWorkingCopy(IProblemRequestor, IProgressMonitor)
	 * @since 3.2
	 *
	 * @deprecated Use {@link #newWorkingCopy(String, IClasspathEntry[], IProgressMonitor)} instead.
	 * 	Note that if this deprecated method is used, problems may be reported twice
	 * 	if the given requestor is not the same as the current working copy owner one.
	 */
	public final ICompilationUnit newWorkingCopy(String name, IClasspathEntry[] classpath, IProblemRequestor problemRequestor, IProgressMonitor monitor) throws JavaModelException {
		ExternalJavaProject project = new ExternalJavaProject(classpath);
		IPackageFragment parent = ((PackageFragmentRoot) project.getPackageFragmentRoot(project.getProject())).getPackageFragment(CharOperation.NO_STRINGS);
		CompilationUnit result = new CompilationUnit((PackageFragment) parent, name, this);
		result.becomeWorkingCopy(problemRequestor, monitor);
		return result;
	}

	Returns a new working copy with the given name using this working copy owner to
create its buffer.

This working copy always belongs to the default package in a package
fragment root that corresponds to its Java project, and this Java project never exists.
However this Java project has the given classpath that is used when resolving names
in this working copy.

If a DOM AST is created using this working copy, then given classpath will be used
 if bindings need to be resolved. Problems will be reported to the problem requestor
of the current working copy owner problem if it is not null.
 Options used to create the DOM AST are got from JavaCore.getOptions() as it is not possible to set the options on a non-existing Java project. 
 When the working copy instance is created, an added delta is reported on this working copy. 
 Once done with the working copy, users of this method must discard it using ICompilationUnit.discardWorkingCopy(). 
 Note that when such working copy is committed, only its buffer is saved (see IBuffer.save(IProgressMonitor, boolean)) but no resource is created. 

This method is not intended to be overriden by clients.

Params: name – the name of the working copy (e.g. "X.java")
classpath – the classpath used to resolve names in this working copy
monitor – a progress monitor used to report progress while opening the working copy
	or null if no progress should be reported
Throws: JavaModelException – if the contents of this working copy can
  not be determined.
See Also: ICompilationUnit.becomeWorkingCopy(IProgressMonitor)
Returns: a new working copy
Since: 3.3/**
	 * 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 Java project, and this Java project never exists.
	 * However this Java project has the given classpath that is used when resolving names
	 * in this working copy.
	 * </p><p>
	 * If a DOM AST is created using this working copy, then given classpath will be used
	 *  if bindings need to be resolved. Problems will be reported to the problem requestor
	 * of the current working copy owner problem if it is not <code>null</code>.
	 * </p><p>
	 * Options used to create the DOM AST are got from {@link JavaCore#getOptions()}
	 * as it is not possible to set the options on a non-existing Java project.
	 * </p><p>
	 * When the working copy instance is created, an {@link IJavaElementDelta#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 ICompilationUnit#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 classpath the classpath used to resolve names in this working copy
	 * @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 JavaModelException if the contents of this working copy can
	 *   not be determined.
	 * @return a new working copy
	 * @see ICompilationUnit#becomeWorkingCopy(IProgressMonitor)
	 *
	 * @since 3.3
	 */
	public final ICompilationUnit newWorkingCopy(String name, IClasspathEntry[] classpath, IProgressMonitor monitor) throws JavaModelException {
		ExternalJavaProject project = new ExternalJavaProject(classpath);
		IPackageFragment parent = ((PackageFragmentRoot) project.getPackageFragmentRoot(project.getProject())).getPackageFragment(CharOperation.NO_STRINGS);
		CompilationUnit result = new CompilationUnit((PackageFragment) parent, name, this);
		result.becomeWorkingCopy(getProblemRequestor(result), monitor);
		return result;
	}

}
See Also:	ICompilationUnit.becomeWorkingCopy(IProgressMonitor) ICompilationUnit.discardWorkingCopy() ICompilationUnit.getWorkingCopy(IProgressMonitor)
Since:	3.0
Params:	workingCopy – the working copy of the buffer
See Also:	IBuffer
Returns:	IBuffer the created buffer for the given working copy
Params:	workingCopy – The problem requestor used for the given working copy.
Returns:	the problem requestor to be used by working copies of this working copy owner or `null` if no problem requestor is configured.
Since:	3.3
Params:	typeName – the simple name of the type to lookup packageName – the dot-separated name of the package of type
See Also:	isPackage(String[])
Returns:	the source of the compilation unit that defines the given type in the given package, or `null` if the type is unknown
Since:	3.5
Params:	pkg – the segments of a package to lookup
See Also:	findSource(String, String)
Returns:	whether the given package segments represent a package.
Since:	3.5
Params:	name – the name of the working copy (e.g. "X.java") classpath – the classpath used to resolve names in this working copy problemRequestor – a requestor which will get notified of problems detected during reconciling as they are discovered. The requestor can be set to `null` indicating that the client is not interested in problems. monitor – a progress monitor used to report progress while opening the working copy or `null` if no progress should be reported
Throws:	JavaModelException – if the contents of this working copy can not be determined.
See Also:	ICompilationUnit.becomeWorkingCopy(IProblemRequestor, IProgressMonitor)
Returns:	a new working copy
Since:	3.2
Deprecated:	Use `newWorkingCopy(String, IClasspathEntry[], IProgressMonitor)` instead. Note that if this deprecated method is used, problems may be reported twice if the given requestor is not the same as the current working copy owner one.
/

org.eclipse.jdt/ org.eclipse.jdt.core/ 3.20.0/ org/eclipse/jdt/core/WorkingCopyOwner.java
