KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > compare > ISharedDocumentAdapter


1 /*******************************************************************************
2  * Copyright (c) 2000, 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;
12
13 import org.eclipse.compare.structuremergeviewer.SharedDocumentAdapterWrapper;
14 import org.eclipse.core.runtime.CoreException;
15 import org.eclipse.core.runtime.IProgressMonitor;
16 import org.eclipse.jface.text.IDocument;
17 import org.eclipse.ui.IEditorInput;
18 import org.eclipse.ui.texteditor.IDocumentProvider;
19
20 /**
21  * An <code>ISharedDocumentAdapter</code> is used to map an {@link ITypedElement} to
22  * a shared document for the purposes of editing.
23  * <p>
24  * Clients are not expected to implement this interface but instead should subclass
25  * {@link SharedDocumentAdapter} or {@link SharedDocumentAdapterWrapper}.
26  * </p>
27  * @since 3.3
28  */
29 public interface ISharedDocumentAdapter {
30
31     /**
32      * Return the object that is to be used as the key for retrieving the
33      * appropriate {@link IDocumentProvider} from the
34      * <code>DocumentProviderRegistry</code> and for obtaining the shared
35      * {@link IDocument} from the document provider. Returns <code>null</code>
36      * if the element does not have a shared document.
37      *
38      * @param element
39      * the element being queried for a shared document
40      * @return the object that acts as the key to obtain a document provider and
41      * document or <code>null</code>
42      */
43     IEditorInput getDocumentKey(Object JavaDoc element);
44     
45     /**
46      * Connect the given element to its document provider. All connections must be performed
47      * through this adapter so that the adapter can track whether it is connected or not.
48      * @param provider the document provider
49      * @param documentKey the element's key returned from {@link #getDocumentKey(Object)}
50      * @throws CoreException if connection was not possible
51      * @see IDocumentProvider#connect(Object)
52      */
53     void connect(IDocumentProvider provider, IEditorInput documentKey) throws CoreException;
54     
55     /**
56      * Disconnect the element from the document provider. All connects and
57      * disconnects must occur through the adapter so that the adapter can
58      * track whether it is connected or not.
59      * @param provider the document provider
60      * @param documentKey the element's key returned from {@link #getDocumentKey(Object)}
61      * @see IDocumentProvider#disconnect(Object)
62      */
63     void disconnect(IDocumentProvider provider, IEditorInput documentKey);
64     
65     /**
66      * A helper disconnect method that looks up the appropriate key (using {@link #getDocumentKey(Object)}
67      * and the appropriate provider and calls {@link #disconnect(IDocumentProvider, IEditorInput)}.
68      * @param element the element that was used to previously connect to a document
69      * @see IDocumentProvider#disconnect(Object)
70      */
71     void disconnect(Object JavaDoc element);
72     
73     /**
74      * Flush the contents of the given document into the typed element that provided the
75      * document. This method is invoked by the Compare framework classes
76      * when a request to flush the viewers has been made. It is up to the implementor to decide
77      * whether the changes in the buffer should be saved to disk at the time of the flush or
78      * buffered to be saved at a later time.
79      *
80      * @param provider the document provider
81      * @param documentKey the element's key returned from {@link #getDocumentKey(Object)}
82      * @param document the document
83      * @param overwrite indicates whether overwrite should be performed
84      * while saving the given element if necessary
85      * @exception CoreException if document could not be stored to the given element
86      * @see IDocumentProvider#saveDocument(IProgressMonitor, Object, IDocument, boolean)
87      */
88     void flushDocument(IDocumentProvider provider, IEditorInput documentKey, IDocument document, boolean overwrite) throws CoreException;
89
90 }
91
Popular Tags