Description Tom Hofmann 2006-04-13 10:39:36 EDT

I20060412-20xx

See bug 129168 for the context. Basically, the AdditionalInfoController implementation has always computed the additional information (e.g. javadoc) about proposals in the display thread. Unlike the hover manager, it only uses a thread to compute the delay, then posts into the display thread to compute and display the info.

This is a problem when the information computation is expensive, for example when javadoc is fetched from a remoted location and parsed.

Existing ICompletionProposal implementations may assume that ICompletionProposal::getAdditionalInfo() is called in the display thread, so we cannot simply push the computation into the background for compatibility reasons.

We propose to create a new extension interface for ICompletionProposal that explicitely states that its additional information may be computed in the background:

public interface ICompletionProposalExtension5 {
	/**
	 * Returns additional information about the proposal. The additional information will be
	 * presented to assist the user in deciding if the selected proposal is the desired choice.
	 * <p>
	 * This method may be called on a non-UI thread.
	 * </p>
	 * <p>
	 * By default, the returned information is converted to a string and displayed as text; if
	 * {@link ICompletionProposalExtension3#getInformationControlCreator()} is implemented, the
	 * information will be passed to a custom information control for display.
	 * </p>
	 * 
	 * @param monitor a monitor to report progress and to watch for
	 *        {@link IProgressMonitor#isCanceled() cancelation}.
	 * @return the additional information, <code>null</code> for no information
	 */
	Object getAdditionalProposalInfo(IProgressMonitor monitor);
}


The differences to ICompletionProposal::getAdditionalProposalInfo are:
- adds explicit threading information to the javadoc
- adds a progress monitor that supports cancellation
- returns an Object instead of a string, similar to IAnnotationHoverExtension::getHoverInfo

API considerations:
- adding a new interface is unproblematic. The call sequence and behavior for existing ICompletionProposal implementations that do not implement the new interface is unchanged.