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 IStructureComparators 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 IStructureComparators 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 IStructureComparators 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 IStructureComparators 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.