IDocumentProviderExtension


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 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  
12  package org.eclipse.ui.texteditor;
13  
14  
15  import org.eclipse.core.runtime.CoreException;
16  import org.eclipse.core.runtime.IStatus;
17  
18  
19  /**
20   * Extension interface for {@link IDocumentProvider}. It adds the following
21   * functions:
22   * <ul>
23   * <li> dealing with immutable domain elements
24   * <li> state validation
25   * <li> persistent status of domain element operations
26   * <li> extended synchronization support
27   * </ul>
28   * @since 2.0
29   */
30  public interface IDocumentProviderExtension {
31  
32      /**
33       * Returns whether the document provider thinks that the given element is read-only.
34       * If this method returns <code>true</code>, <code>saveDocument</code> could fail.
35       * This method does not say anything about the document constructed from the given
36       * element. If the given element is not connected to this document provider, the return
37       * value is undefined. Document providers are allowed to use a cache to answer this
38       * question, i.e. there can be a difference between the "real" state of the element and
39       * the return value.
40       *
41       * @param element the element
42       * @return <code>true</code> if the given element is read-only, <code>false</code> otherwise
43       */
44      boolean isReadOnly(Object   element);
45  
46      /**
47       * Returns whether the document provider thinks that the given element can persistently be modified.
48       * This is orthogonal to <code>isReadOnly</code> as read-only elements may be modifiable and
49       * writable elements may not be modifiable. If the given element is not connected to this document
50       * provider, the result is undefined. Document providers are allowed to use a cache to answer this
51       * question, i.e. there can be a difference between the "real" state of the element and the return
52       * value.
53       *
54       * @param element the element
55       * @return <code>true</code> if the given element is modifiable, <code>false</code> otherwise
56       */
57      boolean isModifiable(Object   element);
58  
59      /**
60       * Validates the state of the given element. This method  may change the "real" state of the
61       * element. If using, it also updates the internal caches, so that this method may also change
62       * the results returned by <code>isReadOnly</code> and <code>isModifiable</code>. If the
63       * given element is not connected to this document provider, the effect is undefined.
64       *
65       * @param element the element
66       * @param computationContext the context in which the computation is performed, e.g., a SWT shell
67       * @exception CoreException if validating fails
68       */
69      void validateState(Object   element, Object   computationContext) throws CoreException;
70  
71      /**
72       * Returns whether the state of the given element has been validated.
73       *
74       * @param element the element
75       * @return <code>true</code> if the state has been validated
76       */
77      boolean isStateValidated(Object   element);
78  
79      /**
80       * Updates the state cache for the given element. This method may change the result returned
81       * by <code>isReadOnly</code> and <code>isModifiable</code>. If the given element is not
82       * connected to this document provider, the effect is undefined.
83       *
84       * @param element the element
85       * @exception CoreException if validating fails
86       */
87      void updateStateCache(Object   element) throws CoreException;
88  
89      /**
90       * Marks the document managed for the given element as savable. I.e.
91       * <code>canBeSaved(element)</code> will return <code>true</code>
92       * afterwards.
93       *
94       * @param element the element
95       */
96      void setCanSaveDocument(Object   element);
97  
98      /**
99       * Returns the status of the given element.
100      *
101      * @param element the element
102      * @return the status of the given element
103      */
104     IStatus getStatus(Object   element);
105 
106     /**
107      * Synchronizes the document provided for the given element with the
108      * given element. After that call <code>getSynchronizationTimeStamp</code>
109      * and <code>getModificationTimeStamp</code> return the same value.
110      *
111      * @param element the element
112      * @exception CoreException  if the synchronization could not be performed
113      */
114     void synchronize(Object   element) throws CoreException;
115 }
116
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags