Latest revision as of 05:38, 16 November 2016

Migration Guide for Handly 0.6

Changes that need to be accommodated by current adopters as part of migrating to Handly 0.6 from the previous major release (0.5). Although the full list of breaking changes is quite long and can be overwhelming, some changes are expected to be less affecting for existing clients than others.

Quick Summary (Most Affecting Changes)

• IElementExtension
  • getPath() has been effectively replaced with getLocationURI() (506717)
• IElementImpl
  • hPath() has been effectively replaced with hLocationURI() and hToDisplayString(IContext) (506717)
• ISourceFileExtension
  • reconcile(boolean, IProgressMonitor) → reconcile(IProgressMonitor) (500408)
• Element
  • Implements IModelManager.Provider (500653)
  • hBuildStructure(Object, Map<IElement, Object>, IProgressMonitor) → hBuildStructure(IContext, IProgressMonitor) (500408)
  • hValidateExistence() → hValidateExistence(IContext) (500408)
  • hNewBody() is no longer used and has been removed (500408)
• Property has been moved to org.eclipse.handly.util package (498749)
  • public Property(String) → protected Property(String) (498752)
  • New API methods:
    • static <T> Property<T> get(String, Class<T>) (498752)
    • Property<T> withDefault(T) (498873)
• SourceFile
  • Clients that previously extended SourceFile should now extend WorkspaceSourceFile (500676)
  • hBuildStructure(SourceElementBody, Map<IElement, Object>, Object, String, IProgressMonitor) → hBuildStructure(IContext, IProgressMonitor) (500408)
  • hCreateStructuralAst(String, IProgressMonitor) is no longer called by the framework and has been removed (506332). Clients can create the AST in whatever way they see fit, or even skip creating the AST entirely (e.g. use something like SAX). For details, see exemplary implementations (e.g. FooFile and CompilationUnit)
  • ReconcileOperation (506332)
    • reconcile(Object, NonExpiringSnapshot, boolean, IProgressMonitor) → reconcile(IContext, IProgressMonitor)
  • New inner class: NotifyingReconcileOperation (505777)

Full List of Changes per Package

org.eclipse.handly.buffer

• IBuffer API has been revised (505714)
  • hasUnsavedChanges() → isDirty()
  • save(boolean, IProgressMonitor) → save(IContext, IProgressMonitor)
  • getDocument() may no longer return null
  • getContents(), setContents(String) have been removed. Clients can use buffer.getDocument().get() and buffer.getDocument().set(text) as the corresponding replacements
  • mustSaveChanges() has been removed without replacement
• ChildBuffer is now final (505714)
• SimpleBuffer has been renamed to Buffer (501080)
  • doSave(boolean, IProgressMonitor) → doSave(IContext, IProgressMonitor)
• TextFileBuffer is now final (505714)
  • TextFileBuffer(IFile, ITextFileBufferManager) → TextFileBuffer(ICoreTextFileBufferProvider, IProgressMonitor) (502000)
  • New API methods:
    • public static TextFileBuffer forLocation(IPath, LocationKind)
    • public static TextFileBuffer forFileStore(IFileStore)
    • public static TextFileBuffer forFile(IFile)
    • public ICoreTextFileBufferProvider getCoreTextFileBufferProvider()

org.eclipse.handly.document

• The package has been renamed to org.eclipse.handly.text (501070)

org.eclipse.handly.model

• IElementExtension
  • getPath() has been effectively replaced with getLocationURI() (506717)
• ISourceFileExtension
  • getBuffer(boolean, IProgressMonitor) has been removed (500408); another overload, getBuffer(), is here to stay
  • reconcile(boolean, IProgressMonitor) → reconcile(IProgressMonitor) (500408)
• ElementDeltas
  • toString(IElementDelta, ToStringStyle) → toString(IElementDelta, IContext) (499540)
• Elements
  • NO_SOURCE_INFO → NO_SOURCE_ELEMENT_INFO
  • toString(IElement, ToStringStyle) → toString(IElement, IContext) (499540)
  • getPath(IElement) has been effectively replaced with getLocationURI(IElement) and toDisplayString(IElement, IContext) (506717)
  • reconcile(ISourceFile, boolean, IProgressMonitor) → reconcile(ISourceFile, IContext, IProgressMonitor) (500408)
  • getBuffer(ISourceFile, boolean, IProgressMonitor) → getBuffer(ISourceFile, IContext, IProgressMonitor) (500408)
