Eclipse Platform Release 3.7

## org.eclipse.compare.structuremergeviewer
Class DocumentRangeNode

    java.lang.Object
      org.eclipse.compare.structuremergeviewer.DocumentRangeNode

All Implemented Interfaces:
  IDocumentRange, IEditableContent, IEditableContentExtension, IEncodedStreamContentAccessor, IStreamContentAccessor, IStructureComparator, IAdaptable

Direct Known Subclasses:
  StructureRootNode

    public class DocumentRangeNode

extends Object
implements IDocumentRange, IStructureComparator, IEditableContent, IEncodedStreamContentAccessor, IAdaptable, IEditableContentExtension

A document range node represents a structural element when performing a structure compare of documents. `DocumentRangeNodes` are created while parsing the document and represent a semantic entity (e.g. a Java class or method). As a consequence of the parsing a `DocumentRangeNode` maps to a range of characters in the document.

Since a `DocumentRangeNode` implements the `IStructureComparator` and `IStreamContentAccessor` interfaces it can be used as input to the differencing engine. This makes it possible to perform a structural diff on a document and have the nodes and leaves of the compare easily map to character ranges within the document.

Clients need to be aware that this node registers position updaters with the document using `IDocument.addPosition(String, Position)` with the category set to `IDocumentRange.RANGE_CATEGORY`. The `StructureDiffViewer` will remove the category when the nodes are no longer being used. Other clients must do the same.

Subclasses may add additional state collected while parsing the document.

See Also:
  `Differencer`

Field Summary

Fields inherited from interface org.eclipse.compare.contentmergeviewer.IDocumentRange
`RANGE_CATEGORY`

Constructor Summary
`DocumentRangeNode(DocumentRangeNode parent, int typeCode, String id, IDocument document, int start, int length)` Creates a new `DocumentRangeNode` for the given range within the specified document.
`DocumentRangeNode(int typeCode, String id, IDocument document, int start, int length)` Creates a new `DocumentRangeNode` for the given range within the specified document.

Method Summary
`void` `addChild(DocumentRangeNode node)` Adds the given node as a child.
`boolean` `equals(Object other)` Implementation based on `getID`.
`Object` `getAdapter(Class adapter)` Implement `IAdaptable.getAdapter(Class)` in order to provide an `ISharedDocumentAdapter` that provides the proper look up key based on the input from which this structure node was created.
`Position` `getAppendPosition()` Returns the position that has been set with `setAppendPosition`.
`String` `getCharset()` Returns the name of a charset encoding to be used when decoding this stream accessor's contents into characters.
`Object[]` `getChildren()` Returns an iterator for all children of this object or `null` if there are no children.
`InputStream` `getContents()` Returns an open `InputStream` for this object which can be used to retrieve the object's content.
`IDocument` `getDocument()` Returns the underlying document.
`String` `getId()` Returns this node's id.
`Object` `getParentNode()` Return the parent of this node or `null` if the node doesn't have a parent or the parent is not known.
`Position` `getRange()` Returns a position that specifies a subrange in the underlying document, or `null` if this document range spans the whole underlying document.
`int` `getTypeCode()` Returns the type code of this node.
`int` `hashCode()` Implementation based on `getID`.
`protected void` `internalSetContents(byte[] content)` Method that is invoked from `setContent(byte[])`.
`boolean` `isEditable()` If this node has a parent, return the editability of the parent.
`boolean` `isReadOnly()` Return whether the typed element being displayed is read-only. a read-only element will require a call to validateEdit before the element can be modified on disk.
`protected void` `nodeChanged(DocumentRangeNode node)` Method that should be invoked whenever the contents of this node are changed. the change is propagated to the parent if there is one.
`ITypedElement` `replace(ITypedElement child, ITypedElement other)` This method is called on a parent to add or remove a child, or to copy the contents of a child.
`void` `setAppendPosition(int pos)` Sets a position within the document range that can be used to (legally) insert text without breaking the syntax of the document.
`void` `setContent(byte[] content)` Default implementation that calls `internalSetContents(byte[])` and then `nodeChanged(DocumentRangeNode)`.
`void` `setId(String id)` Sets this node's id.
`void` `setLength(int length)` Sets the length of the range of this node.
`IStatus` `validateEdit(Shell shell)` If the element is read-only, this method should be called to attempt to make it writable.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### DocumentRangeNode

    public DocumentRangeNode(int typeCode,
                             String id,
                             IDocument document,
                             int start,
                             int length)

  Creates a new `DocumentRangeNode` for the given range within the specified document. The `typeCode` is uninterpreted client data. The ID is used when comparing two nodes with each other: i.e. the differencing engine performs a content compare on two nodes if their IDs are equal.

  Parameters:
    `typeCode` - a type code for this node
    `id` - an identifier for this node
    `document` - document on which this node is based on
    `start` - start position of range within document
    `length` - length of range

