X-Git-Url: http://secure.phpeclipse.com diff --git a/net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IWorkingCopy.java b/net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IWorkingCopy.java index da5c9d5..e30ec1d 100644 --- a/net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IWorkingCopy.java +++ b/net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IWorkingCopy.java @@ -1,15 +1,13 @@ /******************************************************************************* - * Copyright (c) 2000, 2001, 2002 International Business Machines Corp. and others. + * 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 v0.5 + * 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-v05.html + * http://www.eclipse.org/legal/cpl-v10.html * * Contributors: - * IBM Corporation - initial API - * IBM Corporation, 2002/03/01- added notion of shared working copy - * IBM Corporation, 2002/26/01- added notion of IProblemRequestor - ******************************************************************************/ + * IBM Corporation - initial API and implementation + *******************************************************************************/ package net.sourceforge.phpdt.core; import org.eclipse.core.resources.IMarker; @@ -21,329 +19,385 @@ import org.eclipse.core.runtime.IProgressMonitor; *
* 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. + * 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.
+ * 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.
+ * 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.
+ * 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
+ * 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:
*
CoreException
occurred while updating an underlying resource
- * 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.
+ * Destroys this working copy, closing its buffer and discarding its
+ * structure. Subsequent attempts to access non-handle information for this
+ * working copy will result in 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)
.
+ *
- * 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)
.
- * A REMOVED IJavaElementDelta is then reported on this working copy.
+ * When it is destroyed, a REMOVED IJavaElementDelta is reported on this
+ * working copy.
+ *
IBuffer
factory.
- * If no working copy has been created for this element associated with this
- * buffer factory, returns null
.
+ * Finds the shared working copy for this element, given a
+ * IBuffer
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.
+ * 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
+ * @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.
+ * 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
+ * @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.
+ * 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
+ * @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:
+
+ /**
+ * 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.
+ * Returns 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
+ * @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 (i.e. the type with the same name as the
- * compilation unit), or null
if no such a type exists.
+ * 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
+ * @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 (i.e. as defined by Object#equals
).
+ * 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
- * elementgetSharedWorkingCopy(...)
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, i.e. 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. + * 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. Reasons include:
- *
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;
-
+ 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
+ * 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. Reasons include: - *
+ * Note: if intending to share a working copy amongst several clients, then
* #getSharedWorkingCopy
should be used instead.
- *
- * @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. Reasons include:
- *
+ * 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;
-
+ 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.
+ * 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
+ * @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.
+ * 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
.
+ * 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.
+ * 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.
+ * 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:
- *
+ * 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:
+ *