Handly/Migration05

Migration Guide for Handly 0.5

Changes that need to be catered for by current adopters as part of migrating to Handly 0.5 from the previous major release (0.4).

• IHandle has been replaced with a trio of IElement, IElementExtension, and Elements (bug 491568, bug 491564)
• IHandle.ToStringStyle has become a top-level class (bug 491647)
• ISourceElement has been effectively replaced with a trio of ISourceElement, ISourceElementExtension, and Elements (bug 491564)
  • getElementAt → getSourceElementAt
• ISourceElement.Property has become a top-level class (bug 491649)
• ISourceFile has been effectively replaced with a trio of ISourceFile, ISourceFileExtension, and Elements (bug 491564)
• SourceElements has been replaced with Elements (bug 491564)
  • getElementAt → getSourceElementAt2
  • getSourceElementInfo → getSourceElementInfo2
• IHandleDelta has been replaced with a quartet of IElementDelta, IElementDeltaConstants, IElementDeltaExtension, and ElementDeltas (bug 491568, bug 491564)
  • getResourceDeltas and getMarkerDeltas may now return null (bug 488819)
• Handle has been renamed to Element (bug 491568)
  • Fields parent and name are now private and must be accessed through corresponding accessor methods
  • Adopted the h prefix for the names of non-static API methods: getName → hName, exists → hExists, etc. (bug 491564)
  • getHandleManager → hElementManager
  • Some of the API methods have changed type of parameters and/or return value (Body → Object, bug 491570):
    • buildStructure(Body, Map<IHandle, Body>, ..) → hBuildStructure(Object, Map<IElement, Object>, ..)
    • Body findBody() → Object hFindBody()
    • Body peekAtBody() → Object hPeekAtBody()
    • Body getBody() → Object hBody()
    • Body newBody() → Object hNewBody()
    • Body toStringBody(..) → Object hToStringBody(..)
    • toStringChildren(.., Body) → hToStringChildren(.., Object)
    • toStringBody(.., Body, ..) → hToStringBody(.., Object, ..)
    • generateAncestorBodies(Map<IHandle, Body>, ..) → hGenerateAncestorBodies(Map<IElement, Object>, ..)
    • generateBodies(Body, Map<IHandle, Body>, ..) → hGenerateBodies(Object, Map<IElement, Object>, ..)
    • removing(Body) → hRemoving(Object)
• SourceElement
  • Adopted the h prefix for the names of non-static API methods: getElementAt → hSourceElementAt, etc. (bug 491564)
• SourceFile
  • Field file is now private and must be accessed through the corresponding accessor method
  • Adopted the h prefix for the names of non-static API methods: getFile → hFile, getBuffer → hBuffer, etc. (bug 491564)
  • Some of the API methods have changed type of parameters:
    • buildStructure(SourceElementBody, Map<IHandle, Body>, ..) → hBuildStructure(SourceElementBody, Map<IElement, Object>, ..) (bug 491570)
    • becomeWorkingCopy(IWorkingCopyBuffer, ..) → hBecomeWorkingCopy(IBuffer, ..) (bug 492179)
• SourceConstruct
  • Adopted the h prefix for the names of non-static API methods: getOccurrenceCount → hOccurrenceCount, etc. (bug 491564)
• HandleDelta has been renamed to ElementDelta (bug 491568)
  • Adopted the h prefix for the names of non-static API methods: getElement → hElement, getKind → hKind, etc. (bug 491564)
  • insertXXX methods along with setMarkerDeltas and addResourceDelta have been replaced with a new API, ElementDelta.Builder (bug 491575)
  • New API method: hToString(ToStringStyle)
  • Some of the public toStringXXX methods have become protected:
    • public toStringFull → protected hToStringFull
    • public toStringMinimal(StringBuilder) → protected hToStringMinimal(IndentationPolicy, int, StringBuilder)
• HandleDeltaBuilder has been renamed to ElementDifferencer (bug 491568, bug 491575)
  • Some of the API methods have changed type of parameters and/or return value:
    • HandleDeltaBuilder(IHandle) → ElementDifferencer(ElementDelta.Builder)
    • HandleDelta getDelta() → IElementDelta getDelta()
    • findContentChange(Body, Body, IHandle) → findContentChange(Object, Object, IElement) (bug 491570)
  • newDelta method is no longer needed and has been removed
  • New API methods: getElement() and isEmptyDelta()
• HandleManager has been renamed to ElementManager (bug 491568)
  • Methods internalClose(IHandle) and removing(IHandle, Body) have been effectively replaced with closeChildren(IElement, Object) and removing(IElement, Object) (bug 491570)
• IBodyCache
  • Some of the API methods have changed type of parameters and/or return value (Body → Object, bug 491570):
    • Body get(IHandle) → Object get(IElement)
    • Body peek(IHandle) → Object peek(IElement)
    • put(IHandle, Body) → put(IElement, Object)
    • putAll(Map<IHandle, Body>) → putAll(Map<IElement, Object>)
• ElementCache now extends OverflowingLruCache<IElement, Object> instead of previously extending OverflowingLruChache<IHandle, Body> (bug 491570)
  • ensureSpaceLimit(Body, IHandle) → ensureSpaceLimit(Object, IElement)
  • New API method: getChildCount(IElement, Object)
• WorkingCopyInfo has taken over the reconciling related responsibilities from IWorkingCopyBuffer and now works with any IBuffer (bug 492179)
  • Some of the API methods have changed type of parameters and/or return value:
    • WorkingCopyInfo(IWorkingCopyBuffer) → WorkingCopyInfo(IBuffer)
    • IWorkingCopyBuffer getBuffer() → IBuffer getBuffer()
  • New API methods: onInit(), needsReconciling(), reconcile(..), getWorkingCopy()
  • New API classes: DefaultWorkingCopyInfo, XtextWorkingCopyInfo
• IWorkingCopyInfoFactory
  • createWorkingCopyInfo(IWorkingCopyBuffer) → createWorkingCopyInfo(IBuffer) (bug 429179)
• IWorkingCopyBuffer and its implementations are no longer needed and have been removed (bug 429179)
• IWorkingCopyReconciler and its implementations are no longer needed and have been removed (bug 429179)
• Some of the API elements have been renamed (bug 491568)
  • IContentAdaper#getHandle → #adapt
  • HandleLabelProvider → ElementLabelProvider
  • HandleTreeContentProvider → ElementTreeContentProvider
  • AbstractWorkingSetUpdater#processHandleDelta → #processElementDelta
• Previously deprecated API elements have been removed (bug 487183)
  • IBuffer#dispose - Replaced with #release
  • IDocumentBuffer - Effectively replaced with IBuffer#getDocument
  • IElementForEditorInputFactory - Replaced with IInputElementProvider
  • ISourceFile#openBuffer - Replaced with #getBuffer
  • TextFileSnapshot(IFile) - Replaced with TextFileSnapshot(IFile, boolean)