• Property has been moved to org.eclipse.handly.util package (498749)
  • public Property(String) → protected Property(String) (498752)
  • New API methods:
    • static <T> Property<T> get(String, Class<T>) (498752)
    • Property<T> withDefault(T) (498873)
    • Type getType() (498752)
    • Class<T> getRawType() (499101)
    • T defaultValue() (498873)
• ToStringStyle has been effectively replaced with a context containing format options, with common options defined in org.eclipse.handly.util.ToStringOptions (499540)

org.eclipse.handly.model.impl

• IElementDeltaImpl
  • hToString(ToStringStyle) → hToString(IContext) (499540)
• IElementImpl
  • hToString(ToStringStyle) → hToString(IContext) (499540)
  • hPath() has been effectively replaced with hLocationURI() and hToDisplayString(IContext) (506717)
• ISourceFileImpl
  • hReconcile(boolean, IProgressMonitor) and hReconcile(boolean, Object, IProgressMonitor) → hReconcile(IContext, IProgressMonitor) (500408)
  • hBuffer() and hBuffer(boolean, IProgressMonitor) → hBuffer(IContext, IProgressMonitor) (500408)
• IWorkingCopyInfoFactory → WorkingCopyInfo.Factory (506332)
• DefaultWorkingCopyInfo (506332)
  • DefaultWorkingCopyInfo(IBuffer) → DefaultWorkingCopyInfo(SourceFile, IBuffer)
  • needsReconciling() is now final
• Element
  • Implements IModelManager.Provider (500653)
  • hBuildStructure(Object, Map<IElement, Object>, IProgressMonitor) → hBuildStructure(IContext, IProgressMonitor) (500408)
  • hValidateExistence() → hValidateExistence(IContext) (500408)
  • hBody(IProgressMonitor) → hBody(IContext, IProgressMonitor) (500408)
  • hNewBody() is no longer used and has been removed (500408)
  • hGenerateAncestorBodies(Map<IElement, Object>, IProgressMonitor) → hGenerateAncestorBodies(IContext, IProgressMonitor) (500408)
  • hGenerateBodies(Object, Map<IElement, Object>, IProgressMonitor) → hGenerateBodies(IContext, IProgressMonitor) (500408)
  • hToStringAncestors(StringBuilder) → hToStringAncestors(StringBuilder, IContext) (499540)
  • hToStringChildren(IndentationPolicy, int, StringBuilder, Object) → hToStringChildren(StringBuilder, Object, IContext) (499540)
  • hToStringBody(IndentationPolicy, int, StringBuilder, Object, boolean) → hToStringBody(StringBuilder, Object, IContext) (499540)
  • hToStringName(StringBuilder) → hToStringName(StringBuilder, IContext) (499540)
  • The following methods have been removed without replacement (499540):
    • hToDebugString()
    • hToStringWithAncestors()
    • hToStringWithAncestors(boolean)
    • hToStringBody(IndentationPolicy, int, StringBuilder)
    • hToString(IndentationPolicy, int, StringBuilder)
• ElementDelta
  • hToStringFull(IndentationPolicy, int, StringBuilder), hToStringMinimal(IndentationPolicy, int, StringBuilder) have been effectively replaced with a more fine grained API hToStringChildren(StringBuilder, IContext), hToStringResourceDeltas(StringBuilder, IContext), hToStringKind(StringBuilder, IContext) (499540)
  • hToStringFlags(StringBuilder) → hToStringFlags(StringBuilder, IContext) (499540)
• ElementManager
  • closeChildren(IElement, Object) and removing(IElement, Object) have been effectively replaced with close(IElement)
• SimpleSourceElementInfo has been removed (499879)
• SourceFile
  • Clients that previously extended SourceFile should now extend WorkspaceSourceFile (500676)
  • SourceFile(Element, IFile) → SourceFile(Element, String) (500676)
  • hBuildStructure(SourceElementBody, Map<IElement, Object>, Object, String, IProgressMonitor) → hBuildStructure(IContext, IProgressMonitor) (500408)
  • hCreateStructuralAst(String, IProgressMonitor) is no longer called by the framework and has been removed (506332). Clients can create the AST in whatever way they see fit, or even skip creating the AST entirely (e.g. use something like SAX). For details, see exemplary implementations (e.g. FooFile and CompilationUnit)
  • hBecomeWorkingCopy(IBuffer, IProgressMonitor) and hBecomeWorkingCopy(IBuffer, IWorkingCopyInfoFactory, IProgressMonitor) → hBecomeWorkingCopy(IContext, IProgressMonitor) (506332)
  • hAcquireWorkingCopy() → hAcquireExistingWorkingCopy(IProgressMonitor) (506332)
  • hDiscardWorkingCopy() → hReleaseWorkingCopy() (506332)
  • hPeekAtWorkingCopyInfo() → hWorkingCopyInfo() (506332)
  • New abstract methods (500676):
    • hFileExists()
    • hFileSnapshotProvider()
    • hFileBuffer(IContext, IProgressMonitor)
  • hReconcileOperation() is now protected (506332)
  • ReconcileOperation is now protected (506332)
    • reconcile(Object, NonExpiringSnapshot, boolean, IProgressMonitor) → reconcile(IContext, IProgressMonitor)
    • shouldRebuildStructureIfForced() has been effectively replaced with a context property SourceFile.REBUILD_STRUCTURE_IF_FORCED
  • New inner class: NotifyingReconcileOperation (505777)
