| /******************************************************************************* |
| * Copyright (c) 2006, 2011 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.compare.structuremergeviewer; |
| |
| import org.eclipse.compare.ISharedDocumentAdapter; |
| import org.eclipse.compare.ITypedElement; |
| import org.eclipse.core.runtime.CoreException; |
| import org.eclipse.core.runtime.IProgressMonitor; |
| |
| /** |
| * An extension to the {@link IStructureCreator} interface that supports the |
| * use of shared documents. |
| * <p> |
| * This interface is not intended to be implemented by clients. Client should instead |
| * subclass {@link StructureCreator}. |
| * </p> |
| * @since 3.3 |
| */ |
| public interface IStructureCreator2 extends IStructureCreator { |
| |
| /** |
| * Creates a tree structure consisting of <code>IStructureComparator</code>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 <code>null</code> is returned. |
| * <p> |
| * This method is equivalent to |
| * {@link IStructureCreator#getStructure(Object)} with the exception that |
| * the {@link #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. |
| * <p> |
| * Also, the node returned from this method should adapt to an |
| * {@link ISharedDocumentAdapter} if the provided input has |
| * a shared document adapter and it is being used by the |
| * this creator. The convenience class {@link SharedDocumentAdapterWrapper} |
| * is provided to allow the creator to wrap the adapter of the input |
| * so that the proper key can be returned. |
| * |
| * @param input |
| * the object from which to create the tree of |
| * <code>IStructureComparator</code> |
| * @param monitor a progress monitor or <code>null</code> if progress and cancelation is not required |
| * @return the root node of the structure or <code>null</code> in case of |
| * error |
| * @throws CoreException |
| * @see IStructureCreator#getStructure(Object) |
| * @see #destroy(Object) |
| */ |
| IStructureComparator createStructure(Object input, IProgressMonitor monitor) throws CoreException; |
| |
| /** |
| * Creates the single node specified by path from the given input object. |
| * This method is equivalent to |
| * {@link IStructureCreator#locate(Object, Object)} with the exception that |
| * the {@link #destroy(Object)} method must be called with the returned |
| * element as a parameter when the element is no longer |
| * needed. This is done to allow structure creators |
| * to make use of shared resources such a file buffer. |
| * |
| * @param element specifies a sub object within the input object |
| * @param input the object from which to create the |
| * <code>ITypedElement</code> |
| * @param monitor a progress monitor or <code>null</code> if progress is not desired |
| * @return the single node specified by <code>path</code> or |
| * <code>null</code> |
| * @throws CoreException if an error occurs while parsing the input |
| * |
| * @see IStructureCreator#locate(Object, Object) |
| * @see #destroy(Object) |
| */ |
| ITypedElement createElement(Object element, Object input, IProgressMonitor monitor) throws CoreException; |
| |
| /** |
| * Release any resources associated with the given object. |
| * This method must be called for objects returned from either |
| * {@link #createStructure(Object, IProgressMonitor)} or |
| * {@link #createElement(Object, Object, IProgressMonitor)}. |
| * @param object the object to be destroyed |
| * @see #createElement(Object, Object, IProgressMonitor) |
| * @see #createStructure(Object, IProgressMonitor) |
| */ |
| void destroy(Object object); |
| } |