net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IOpenable.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2003 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Common Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/cpl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.core;
  12
  13 import org.eclipse.core.runtime.IProgressMonitor;
  14 import net.sourceforge.phpdt.core.JavaModelException;
  15
  16
  17 /**
  18  * Common protocol for Java elements that must be opened before they can be
  19  * navigated or modified. Opening a textual element (such as a compilation unit)
  20  * involves opening a buffer on its contents.  While open, any changes to the buffer
  21  * can be reflected in the element's structure;
  22  * see <code>isConsistent</code> and <code>makeConsistent(IProgressMonitor)</code>.
  23  * <p>
  24  * To reduce complexity in clients, elements are automatically opened
  25  * by the Java model as element properties are accessed. The Java model maintains
  26  * an LRU cache of open elements, and automatically closes elements as they
  27  * are swapped out of the cache to make room for other elements. Elements with
  28  * unsaved changes are never removed from the cache, and thus, if the client
  29  * maintains many open elements with unsaved
  30  * changes, the LRU cache can grow in size (in this case the cache is not
  31  * bounded). However, as elements are saved, the cache will shrink back to its
  32  * original bounded size.
  33  * </p>
  34  * <p>
  35  * To open an element, all openable parent elements must be open.
  36  * The Java model automatically opens parent elements, as it automatically opens elements.
  37  * Opening an element may provide access to direct children and other descendants,
  38  * but does not automatically open any descendents which are themselves <code>IOpenable</code>.
  39  * For example, opening a compilation unit provides access to all its constituent elements,
  40  * but opening a package fragment does not open all compilation units in the package fragment.
  41  * </p>
  42  * <p>
  43  * This interface is not intended to be implemented by clients.
  44  * </p>
  45  */
  46 public interface IOpenable {
  47
  48 /**
  49  * Closes this element and its buffer (if any).
  50  * Closing an element which is not open has no effect.
  51  *
  52  * <p>Note: although <code>close</code> is exposed in the API, clients are
  53  * not expected to open and close elements - the Java model does this automatically
  54  * as elements are accessed.
  55  *
  56  * @exception JavaModelException if an error occurs closing this element
  57  */
  58 public void close() throws JavaModelException;
  59 /**
  60  * Returns the buffer opened for this element, or <code>null</code>
  61  * if this element does not have a buffer.
  62  *
  63  * @exception JavaModelException if this element does not exist or if an
  64  *              exception occurs while accessing its corresponding resource.
  65  * @return the buffer opened for this element, or <code>null</code>
  66  * if this element does not have a buffer
  67  */
  68 public IBuffer getBuffer() throws JavaModelException;
  69 /**
  70  * Returns <code>true</code> if this element is open and:
  71  * <ul>
  72  * <li>its buffer has unsaved changes, or
  73  * <li>one of its descendants has unsaved changes, or
  74  * <li>a working copy has been created on one of this
  75  * element's children and has not yet destroyed
  76  * </ul>
  77  *
  78  * @exception JavaModelException if this element does not exist or if an
  79  *              exception occurs while accessing its corresponding resource.
  80  * @return <code>true</code> if this element is open and:
  81  * <ul>
  82  * <li>its buffer has unsaved changes, or
  83  * <li>one of its descendants has unsaved changes, or
  84  * <li>a working copy has been created on one of this
  85  * element's children and has not yet destroyed
  86  * </ul>
  87  */
  88 boolean hasUnsavedChanges() throws JavaModelException;
  89 /**
  90  * Returns whether the element is consistent with its underlying resource or buffer.
  91  * The element is consistent when opened, and is consistent if the underlying resource
  92  * or buffer has not been modified since it was last consistent.
  93  *
  94  * <p>NOTE: Child consistency is not considered. For example, a package fragment
  95  * responds <code>true</code> when it knows about all of its
  96  * compilation units present in its underlying folder. However, one or more of
  97  * the compilation units could be inconsistent.
  98  *
  99  * @exception JavaModelException if this element does not exist or if an
 100  *              exception occurs while accessing its corresponding resource.
 101  * @return true if the element is consistent with its underlying resource or buffer, false otherwise.
 102  * @see IOpenable#makeConsistent
 103  */
 104 boolean isConsistent() throws JavaModelException;
 105 /**
 106  * Returns whether this openable is open. This is a handle-only method.
 107  * @return true if this openable is open, false otherwise
 108  */
 109 boolean isOpen();
 110 /**
 111  * Opens this element and all parent elements that are not already open.
 112  * For compilation units, a buffer is opened on the contents of the underlying resource.
 113  *
 114  * <p>Note: although <code>open</code> is exposed in the API, clients are
 115  * not expected to open and close elements - the Java model does this automatically
 116  * as elements are accessed.
 117  *
 118  * @param progress the given progress monitor
 119  * @exception JavaModelException if an error occurs accessing the contents
 120  *              of its underlying resource. Reasons include:
 121  * <ul>
 122  *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 123  * </ul>
 124  */
 125 public void open(IProgressMonitor progress) throws JavaModelException;
 126 /**
 127  * Makes this element consistent with its underlying resource or buffer
 128  * by updating the element's structure and properties as necessary.
 129  *
 130  * @param progress the given progress monitor
 131  * @exception JavaModelException if the element is unable to access the contents
 132  *              of its underlying resource. Reasons include:
 133  * <ul>
 134  *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 135  * </ul>
 136  * @see IOpenable#isConsistent
 137  */
 138 void makeConsistent(IProgressMonitor progress) throws JavaModelException;
 139 /**
 140  * Opens this element and all parent elements that are not already open.
 141  * For compilation units, a buffer is opened on the contents of the underlying resource.
 142  *
 143  * <p>Note: although <code>open</code> is exposed in the API, clients are
 144  * not expected to open and close elements - the Java model does this automatically
 145  * as elements are accessed.
 146  *
 147  * @param progress the given progress monitor
 148  * @exception JavaModelException if an error occurs accessing the contents
 149  *              of its underlying resource. Reasons include:
 150  * <ul>
 151  *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 152  * </ul>
 153  */
 154 //public void open(IProgressMonitor progress) throws JavaModelException;
 155 /**
 156  * Saves any changes in this element's buffer to its underlying resource
 157  * via a workspace resource operation. This has no effect if the element has no underlying
 158  * buffer, or if there are no unsaved changed in the buffer.
 159  * <p>
 160  * The <code>force</code> parameter controls how this method deals with
 161  * cases where the workbench is not completely in sync with the local file system.
 162  * If <code>false</code> is specified, this method will only attempt
 163  * to overwrite a corresponding file in the local file system provided
 164  * it is in sync with the workbench. This option ensures there is no
 165  * unintended data loss; it is the recommended setting.
 166  * However, if <code>true</code> is specified, an attempt will be made
 167  * to write a corresponding file in the local file system,
 168  * overwriting any existing one if need be.
 169  * In either case, if this method succeeds, the resource will be marked
 170  * as being local (even if it wasn't before).
 171  * <p>
 172  * As a result of this operation, the element is consistent with its underlying
 173  * resource or buffer.
 174  *
 175  * @param progress the given progress monitor
 176  * @param force it controls how this method deals with
 177  * cases where the workbench is not completely in sync with the local file system
 178  * @exception JavaModelException if an error occurs accessing the contents
 179  *              of its underlying resource. Reasons include:
 180  * <ul>
 181  *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 182  *  <li>This Java element is read-only (READ_ONLY)</li>
 183  * </ul>
 184  */
 185 public void save(IProgressMonitor progress, boolean force) throws JavaModelException;
 186
 187 }