net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IWorkingCopy.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2001, 2002 International Business Machines Corp. and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Common Public License v0.5
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/cpl-v05.html
   7  *
   8  * Contributors:
   9  *    IBM Corporation - initial API
  10  *    IBM Corporation, 2002/03/01- added notion of shared working copy
  11  *    IBM Corporation, 2002/26/01- added notion of IProblemRequestor
  12  ******************************************************************************/
  13 package net.sourceforge.phpdt.core;
  14
  15 import org.eclipse.core.resources.IMarker;
  16 import org.eclipse.core.resources.IResource;
  17 import org.eclipse.core.runtime.IProgressMonitor;
  18
  19 /**
  20  * Common protocol for Java elements that support working copies.
  21  * <p>
  22  * A working copy of a Java element acts just like a regular element (handle),
  23  * except it is not attached to an underlying resource. A working copy is not
  24  * visible to the rest of the Java model. Changes in a working copy's
  25  * buffer are not realized in a resource. To bring the Java model up-to-date with a working
  26  * copy's contents, an explicit commit must be performed on the working copy.
  27  * Other operations performed on a working copy update the
  28  * contents of the working copy's buffer but do not commit the contents
  29  * of the working copy.
  30  * </p>
  31  * <p>
  32  * Note: The contents of a working copy is determined when a working
  33  * copy is created, based on the current content of the element the working
  34  * copy is created from. If a working copy is an <code>IOpenable</code> and is explicitly
  35  * closed, the working copy's buffer will be thrown away. However, clients should not
  36  * explicitly open and close working copies.
  37  * </p>
  38  * <p>
  39  * The client that creates a working copy is responsible for
  40  * destroying the working copy. The Java model will never automatically
  41  * destroy or close a working copy. (Note that destroying a working copy
  42  * does not commit it to the model, it only frees up the memory occupied by
  43  * the element). After a working copy is destroyed, the working copy cannot
  44  * be accessed again. Non-handle methods will throw a
  45  * <code>JavaModelException</code> indicating the Java element does not exist.
  46  * </p>
  47  * <p>
  48  * A working copy cannot be created from another working copy.
  49  * Calling <code>getWorkingCopy</code> on a working copy returns the receiver.
  50  * </p>
  51  * <p>
  52  * This interface is not intended to be implemented by clients.
  53  * </p>
  54  */
  55 public interface IWorkingCopy {
  56
  57         /**
  58          * Commits the contents of this working copy to its original element
  59          * and underlying resource, bringing the Java model up-to-date with
  60          * the current contents of the working copy.
  61          *
  62          * <p>It is possible that the contents of the original resource have changed
  63          * since this working copy was created, in which case there is an update conflict.
  64          * The value of the <code>force</code> parameter effects the resolution of
  65          * such a conflict:<ul>
  66          * <li> <code>true</code> - in this case the contents of this working copy are applied to
  67          *      the underlying resource even though this working copy was created before
  68          *      a subsequent change in the resource</li>
  69          * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
  70          * </ul>
  71          *
  72          * @param force a flag to handle the cases when the contents of the original resource have changed
  73          * since this working copy was created
  74          * @param monitor the given progress monitor
  75          * @exception JavaModelException if this working copy could not commit. Reasons include:
  76          * <ul>
  77          * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
  78          * <li> A <code>CoreException</code> occurred while updating an underlying resource
  79          * <li> This element is not a working copy (INVALID_ELEMENT_TYPES)
  80          * <li> A update conflict (described above) (UPDATE_CONFLICT)
  81          * </ul>
  82          */
  83         void commit(boolean force, IProgressMonitor monitor) throws JavaModelException;
  84
  85         /**
  86          * Destroys this working copy, closing its buffer and discarding
  87          * its structure. Subsequent attempts to access non-handle information
  88          * for this working copy will result in <code>IJavaModelException</code>s. Has
  89          * no effect if this element is not a working copy.
  90          * <p>
  91          * If this working copy is shared, it is destroyed only when the number of calls to
  92          * <code>destroy()</code> is the same as the number of calls to <code>
  93          * getSharedWorkingCopy(IProgressMonitor, IBufferFactory)</code>.
  94          * A REMOVED IJavaElementDelta is then reported on this working copy.
  95          */
  96         void destroy();
  97
  98         /**
  99          * Finds the shared working copy for this element, given a <code>IBuffer</code> factory.
 100          * If no working copy has been created for this element associated with this
 101          * buffer factory, returns <code>null</code>.
 102          * <p>
 103          * Users of this method must not destroy the resulting working copy.
 104          *
 105          * @param bufferFactory the given <code>IBuffer</code> factory
 106          * @return the found shared working copy for this element, <code>null</code> if none
 107          * @see IBufferFactory
 108          * @since 2.0
 109          */
 110         IJavaElement findSharedWorkingCopy(IBufferFactory bufferFactory);
 111
 112         /**
 113          * Returns the original element the specified working copy element was created from,
 114          * or <code>null</code> if this is not a working copy element.  This is a handle
 115          * only method, the returned element may or may not exist.
 116          *
 117          * @return the original element the specified working copy element was created from,
 118          * or <code>null</code> if this is not a working copy element
 119          */
 120         IJavaElement getOriginal(IJavaElement workingCopyElement);
 121
 122         /**
 123          * Returns the original element this working copy was created from,
 124          * or <code>null</code> if this is not a working copy.
 125          *
 126          * @return the original element this working copy was created from,
 127          * or <code>null</code> if this is not a working copy
 128          */
 129         IJavaElement getOriginalElement();
 130
 131         /**
 132          * Finds the elements in this compilation unit that correspond to
 133          * the given element.
 134          * An element A corresponds to an element B if:
 135          * <ul>
 136          * <li>A has the same element name as B.
 137          * <li>If A is a method, A must have the same number of arguments as
 138          *     B and the simple names of the argument types must be equals.
 139          * <li>The parent of A corresponds to the parent of B recursively up to
 140          *     their respective compilation units.
 141          * <li>A exists.
 142          * </ul>
 143          * Returns <code>null</code> if no such java elements can be found
 144          * or if the given element is not included in a compilation unit.
 145          *
 146          * @param element the given element
 147          * @return the found elements in this compilation unit that correspond to the given element
 148          * @since 2.0
 149          */
 150         IJavaElement[] findElements(IJavaElement element);
 151
 152         /**
 153          * Finds the primary type of this compilation unit (i.e.&nbsp;the type with the same name as the
 154          * compilation unit), or <code>null</code> if no such a type exists.
 155          *
 156          * @return the found primary type of this compilation unit, or <code>null</code> if no such a type exists
 157          * @since 2.0
 158          */
 159         IType findPrimaryType();
 160
 161         /**
 162          * Returns a shared working copy on this element using the given factory to create
 163          * the buffer, or this element if this element is already a working copy.
 164          * This API can only answer an already existing working copy if it is based on the same
 165          * original compilation unit AND was using the same buffer factory (i.e. as defined by <code>Object#equals</code>).
 166          * <p>
 167          * The life time of a shared working copy is as follows:
 168          * <ul>
 169          * <li>The first call to <code>getSharedWorkingCopy(...)</code> creates a new working copy for this
 170          *     element</li>
 171          * <li>Subsequent calls increment an internal counter.</li>
 172          * <li>A call to <code>destroy()</code> decrements the internal counter.</li>
 173          * <li>When this counter is 0, the working copy is destroyed.
 174          * </ul>
 175          * So users of this method must destroy exactly once the working copy.
 176          * <p>
 177          * Note that the buffer factory will be used for the life time of this working copy, i.e. if the
 178          * working copy is closed then reopened, this factory will be used.
 179          * The buffer will be automatically initialized with the original's compilation unit content
 180          * upon creation.
 181          * <p>
 182          * When the shared working copy instance is created, an ADDED IJavaElementDelta is reported on this
 183          * working copy.
 184          *
 185          * @param monitor a progress monitor used to report progress while opening this compilation unit
 186          *                 or <code>null</code> if no progress should be reported
 187          * @param factory the factory that creates a buffer that is used to get the content of the working copy
 188          *                 or <code>null</code> if the internal factory should be used
 189          * @param problemRequestor a requestor which will get notified of problems detected during
 190          *      reconciling as they are discovered. The requestor can be set to <code>null</code> indicating
 191          *      that the client is not interested in problems.
 192          * @exception JavaModelException if the contents of this element can
 193          *   not be determined. Reasons include:
 194          * <ul>
 195          * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 196          * </ul>
 197          * @return a shared working copy on this element using the given factory to create
 198          * the buffer, or this element if this element is already a working copy
 199          * @see IBufferFactory
 200          * @see IProblemRequestor
 201          * @since 2.0
 202          */
 203         IJavaElement getSharedWorkingCopy(
 204                 IProgressMonitor monitor,
 205                 IBufferFactory factory,
 206                 IProblemRequestor problemRequestor)
 207                 throws JavaModelException;
 208
 209         /**
 210          * Returns a new working copy of this element if this element is not
 211          * a working copy, or this element if this element is already a working copy.
 212          *
 213          * Note: if intending to share a working copy amongst several clients, then
 214          * <code>#getSharedWorkingCopy</code> should be used instead.
 215          *
 216          * @exception JavaModelException if the contents of this element can
 217          *   not be determined. Reasons include:
 218          * <ul>
 219          * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 220          * </ul>
 221          * @return a new working copy of this element if this element is not
 222          * a working copy, or this element if this element is already a working copy
 223          */
 224         IJavaElement getWorkingCopy() throws JavaModelException;
 225
 226         /**
 227          * Returns a new working copy of this element using the given factory to create
 228          * the buffer, or this element if this element is already a working copy.
 229          * Note that this factory will be used for the life time of this working copy, i.e. if the
 230          * working copy is closed then reopened, this factory will be reused.
 231          * The buffer will be automatically initialized with the original's compilation unit content
 232          * upon creation.
 233          *
 234          * Note: if intending to share a working copy amongst several clients, then
 235          * <code>#getSharedWorkingCopy</code> should be used instead.
 236          *
 237          * @param monitor a progress monitor used to report progress while opening this compilation unit
 238          *                 or <code>null</code> if no progress should be reported
 239          * @param factory the factory that creates a buffer that is used to get the content of the working copy
 240          *                 or <code>null</code> if the internal factory should be used
 241          * @param problemRequestor a requestor which will get notified of problems detected during
 242          *      reconciling as they are discovered. The requestor can be set to <code>null</code> indicating
 243          *      that the client is not interested in problems.
 244          * @exception JavaModelException if the contents of this element can
 245          *   not be determined. Reasons include:
 246          * <ul>
 247          * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 248          * </ul>
 249          * @return a new working copy of this element using the given factory to create
 250          * the buffer, or this element if this element is already a working copy
 251          * @since 2.0
 252          */
 253         IJavaElement getWorkingCopy(
 254                 IProgressMonitor monitor,
 255                 IBufferFactory factory,
 256                 IProblemRequestor problemRequestor)
 257                 throws JavaModelException;
 258
 259         /**
 260          * Returns whether this working copy's original element's content
 261          * has not changed since the inception of this working copy.
 262          *
 263          * @return true if this working copy's original element's content
 264          * has not changed since the inception of this working copy, false otherwise
 265          */
 266         boolean isBasedOn(IResource resource);
 267
 268         /**
 269          * Returns whether this element is a working copy.
 270          *
 271          * @return true if this element is a working copy, false otherwise
 272          */
 273         boolean isWorkingCopy();
 274
 275         /**
 276          * Reconciles the contents of this working copy.
 277          * It performs the reconciliation by locally caching the contents of
 278          * the working copy, updating the contents, then creating a delta
 279          * over the cached contents and the new contents, and finally firing
 280          * this delta.
 281          * <p>
 282          * If the working copy hasn't changed, then no problem will be detected,
 283          * this is equivalent to <code>IWorkingCopy#reconcile(false, null)</code>.
 284          * <p>
 285          * Compilation problems found in the new contents are notified through the
 286          * <code>IProblemRequestor</code> interface which was passed at
 287          * creation, and no longer as transient markers. Therefore this API will
 288          * return <code>null</code>.
 289          * <p>
 290          * Note: It has been assumed that added inner types should
 291          * not generate change deltas.  The implementation has been
 292          * modified to reflect this assumption.
 293          *
 294          * @exception JavaModelException if the contents of the original element
 295          *              cannot be accessed. Reasons include:
 296          * <ul>
 297          * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 298          * </ul>
 299          * @return <code>null</code>
 300          */
 301         IMarker[] reconcile() throws JavaModelException;
 302
 303         /**
 304          * Reconciles the contents of this working copy.
 305          * It performs the reconciliation by locally caching the contents of
 306          * the working copy, updating the contents, then creating a delta
 307          * over the cached contents and the new contents, and finally firing
 308          * this delta.
 309          * <p>
 310          * The boolean argument allows to force problem detection even if the
 311          * working copy is already consistent.
 312          * <p>
 313          * Compilation problems found in the new contents are notified through the
 314          * <code>IProblemRequestor</code> interface which was passed at
 315          * creation, and no longer as transient markers. Therefore this API answers
 316          * nothing.
 317          * <p>
 318          * Note: It has been assumed that added inner types should
 319          * not generate change deltas.  The implementation has been
 320          * modified to reflect this assumption.
 321          *
 322          * @param forceProblemDetection boolean indicating whether problem should be recomputed
 323          *   even if the source hasn't changed.
 324          * @param monitor a progress monitor
 325          * @exception JavaModelException if the contents of the original element
 326          *              cannot be accessed. Reasons include:
 327          * <ul>
 328          * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 329          * </ul>
 330          * @since 2.0
 331          */
 332         void reconcile(boolean forceProblemDetection, IProgressMonitor monitor) throws JavaModelException;
 333
 334         /**
 335          * Restores the contents of this working copy to the current contents of
 336          * this working copy's original element. Has no effect if this element
 337          * is not a working copy.
 338          *
 339          * <p>Note: This is the inverse of committing the content of the
 340          * working copy to the original element with <code>commit(boolean, IProgressMonitor)</code>.
 341          *
 342          * @exception JavaModelException if the contents of the original element
 343          *              cannot be accessed.  Reasons include:
 344          * <ul>
 345          * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 346          * </ul>
 347          */
 348         void restore() throws JavaModelException;
 349 }