### DocumentRangeNode

    public DocumentRangeNode(DocumentRangeNode parent,
                             int typeCode,
                             String id,
                             IDocument document,
                             int start,
                             int length)

  Creates a new `DocumentRangeNode` for the given range within the specified document. The `typeCode` is uninterpreted client data. The ID is used when comparing two nodes with each other: i.e. the differencing engine performs a content compare on two nodes if their IDs are equal.

  Parameters:
    `parent` - the parent node
    `typeCode` - a type code for this node
    `id` - an identifier for this node
    `document` - document on which this node is based on
    `start` - start position of range within document
    `length` - length of range
  Since:
    3.3

Method Detail

### getDocument

    public IDocument getDocument()

  Description copied from interface: `IDocumentRange`
  Returns the underlying document.

  Specified by:
    `getDocument` in interface `IDocumentRange`
  Returns:
    the underlying document

### getRange

    public Position getRange()

  Description copied from interface: `IDocumentRange`
  Returns a position that specifies a subrange in the underlying document, or `null` if this document range spans the whole underlying document.

  Specified by:
    `getRange` in interface `IDocumentRange`
  Returns:
    a position that specifies a subrange in the underlying document, or `null`

### getTypeCode

    public int getTypeCode()

  Returns the type code of this node. The type code is uninterpreted client data which can be set in the constructor.

  Returns:
    the type code of this node

### getId

    public String getId()

  Returns this node's id. It is used in `equals` and `hashcode`.

  Returns:
    the node's id

### setId

    public void setId(String id)

  Sets this node's id. It is used in `equals` and `hashcode`.

  Parameters:
    `id` - the new id for this node

### addChild

    public void addChild(DocumentRangeNode node)

  Adds the given node as a child.

  Parameters:
    `node` - the node to add as a child

### getChildren

    public Object[] getChildren()

  Description copied from interface: `IStructureComparator`
  Returns an iterator for all children of this object or `null` if there are no children.

  Specified by:
    `getChildren` in interface `IStructureComparator`
  Returns:
    an array with all children of this object, or an empty array if there are no children

### setLength

    public void setLength(int length)

  Sets the length of the range of this node.

  Parameters:
    `length` - the length of the range

### setAppendPosition

    public void setAppendPosition(int pos)

  Sets a position within the document range that can be used to (legally) insert text without breaking the syntax of the document.

  E.g. when parsing a Java document the "append position" of a `DocumentRangeNode` representing a Java class could be the character position just before the closing bracket. Inserting the text of a new method there would not disturb the syntax of the class.

  Parameters:
    `pos` - the character position within the underlying document where text can be legally inserted

### getAppendPosition

    public Position getAppendPosition()

  Returns the position that has been set with `setAppendPosition`. If `setAppendPosition` hasn't been called, the position after the last character of this range is returned. This method will return `null` if the position could not be registered with the document.

  Returns:
    a position where text can be legally inserted

### equals

    public boolean equals(Object other)

  Implementation based on `getID`.

  Specified by:
    `equals` in interface `IStructureComparator`
  Overrides:
    `equals` in class `Object`
  Parameters:
    `other` - the object to compare this `DocumentRangeNode` against.
  Returns:
    `true` if the `DocumentRangeNodes`are equal; `false` otherwise.
  See Also:
    `Object.equals(java.lang.Object)`

### hashCode

    public int hashCode()

  Implementation based on `getID`.

  Overrides:
    `hashCode` in class `Object`
  Returns:
    a hash code for this object.

