[jdt-core-dev] Clarification on specs: ICompilationUnit#reconcile(...) v

["Philippe P Mulet" <philippe_mulet@xxxxxxxxxx>]

We'd like to mention a subtle issue which one may encounter when using
combinations of ICompilationUnit#reconcile(...) and
IOpenable#makeConsistent(...).
Both feels pretty close to each other, but only the reconcile operation
will provide a description of the changes since last time it got reconciled
by sending out a notification of a Java element delta.

One point our spec did not clearly say is that a reconcile operation will
only flag changes which occurred since last time the working copy was
reconciled OR made consistent. So if one is mixing usage of #reconcile(...)
and #makeConsistent(...), some deltas may get altered.

It is preferable to only use #reconcile(...) everywhere or #makeConsistent
(...) everywhere in your code.
An interesting example of mixed usage is:

org.eclipse.jdt.internal.ui.examples.jspeditor.JavaReconcileStep.reconcileModel(DirtyRegion,

IRegion)


See below the updated spec mentionning this issue:

org.eclipse.jdt.core.IOpenable:

/**
 * Makes this element consistent with its underlying resource or buffer
 * by updating the element's structure and properties as necessary.
 *<p>
 * Note: Using this functionality on a working copy will interfere with any
 * subsequent reconciling operation. Indeed, the next <code>
ICompilationUnit#reconcile()</code>
 * operation will not account for changes which occurred before an
 * explicit use of <code>#makeConsistent(IProgressMonitor)</code>
 * <p>
 * @param progress the given progress monitor
 * @exception JavaModelException if the element is unable to access the
contents
 *          of its underlying resource. Reasons include:
 * <ul>
 *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 * </ul>
 * @see IOpenable#isConsistent()
 * @see ICompilationUnit#reconcile(boolean, IProgressMonitor)
 */
void makeConsistent(IProgressMonitor progress) throws JavaModelException;





org.eclipse.jdt.core.ICompilationUnit

/**
 * Reconciles the contents of this working copy, and sends out a Java delta
 * notification indicating the nature of the change of the working copy
since
 * the last time it was either reconciled or made consistent
 * (see <code>IOpenable#makeConsistent()</code>).
 * .<p>
 * 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.
 * <p>
 * The boolean argument allows to force problem detection even if the
 * working copy is already consistent.</p>
 * <p>
 * Compilation problems found in the new contents are notified through the
 * <code>IProblemRequestor</code> interface which was passed at
 * creation, and no longer as transient markers. Therefore this API answers
 * nothing.</p>
 * <p>
 * Note: Since 3.0 added/removed/changed inner types generate change
deltas.</p>
 * <p>
 * @param forceProblemDetection boolean indicating whether problem should
be recomputed
 *   even if the source hasn't changed.
 * @param monitor a progress monitor
 * @throws JavaModelException if the contents of the original element
 *          cannot be accessed. Reasons include:
 * <ul>
 * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)
</li>
 * </ul>
 * @since 3.0
 */
void reconcile(boolean forceProblemDetection, IProgressMonitor monitor)
throws JavaModelException;