Package org.eclipse.compare.structuremergeviewer

# Class StructureCreator

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

All Implemented Interfaces:
  `IStructureCreator`, `IStructureCreator2`

public abstract class StructureCreator extends Object implements IStructureCreator2
An `IStructureCreator2` that attempts to use an `IDocumentProvider` to obtain a shared document for an `ITypedElement`.

Clients may subclass this class.

Since:
  3.3

## Constructor Summary

Constructors
Constructor
Description
`StructureCreator()`

## Method Summary

Modifier and Type
Method
Description
`boolean`
`contentsEquals(Object node1, char contributor1, Object node2, char contributor2, boolean ignoreWhitespace, ICompareFilter[] compareFilters)`
Returns true if the two nodes are equal for comparison purposes.
`ITypedElement`
`createElement(Object element, Object input, IProgressMonitor monitor)`
Default implementation of `createElement(Object, Object, IProgressMonitor)` that uses `getPath(Object, Object)` to determine the path for the element, `createStructure(Object, IProgressMonitor)` to create the structure and `findElement(IStructureComparator, String[])` to find the element in the structure.
`IStructureComparator`
`createStructure(Object element, IProgressMonitor monitor)`
Creates a tree structure consisting of `IStructureComparator`s from the given object and returns its root object.
`protected abstract IStructureComparator`
`createStructureComparator(Object element, IDocument document, ISharedDocumentAdapter sharedDocumentAdapter, IProgressMonitor monitor)`
Creates an `IStructureComparator` for the given element using the contents available in the given document.
`void`
`destroy(Object object)`
Release any resources associated with the given object.
`protected ITypedElement`
`findElement(IStructureComparator structure, String[] path)`
Finds the element at the given path in the given structure.
`protected IDocumentPartitioner`
`getDocumentPartitioner()`
Returns the partitioner to be associated with the document or `null` is partitioning is not needed or if the subclass overrode `setupDocument(IDocument)` directly.
`protected String`
`getDocumentPartitioning()`
Returns the partitioning to which the partitioner returned from `getDocumentPartitioner()` is to be associated.
`protected String[]`
`getPath(Object element, Object input)`
Returns the path of the element in the structure of it's containing input or `null` if the element is not contained in the input.
`IStructureComparator`
`getStructure(Object input)`
Creates a tree structure consisting of `IStructureComparator`s from the given object and returns its root object.
`IStructureComparator`
`locate(Object element, Object input)`
Default implementation of `locate(Object, Object)` that uses `getPath(Object, Object)` to determine the path for the element, `getStructure(Object)` to create the structure and `findElement(IStructureComparator, String[])` to find the element in the structure.
`void`
`save(IStructureComparator node, Object input)`
Default implementation of save that extracts the contents from the document of an `IDocumentRange` and sets it on the input.
`protected void`
`setupDocument(IDocument document)`
Sets up the newly created document as appropriate.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface org.eclipse.compare.structuremergeviewer.IStructureCreator

`getContents, getName`

## Constructor Details

### StructureCreator

public StructureCreator()

## Method Details

### getStructure

public IStructureComparator getStructure(Object input)
Description copied from interface: `IStructureCreator`
Creates a tree structure consisting of `IStructureComparator`s from the given object and returns its root object. Implementing this method typically involves parsing the input object. In case of an error (e.g. a parsing error) the value `null` is returned.

Specified by:
  `getStructure` in interface `IStructureCreator`
Parameters:
  `input` - the object from which to create the tree of `IStructureComparator`
Returns:
  the root node of the structure or `null` in case of error

### createStructure

public IStructureComparator createStructure(Object element, IProgressMonitor monitor) throws CoreException
Description copied from interface: `IStructureCreator2`
Creates a tree structure consisting of `IStructureComparator`s from the given object and returns its root object. Implementing this method typically involves parsing the input object. In case of an error (e.g. a parsing error) the value `null` is returned.

This method is equivalent to `IStructureCreator.getStructure(Object)` with the exception that the `IStructureCreator2.destroy(Object)` method must be called with the returned comparator as a parameter when the comparator is no longer needed. This is done to allow structure creators to make use of shared resources such a file buffer.

Also, the node returned from this method should adapt to an `ISharedDocumentAdapter` if the provided input has a shared document adapter and it is being used by the this creator. The convenience class `SharedDocumentAdapterWrapper` is provided to allow the creator to wrap the adapter of the input so that the proper key can be returned.

Specified by:
  `createStructure` in interface `IStructureCreator2`
Parameters:
  `element` - the object from which to create the tree of `IStructureComparator`
  `monitor` - a progress monitor or `null` if progress and cancelation is not required
Returns:
  the root node of the structure or `null` in case of error
Throws:
  `CoreException` - if structure creation failed; depends on actual implementation
See Also:
  - `IStructureCreator.getStructure(Object)`
  - `IStructureCreator2.destroy(Object)`

### createStructureComparator

protected abstract IStructureComparator createStructureComparator(Object element, IDocument document, ISharedDocumentAdapter sharedDocumentAdapter, IProgressMonitor monitor) throws CoreException
Creates an `IStructureComparator` for the given element using the contents available in the given document. If the provided `ISharedDocumentAdapter` is not `null` then the `IStructureComparator` returned by this method must implement the `IDisposable` interface and disconnect from the adapter when the comparator is disposed. The `StructureDiffViewer` class will call dispose if the `IStructureComparator` also implements `IDisposable`. Other clients must do the same.

It should be noted that the provided `ISharedDocumentAdapter` will provide the key associated with the given element when `ISharedDocumentAdapter.getDocumentKey(Object)` is called for any `IDocumentRange` node whose document matches the provided document. Thus, this adapter should also be returned by the structure comparator and its children when they are adapted to an `ISharedDocumentAdapter`.

