001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.texteditor;
011:
012: import org.eclipse.core.runtime.CoreException;
013: import org.eclipse.core.runtime.IStatus;
014:
015: /**
016: * Extension interface for {@link IDocumentProvider}. It adds the following
017: * functions:
018: * <ul>
019: * <li> dealing with immutable domain elements
020: * <li> state validation
021: * <li> persistent status of domain element operations
022: * <li> extended synchronization support
023: * </ul>
024: * @since 2.0
025: */
026: public interface IDocumentProviderExtension {
027:
028: /**
029: * Returns whether the document provider thinks that the given element is read-only.
030: * If this method returns <code>true</code>, <code>saveDocument</code> could fail.
031: * This method does not say anything about the document constructed from the given
032: * element. If the given element is not connected to this document provider, the return
033: * value is undefined. Document providers are allowed to use a cache to answer this
034: * question, i.e. there can be a difference between the "real" state of the element and
035: * the return value.
036: *
037: * @param element the element
038: * @return <code>true</code> if the given element is read-only, <code>false</code> otherwise
039: */
040: boolean isReadOnly(Object element);
041:
042: /**
043: * Returns whether the document provider thinks that the given element can persistently be modified.
044: * This is orthogonal to <code>isReadOnly</code> as read-only elements may be modifiable and
045: * writable elements may not be modifiable. If the given element is not connected to this document
046: * provider, the result is undefined. Document providers are allowed to use a cache to answer this
047: * question, i.e. there can be a difference between the "real" state of the element and the return
048: * value.
049: *
050: * @param element the element
051: * @return <code>true</code> if the given element is modifiable, <code>false</code> otherwise
052: */
053: boolean isModifiable(Object element);
054:
055: /**
056: * Validates the state of the given element. This method may change the "real" state of the
057: * element. If using, it also updates the internal caches, so that this method may also change
058: * the results returned by <code>isReadOnly</code> and <code>isModifiable</code>. If the
059: * given element is not connected to this document provider, the effect is undefined.
060: *
061: * @param element the element
062: * @param computationContext the context in which the computation is performed, e.g., a SWT shell
063: * @exception CoreException if validating fails
064: */
065: void validateState(Object element, Object computationContext)
066: throws CoreException;
067:
068: /**
069: * Returns whether the state of the given element has been validated.
070: *
071: * @param element the element
072: * @return <code>true</code> if the state has been validated
073: */
074: boolean isStateValidated(Object element);
075:
076: /**
077: * Updates the state cache for the given element. This method may change the result returned
078: * by <code>isReadOnly</code> and <code>isModifiable</code>. If the given element is not
079: * connected to this document provider, the effect is undefined.
080: *
081: * @param element the element
082: * @exception CoreException if validating fails
083: */
084: void updateStateCache(Object element) throws CoreException;
085:
086: /**
087: * Marks the document managed for the given element as savable. I.e.
088: * <code>canBeSaved(element)</code> will return <code>true</code>
089: * afterwards.
090: *
091: * @param element the element
092: */
093: void setCanSaveDocument(Object element);
094:
095: /**
096: * Returns the status of the given element.
097: *
098: * @param element the element
099: * @return the status of the given element
100: */
101: IStatus getStatus(Object element);
102:
103: /**
104: * Synchronizes the document provided for the given element with the
105: * given element. After that call <code>getSynchronizationTimeStamp</code>
106: * and <code>getModificationTimeStamp</code> return the same value.
107: *
108: * @param element the element
109: * @exception CoreException if the synchronization could not be performed
110: */
111: void synchronize(Object element) throws CoreException;
112: }
|