• WorkingCopyInfo (506332)
  • WorkingCopyInfo(IBuffer) → WorkingCopyInfo(SourceFile, IBuffer)
  • needsReconciling and reconcile(..) are now @noreference

org.eclipse.handly.snapshot

• ISnapshotProvider now extends org.eclipse.handly.util.IReferenceCountable (500893)
• DocumentSnapshot is now final (500893)
• TextFileSnapshot (500893)
  • TextFileSnapshot(IFile, boolean) → TextFileSnapshot(IFile, Layer)
  • New API class: Layer
• New API class: TextFileStoreSnapshot

org.eclipse.handly.ui

• IWorkingCopyProvider and WorkingCopyProvider are no longer used and have been removed (506332)

org.eclipse.handly.ui.text.reconciler

• BaseReconciler → WorkingCopyReconciler (506332)
  • No longer implements IWorkingCopyProvider
  • BaseReconciler(IWorkingCopyProvider) → WorkingCopyReconciler(IWorkingCopyManager)
• HandlyReconciler → EditorWorkingCopyReconciler (506332)
  • HandlyReconciler(ITextEditor, IWorkingCopyManager) → EditorWorkingCopyReconciler(IEditorPart, IWorkingCopyManager)
• WorkingCopyReconcilingStrategy (506332)
  • WorkingCopyReconcilingStrategy(IWorkingCopyProvider) → WorkingCopyReconcilingStrategy(IWorkingCopyManager)
  • reconcile(ISourceFile, boolean) → reconcile(ISourceFile, boolean, IProgressMonitor)
  • getProgressMonitor() has been removed

org.eclipse.handly.ui.texteditor

• SourceFileDocumentProvider is now abstract (506332)
  • SourceFileDocumentProvider(IInputElementProvider) → SourceFileDocumentProvider()
  • SourceFileDocumentProvider(IDocumentProvider, IInputElementProvider) → SourceFileDocumentProvider(IDocumentProvider)
  • SourceFile getSourceFile(Object) → abstract ISourceFile getSourceFile(Object)
  • getWorkingCopyInfoFactory(..) is no longer used and has been removed
  • New API methods:
    • acquireWorkingCopy(Object, FileInfo)
    • releaseWorkingCopy(ISourceFile, Object, FileInfo)
• TextEditorBuffer is now final (505714)

org.eclipse.handly.util

• IndentationPolicy → IndentPolicty (499540)
  • appendIndentTo(..) → appendIndent(..)
  • appendLineSeparatorTo(..) → appendLine(..)
• UiSynchronizer (496840)
  • DEFAULT → getDefault()
  • synchExec(Runnable) may now throw a checked java.util.concurrent.ExecutionException
  • getThread(), asyncExec(Runnable), and syncExec(Runnable) may now throw IllegalStateException
• New API:
  • IReferenceCountable (500893)
  • SavedStateJob (505792)
  • ToStringOptions (499540)

org.eclipse.handly.xtext.ui.editor

• IHandlyXtextDocument no longer extends ISnapshotProvider (500893)
• HandlyXtextDocument (506332)
  • IReconcilingListener, addReconcilingListener, removeReconcilingListener are now package private
• HandlyXtextEditorCallback (506332)
  • SourceFile getSourceFile(XtextEditor) → ISourceFile getSourceFile(XtextEditor)
  • SourceFile getWorkingCopy(XtextEditor) → ISourceFile getWorkingCopy(XtextEditor)
  • New API methods:
    • ISourceFile acquireWorkingCopy(XtextEditor)
    • releaseWorkingCopy(XtextEditor, ISourceFile)
• XtextWorkingCopyInfo (506332)
  • XtextWorkingCopyInfo(IBuffer) → XtextWorkingCopyInfo(SourceFile, IBuffer)
  • needsReconciling(), reconcile(..), and getDocument() are now final