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