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

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