### getContents

    public InputStream getContents()

  Description copied from interface: `IStreamContentAccessor`
  Returns an open `InputStream` for this object which can be used to retrieve the object's content. The client is responsible for closing the stream when finished. Returns `null` if this object has no streamable contents.

  Specified by:
    `getContents` in interface `IStreamContentAccessor`
  Returns:
    an input stream containing the contents of this object

### isEditable

    public boolean isEditable()

  If this node has a parent, return the editability of the parent. Otherwise return `true`. Subclasses may override.

  Specified by:
    `isEditable` in interface `IEditableContent`
  Returns:
    `true` if this object can be modified
  See Also:
    `IEditableContent.isEditable()`

### replace

    public ITypedElement replace(ITypedElement child,
                                 ITypedElement other)

  Description copied from interface: `IEditableContent`
  This method is called on a parent to add or remove a child, or to copy the contents of a child. What to do is encoded in the two arguments as follows:

  add: | dest == null | src != null
  remove: | dest != null | src == null
  copy: | dest != null | src != null

  Specified by:
    `replace` in interface `IEditableContent`
  Parameters:
    `child` - the existing child of this object to be replaced; if `null` a new child can be added.
    `other` - the new child to be added or replaced; if `null` an existing child can be removed.
  Returns:
    the argument `dest`

### setContent

    public void setContent(byte[] content)

  Default implementation that calls `internalSetContents(byte[])` and then `nodeChanged(DocumentRangeNode)`. Subclasses may override but should then call `nodeChanged(DocumentRangeNode)` after the contents have been set.

  Specified by:
    `setContent` in interface `IEditableContent`
  Parameters:
    `content` - this new contents replaces the old contents
  See Also:
    `IEditableContent.setContent(byte[])`

### internalSetContents

    protected void internalSetContents(byte[] content)

  Method that is invoked from `setContent(byte[])`. By default, this method does nothing. Subclasses may override.

  Parameters:
    `content` - the new content
  Since:
    3.3

### getCharset

    public String getCharset()

  Description copied from interface: `IEncodedStreamContentAccessor`
  Returns the name of a charset encoding to be used when decoding this stream accessor's contents into characters. Returns `null` if a proper encoding cannot be determined.

  Note: this method does not check whether the result is a supported charset name. Callers should be prepared to handle `UnsupportedEncodingException` where this charset is used.

  Specified by:
    `getCharset` in interface `IEncodedStreamContentAccessor`
  Returns:
    the name of a charset, or `null`
  See Also:
    `IStreamContentAccessor.getContents()`

### nodeChanged

    protected void nodeChanged(DocumentRangeNode node)

  Method that should be invoked whenever the contents of this node are changed. the change is propagated to the parent if there is one.

  Parameters:
    `node` - the node that has changed.
  Since:
    3.3

### getAdapter

    public Object getAdapter(Class adapter)

  Implement `IAdaptable.getAdapter(Class)` in order to provide an `ISharedDocumentAdapter` that provides the proper look up key based on the input from which this structure node was created. The proper shared document adapter is obtained by calling `getAdapter(Class)` on this node's parent if there is one.

  Specified by:
    `getAdapter` in interface `IAdaptable`
  Parameters:
    `adapter` - the adapter class to look up
  Returns:
    the object adapted to the given class or `null`
  Since:
    3.3
  See Also:
    `IAdaptable.getAdapter(Class)`

### isReadOnly

    public boolean isReadOnly()

  Description copied from interface: `IEditableContentExtension`
  Return whether the typed element being displayed is read-only. a read-only element will require a call to validateEdit before the element can be modified on disk.

  Specified by:
    `isReadOnly` in interface `IEditableContentExtension`
  Returns:
    whether the typed element is read-only

### validateEdit

    public IStatus validateEdit(Shell shell)

  Description copied from interface: `IEditableContentExtension`
  If the element is read-only, this method should be called to attempt to make it writable.

  Specified by:
    `validateEdit` in interface `IEditableContentExtension`
  Parameters:
    `shell` - a shell used to prompt the user if required.
  Returns:
    a status object that is `OK` if things are fine, otherwise a status describing reasons why modifying the given files is not reasonable. A status with a severity of `CANCEL` is returned if the validation was canceled, indicating the edit should not proceed.

### getParentNode

    public Object getParentNode()

  Return the parent of this node or `null` if the node doesn't have a parent or the parent is not known.

  Returns:
    the parent of this node or `null`

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.