Parameters:
  `element` - the element
  `document` - the document that has the contents for the element
  `sharedDocumentAdapter` - the shared document adapter from which the document was obtained or `null` if the document is not shared.
  `monitor` - a progress monitor or `null` if progress is not required
Returns:
  a structure comparator
Throws:
  `CoreException` - if creating the comparator failed; depends on actual implementation

### setupDocument

protected void setupDocument(IDocument document)
Sets up the newly created document as appropriate. Any document partitioners should be added to a custom slot using the `IDocumentExtension3` interface in case the document is shared via a file buffer.

Parameters:
  `document` - a document

### getDocumentPartitioner

protected IDocumentPartitioner getDocumentPartitioner()
Returns the partitioner to be associated with the document or `null` is partitioning is not needed or if the subclass overrode `setupDocument(IDocument)` directly.

Returns:
  a partitioner

### getDocumentPartitioning

protected String getDocumentPartitioning()
Returns the partitioning to which the partitioner returned from `getDocumentPartitioner()` is to be associated. Return `null` only if partitioning is not needed or if the subclass overrode `setupDocument(IDocument)` directly.

Returns:
  a partitioning
See Also:
  - `IDocumentExtension3`

### save

public void save(IStructureComparator node, Object input)
Default implementation of save that extracts the contents from the document of an `IDocumentRange` and sets it on the input. If the input is an `IEncodedStreamContentAccessor`, the charset of the input is used to extract the contents from the document. If the input adapts to `ISharedDocumentAdapter` and the document of the `IDocumentRange` matches that of the input, then the save is issued through the shared document adapter.

Specified by:
  `save` in interface `IStructureCreator`
Parameters:
  `node` - the node for which to save the new content
  `input` - the object from which the structure tree was created in `getStructure`
See Also:
  - `IStructureCreator.save(org.eclipse.compare.structuremergeviewer.IStructureComparator, java.lang.Object)`

### createElement

public ITypedElement createElement(Object element, Object input, IProgressMonitor monitor) throws CoreException
Default implementation of `createElement(Object, Object, IProgressMonitor)` that uses `getPath(Object, Object)` to determine the path for the element, `createStructure(Object, IProgressMonitor)` to create the structure and `findElement(IStructureComparator, String[])` to find the element in the structure. Subclasses may override.

Specified by:
  `createElement` in interface `IStructureCreator2`
Parameters:
  `element` - the element
  `input` - the containing input
  `monitor` - a progress monitor
Returns:
  the sub-structure element in the input for the given element
Throws:
  `CoreException` - if a parse error occurred
See Also:
  - `IStructureCreator.locate(Object, Object)`
  - `IStructureCreator2.destroy(Object)`

### locate

public IStructureComparator locate(Object element, Object input)
Default implementation of `locate(Object, Object)` that uses `getPath(Object, Object)` to determine the path for the element, `getStructure(Object)` to create the structure and `findElement(IStructureComparator, String[])` to find the element in the structure. Subclasses may override.

Specified by:
  `locate` in interface `IStructureCreator`
Parameters:
  `element` - the element
  `input` - the containing input
Returns:
  the sub-structure element in the input for the given element

### findElement

protected ITypedElement findElement(IStructureComparator structure, String[] path)
Finds the element at the given path in the given structure. This method is invoked from the `createElement(Object, Object, IProgressMonitor)` and `locate(Object, Object)` methods to find the element for the given path.

Parameters:
  `structure` - the structure
  `path` - the path of an element in the structure
Returns:
  the element at the given path in the structure or `null`

### getPath

protected String[] getPath(Object element, Object input)
Returns the path of the element in the structure of it's containing input or `null` if the element is not contained in the input. This method is invoked from `createElement(Object, Object, IProgressMonitor)` and `locate(Object, Object)` methods to determine the path to be passed to `findElement(IStructureComparator, String[])`. By default, `null` is returned. Subclasses may override.

Parameters:
  `element` - the element
  `input` - the input
Returns:
  the path of the element in the structure of it's containing input or `null`

### destroy

public void destroy(Object object)
Description copied from interface: `IStructureCreator2`
Release any resources associated with the given object. This method must be called for objects returned from either `IStructureCreator2.createStructure(Object, IProgressMonitor)` or `IStructureCreator2.createElement(Object, Object, IProgressMonitor)`.

Specified by:
  `destroy` in interface `IStructureCreator2`
Parameters:
  `object` - the object to be destroyed
See Also:
  - `IStructureCreator2.createElement(Object, Object, IProgressMonitor)`
  - `IStructureCreator2.createStructure(Object, IProgressMonitor)`

### contentsEquals

public boolean contentsEquals(Object node1, char contributor1, Object node2, char contributor2, boolean ignoreWhitespace, ICompareFilter[] compareFilters)
Returns true if the two nodes are equal for comparison purposes. If `compareFilters` is not empty, the filters are applied to each line of each node's text representation.

Parameters:
  `node1` - first node
  `contributor1` - either 'A', 'L', or 'R' for ancestor, left or right contributor
  `node2` - second node
  `contributor2` - either 'A', 'L', or 'R' for ancestor, left or right contributor
  `ignoreWhitespace` - if `true` whitespace characters will be ignored when determining equality. Note: Will bypass any custom ignore whitespace behaviors contributed through implementations of `org.eclipse.compare.structuremergeviewer.IStructureCreator.getContents()`
  `compareFilters` - the filters used to customize the comparison of lines of text.
Returns:
  whether the two nodes are equal for comparison purposes
Since:
  3.6
Restriction:
  This method is not intended to be referenced by clients.