KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > compare > structuremergeviewer > IStructureCreator2


1 /*******************************************************************************
2  * Copyright (c) 2006, 2007 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.compare.structuremergeviewer;
12
13 import org.eclipse.compare.ISharedDocumentAdapter;
14 import org.eclipse.compare.ITypedElement;
15 import org.eclipse.core.runtime.CoreException;
16 import org.eclipse.core.runtime.IProgressMonitor;
17
18 /**
19  * An extension to the {@link IStructureCreator} interface that supports the
20  * use of shared documents.
21  * <p>
22  * This interface is not intended to be implemented by clients. Client should instead
23  * subclass {@link StructureCreator}.
24  * </p>
25  * @since 3.3
26  */
27 public interface IStructureCreator2 extends IStructureCreator {
28     
29     /**
30      * Creates a tree structure consisting of <code>IStructureComparator</code>s
31      * from the given object and returns its root object. Implementing this
32      * method typically involves parsing the input object. In case of an error
33      * (e.g. a parsing error) the value <code>null</code> is returned.
34      * <p>
35      * This method is equivalent to
36      * {@link IStructureCreator#getStructure(Object)} with the exception that
37      * the {@link #destroy(Object)} method must be called with the returned
38      * comparator as a parameter when the comparator is no longer
39      * needed. This is done to allow structure creators
40      * to make use of shared resources such a file buffer.
41      * <p>
42      * Also, the node returned from this method should adapt to an
43      * {@link ISharedDocumentAdapter} if the provided input has
44      * a shared document adapter and it is being used by the
45      * this creator. The convenience class {@link SharedDocumentAdapterWrapper}
46      * is provided to allow the creator to wrap the adapter of the input
47      * so that the proper key can be returned.
48      *
49      * @param input
50      * the object from which to create the tree of
51      * <code>IStructureComparator</code>
52      * @param monitor a progress monitor or <code>null</code> if progress and cancelation is not required
53      * @return the root node of the structure or <code>null</code> in case of
54      * error
55      * @throws CoreException
56      * @see IStructureCreator#getStructure(Object)
57      * @see #destroy(Object)
58      */
59     IStructureComparator createStructure(Object JavaDoc input, IProgressMonitor monitor) throws CoreException;
60     
61     /**
62      * Creates the single node specified by path from the given input object.
63      * This method is equivalent to
64      * {@link IStructureCreator#locate(Object, Object)} with the exception that
65      * the {@link #destroy(Object)} method must be called with the returned
66      * element as a parameter when the element is no longer
67      * needed. This is done to allow structure creators
68      * to make use of shared resources such a file buffer.
69      *
70      * @param element specifies a sub object within the input object
71      * @param input the object from which to create the
72      * <code>ITypedElement</code>
73      * @param monitor a progress monitor or <code>null</code> if progress is not desired
74      * @return the single node specified by <code>path</code> or
75      * <code>null</code>
76      * @throws CoreException if an error occurs while parsing the input
77      *
78      * @see IStructureCreator#locate(Object, Object)
79      * @see #destroy(Object)
80      */
81     ITypedElement createElement(Object JavaDoc element, Object JavaDoc input, IProgressMonitor monitor) throws CoreException;
82     
83     /**
84      * Release any resources associated with the given object.
85      * This method must be called for objects returned from either
86      * {@link #createStructure(Object, IProgressMonitor)} or
87      * {@link #createElement(Object, Object, IProgressMonitor)}.
88      * @param object the object to be destroyed
89      * @see #createElement(Object, Object, IProgressMonitor)
90      * @see #createStructure(Object, IProgressMonitor)
91      */
92     void destroy(Object JavaDoc object);
93 }
94
Popular Tags