/******************************************************************************* * Copyright (c) 2000, 2003 IBM Corporation and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Common Public License v1.0 * which accompanies this distribution, and is available at * http://www.eclipse.org/legal/cpl-v10.html * * Contributors: * IBM Corporation - initial API and implementation *******************************************************************************/ package net.sourceforge.phpdt.core; import org.eclipse.core.resources.IMarker; import org.eclipse.core.resources.IResource; import org.eclipse.core.runtime.IProgressMonitor; /** * Common protocol for Java elements that support working copies. *
* A working copy of a Java element acts just like a regular element (handle), * except it is not attached to an underlying resource. A working copy is not * visible to the rest of the Java model. Changes in a working copy's * buffer are not realized in a resource. To bring the Java model up-to-date with a working * copy's contents, an explicit commit must be performed on the working copy. * Other operations performed on a working copy update the * contents of the working copy's buffer but do not commit the contents * of the working copy. *
*
* Note: The contents of a working copy is determined when a working
* copy is created, based on the current content of the element the working
* copy is created from. If a working copy is an IOpenable
and is explicitly
* closed, the working copy's buffer will be thrown away. However, clients should not
* explicitly open and close working copies.
*
* The client that creates a working copy is responsible for
* destroying the working copy. The Java model will never automatically
* destroy or close a working copy. (Note that destroying a working copy
* does not commit it to the model, it only frees up the memory occupied by
* the element). After a working copy is destroyed, the working copy cannot
* be accessed again. Non-handle methods will throw a
* JavaModelException
indicating the Java element does not exist.
*
* A working copy cannot be created from another working copy.
* Calling getWorkingCopy
on a working copy returns the receiver.
*
* This interface is not intended to be implemented by clients. *
*/ public interface IWorkingCopy { /** * Commits the contents of this working copy to its original element * and underlying resource, bringing the Java model up-to-date with * the current contents of the working copy. * *It is possible that the contents of the original resource have changed
* since this working copy was created, in which case there is an update conflict.
* The value of the force
parameter effects the resolution of
* such a conflict:
true
- in this case the contents of this working copy are applied to
* the underlying resource even though this working copy was created before
* a subsequent change in the resourcefalse
- in this case a JavaModelException
is thrown* Since 2.1, a working copy can be created on a not-yet existing compilation * unit. In particular, such a working copy can then be committed in order to create * the corresponding compilation unit. *
* @param force a flag to handle the cases when the contents of the original resource have changed * since this working copy was created * @param monitor the given progress monitor * @exception JavaModelException if this working copy could not commit. Reasons include: *CoreException
occurred while updating an underlying resource
* IJavaModelException
s. Has
* no effect if this element is not a working copy.
*
* If this working copy is shared, it is destroyed only when the number of calls to
* destroy()
is the same as the number of calls to
* getSharedWorkingCopy(IProgressMonitor, IBufferFactory)
.
*
* When it is destroyed, a REMOVED IJavaElementDelta is reported on this * working copy. *
*/ void destroy(); /** * Finds the shared working copy for this element, given aIBuffer
factory.
* If no working copy has been created for this element associated with this
* buffer factory, returns null
.
*
* Users of this method must not destroy the resulting working copy.
*
* @param bufferFactory the given IBuffer
factory
* @return the found shared working copy for this element, null
if none
* @see IBufferFactory
* @since 2.0
*/
IJavaElement findSharedWorkingCopy(IBufferFactory bufferFactory);
/**
* Returns the original element the specified working copy element was created from,
* or null
if this is not a working copy element. This is a handle
* only method, the returned element may or may not exist.
*
* @return the original element the specified working copy element was created from,
* or null
if this is not a working copy element
*/
IJavaElement getOriginal(IJavaElement workingCopyElement);
/**
* Returns the original element this working copy was created from,
* or null
if this is not a working copy.
*
* @return the original element this working copy was created from,
* or null
if this is not a working copy
*/
IJavaElement getOriginalElement();
/**
* Finds the elements in this compilation unit that correspond to
* the given element.
* An element A corresponds to an element B if:
*
null
if no such java elements can be found
* or if the given element is not included in a compilation unit.
*
* @param element the given element
* @return the found elements in this compilation unit that correspond to the given element
* @since 2.0
*/
IJavaElement[] findElements(IJavaElement element);
/**
* Finds the primary type of this compilation unit (that is, the type with the same name as the
* compilation unit), or null
if no such a type exists.
*
* @return the found primary type of this compilation unit, or null
if no such a type exists
* @since 2.0
*/
IType findPrimaryType();
/**
* Returns a shared working copy on this element using the given factory to create
* the buffer, or this element if this element is already a working copy.
* This API can only answer an already existing working copy if it is based on the same
* original compilation unit AND was using the same buffer factory (that is, as defined by Object.equals
).
* * The life time of a shared working copy is as follows: *
getSharedWorkingCopy(...)
creates a new working copy for this
* elementdestroy()
decrements the internal counter.* Note that the buffer factory will be used for the life time of this working copy, that is if the * working copy is closed then reopened, this factory will be used. * The buffer will be automatically initialized with the original's compilation unit content * upon creation. *
* When the shared working copy instance is created, an ADDED IJavaElementDelta is reported on this
* working copy.
*
* @param monitor a progress monitor used to report progress while opening this compilation unit
* or null
if no progress should be reported
* @param factory the factory that creates a buffer that is used to get the content of the working copy
* or null
if the internal factory should be used
* @param 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.
* @exception JavaModelException if the contents of this element can
* not be determined.
* @return a shared working copy on this element using the given factory to create
* the buffer, or this element if this element is already a working copy
* @see IBufferFactory
* @see IProblemRequestor
* @since 2.0
*/
IJavaElement getSharedWorkingCopy(
IProgressMonitor monitor,
IBufferFactory factory,
IProblemRequestor problemRequestor)
throws JavaModelException;
/**
* Returns a new working copy of this element if this element is not
* a working copy, or this element if this element is already a working copy.
*
* Note: if intending to share a working copy amongst several clients, then
* #getSharedWorkingCopy
should be used instead.
*
* When the working copy instance is created, an ADDED IJavaElementDelta is * reported on this working copy. *
* Since 2.1, a working copy can be created on a not-yet existing compilation * unit. In particular, such a working copy can then be committed in order to create * the corresponding compilation unit. *
* @exception JavaModelException if the contents of this element can * not be determined. * @return a new working copy of this element if this element is not * a working copy, or this element if this element is already a working copy */ IJavaElement getWorkingCopy() throws JavaModelException; /** * Returns a new working copy of this element using the given factory to create * the buffer, or this element if this element is already a working copy. * Note that this factory will be used for the life time of this working copy, that is if the * working copy is closed then reopened, this factory will be reused. * The buffer will be automatically initialized with the original's compilation unit content * upon creation. *
* Note: if intending to share a working copy amongst several clients, then
* #getSharedWorkingCopy
should be used instead.
*
* When the working copy instance is created, an ADDED IJavaElementDelta is * reported on this working copy. *
* Since 2.1, a working copy can be created on a not-yet existing compilation * unit. In particular, such a working copy can then be committed in order to create * the corresponding compilation unit. *
* @param monitor a progress monitor used to report progress while opening this compilation unit * ornull
if no progress should be reported
* @param factory the factory that creates a buffer that is used to get the content of the working copy
* or null
if the internal factory should be used
* @param 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.
* @exception JavaModelException if the contents of this element can
* not be determined.
* @return a new working copy of this element using the given factory to create
* the buffer, or this element if this element is already a working copy
* @since 2.0
*/
IJavaElement getWorkingCopy(
IProgressMonitor monitor,
IBufferFactory factory,
IProblemRequestor problemRequestor)
throws JavaModelException;
/**
* Returns whether this working copy's original element's content
* has not changed since the inception of this working copy.
*
* @return true if this working copy's original element's content
* has not changed since the inception of this working copy, false otherwise
*/
boolean isBasedOn(IResource resource);
/**
* Returns whether this element is a working copy.
*
* @return true if this element is a working copy, false otherwise
*/
boolean isWorkingCopy();
/**
* Reconciles the contents of this working copy.
* It performs the reconciliation by locally caching the contents of
* the working copy, updating the contents, then creating a delta
* over the cached contents and the new contents, and finally firing
* this delta.
*
* If the working copy hasn't changed, then no problem will be detected,
* this is equivalent to IWorkingCopy#reconcile(false, null)
.
*
* Compilation problems found in the new contents are notified through the
* IProblemRequestor
interface which was passed at
* creation, and no longer as transient markers. Therefore this API will
* return null
.
*
* Note: It has been assumed that added inner types should * not generate change deltas. The implementation has been * modified to reflect this assumption. * * @exception JavaModelException if the contents of the original element * cannot be accessed. Reasons include: *
null
*/
IMarker[] reconcile() throws JavaModelException;
/**
* Reconciles the contents of this working copy.
* It performs the reconciliation by locally caching the contents of
* the working copy, updating the contents, then creating a delta
* over the cached contents and the new contents, and finally firing
* this delta.
* * The boolean argument allows to force problem detection even if the * working copy is already consistent. *
* Compilation problems found in the new contents are notified through the
* IProblemRequestor
interface which was passed at
* creation, and no longer as transient markers. Therefore this API answers
* nothing.
*
* Note: It has been assumed that added inner types should * not generate change deltas. The implementation has been * modified to reflect this assumption. * * @param forceProblemDetection boolean indicating whether problem should be recomputed * even if the source hasn't changed. * @param monitor a progress monitor * @exception JavaModelException if the contents of the original element * cannot be accessed. Reasons include: *
Note: This is the inverse of committing the content of the
* working copy to the original element with commit(boolean, IProgressMonitor)
.
*
* @exception JavaModelException if the contents of the original element
* cannot be accessed. Reasons include:
*