org.aspectj.ajde/source/org/aspectj/org/eclipse/jdt/core/IOpenable.java - ajdt/org.eclipse.ajdt - Git at Google

 /*******************************************************************************
  * Copyright (c) 2000, 2016 IBM Corporation and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
  * which accompanies this distribution, and is available at
  * https://www.eclipse.org/legal/epl-2.0/
  *
  * SPDX-License-Identifier: EPL-2.0
  *
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.aspectj.org.eclipse.jdt.core;

 import org.eclipse.core.resources.IProject;
 import org.eclipse.core.runtime.IProgressMonitor;

 /**
  * Common protocol for Java elements that must be opened before they can be
  * navigated or modified. Opening a textual element (such as a compilation unit)
  * involves opening a buffer on its contents.  While open, any changes to the buffer
  * can be reflected in the element's structure;
  * see {@link #isConsistent} and {@link #makeConsistent(IProgressMonitor)}.
  * <p>
  * To reduce complexity in clients, elements are automatically opened
  * by the Java model as element properties are accessed. The Java model maintains
  * an LRU cache of open elements, and automatically closes elements as they
  * are swapped out of the cache to make room for other elements. Elements with
  * unsaved changes are never removed from the cache, and thus, if the client
  * maintains many open elements with unsaved
  * changes, the LRU cache can grow in size (in this case the cache is not
  * bounded). However, as elements are saved, the cache will shrink back to its
  * original bounded size.
  * </p>
  * <p>
  * To open an element, all openable parent elements must be open.
  * The Java model automatically opens parent elements, as it automatically opens elements.
  * Opening an element may provide access to direct children and other descendants,
  * but does not automatically open any descendents which are themselves {@link IOpenable}.
  * For example, opening a compilation unit provides access to all its constituent elements,
  * but opening a package fragment does not open all compilation units in the package fragment.
  * </p>
  *
  * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface IOpenable {

 /**
  * Closes this element and its buffer (if any).
  * Closing an element which is not open has no effect.
  *
  * <p>Note: Although {@link #close} is exposed in the API, clients are
  * not expected to open and close elements - the Java model does this automatically
  * as elements are accessed.
  *
  * @exception JavaModelException if an error occurs closing this element
  */
 public void close() throws JavaModelException;
 /**
  * Finds and returns the recommended line separator for this element.
  * The element's buffer is first searched and the first line separator in this buffer is returned if any.
  * Otherwise the preference {@link org.eclipse.core.runtime.Platform#PREF_LINE_SEPARATOR}
  * on this element's project or workspace is returned.
  * Finally if no such preference is set, the system line separator is returned.
  *
  * @return the recommended line separator for this element
  * @exception JavaModelException if this element does not exist or if an
  *		exception occurs while accessing its corresponding resource.
  * @since 3.2
  */
 public String findRecommendedLineSeparator() throws JavaModelException;
 /**
  * Returns the buffer opened for this element, or <code>null</code>
  * if this element does not have a buffer.
  *
  * @exception JavaModelException if this element does not exist or if an
  *		exception occurs while accessing its corresponding resource.
  * @return the buffer opened for this element, or <code>null</code>
  * if this element does not have a buffer
  */
 public IBuffer getBuffer() throws JavaModelException;
 /**
  * Returns <code>true</code> if this element is open and:
  * <ul>
  * <li>its buffer has unsaved changes, or
  * <li>one of its descendants has unsaved changes, or
  * <li>a working copy has been created on one of this
  * element's children and has not yet destroyed
  * </ul>
  *
  * @exception JavaModelException if this element does not exist or if an
  *		exception occurs while accessing its corresponding resource.
  * @return <code>true</code> if this element is open and:
  * <ul>
  * <li>its buffer has unsaved changes, or
  * <li>one of its descendants has unsaved changes, or
  * <li>a working copy has been created on one of this
  * element's children and has not yet destroyed
  * </ul>
  */
 boolean hasUnsavedChanges() throws JavaModelException;
 /**
  * Returns whether the element is consistent with its underlying resource or buffer.
  * The element is consistent when opened, and is consistent if the underlying resource
  * or buffer has not been modified since it was last consistent.
  *
  * <p>NOTE: Child consistency is not considered. For example, a package fragment
  * responds <code>true</code> when it knows about all of its
  * compilation units present in its underlying folder. However, one or more of
  * the compilation units could be inconsistent.
  *
  * @exception JavaModelException if this element does not exist or if an
  *		exception occurs while accessing its corresponding resource.
  * @return true if the element is consistent with its underlying resource or buffer, false otherwise.
  * @see IOpenable#makeConsistent(IProgressMonitor)
  */
 boolean isConsistent() throws JavaModelException;
 /**
  * Returns whether this openable is open. This is a handle-only method.
  *
  * <p>Note: This method doesn't tell whether an {@link IJavaProject}'s {@link IJavaProject#getProject() getProject()} is open.
  * It is <b>not</b> equivalent to {@link IProject#isOpen()}!</p>
  *
  * <p>Note: Although {@link #isOpen} is exposed in the API, clients
  * rarely have a need to rely on this internal state of the Java model.</p>

  * @return true if this openable is open, false otherwise
  */
 boolean isOpen();
 /**
  * Makes this element consistent with its underlying resource or buffer
  * by updating the element's structure and properties as necessary.
  *<p>
  * Note: Using this functionality on a working copy will interfere with any
  * subsequent reconciling operation. Indeed, the next
  * {@link ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, IProgressMonitor)} or
  * {@link ICompilationUnit#reconcile(int, boolean, boolean, WorkingCopyOwner, IProgressMonitor)}
  * operation will not account for changes which occurred before an
  * explicit use of {@link #makeConsistent(IProgressMonitor)}
  * <p>
  * @param progress the given progress monitor
  * @exception JavaModelException if the element is unable to access the contents
  * 		of its underlying resource. Reasons include:
  * <ul>
  *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
  * </ul>
  * @see IOpenable#isConsistent()
  * @see ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, IProgressMonitor)
  */
 void makeConsistent(IProgressMonitor progress) throws JavaModelException;
 /**
  * Opens this element and all parent elements that are not already open.
  * For compilation units, a buffer is opened on the contents of the underlying resource.
  *
  * <p>Note: Although {@link #open} is exposed in the API, clients are
  * not expected to open and close elements - the Java model does this automatically
  * as elements are accessed.
  *
  * @param progress the given progress monitor
  * @exception JavaModelException if an error occurs accessing the contents
  * 		of its underlying resource. Reasons include:
  * <ul>
  *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
  * </ul>
  */
 public void open(IProgressMonitor progress) throws JavaModelException;
 /**
  * Saves any changes in this element's buffer to its underlying resource
  * via a workspace resource operation. This has no effect if the element has no underlying
  * buffer, or if there are no unsaved changed in the buffer.
  * <p>
  * The <code>force</code> parameter controls how this method deals with
  * cases where the workbench is not completely in sync with the local file system.
  * If <code>false</code> is specified, this method will only attempt
  * to overwrite a corresponding file in the local file system provided
  * it is in sync with the workbench. This option ensures there is no
  * unintended data loss; it is the recommended setting.
  * However, if <code>true</code> is specified, an attempt will be made
  * to write a corresponding file in the local file system,
  * overwriting any existing one if need be.
  * In either case, if this method succeeds, the resource will be marked
  * as being local (even if it wasn't before).
  * <p>
  * As a result of this operation, the element is consistent with its underlying
  * resource or buffer.
  *
  * @param progress the given progress monitor
  * @param force it controls how this method deals with
  * cases where the workbench is not completely in sync with the local file system
  * @exception JavaModelException if an error occurs accessing the contents
  * 		of its underlying resource. Reasons include:
  * <ul>
  *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
  *  <li>This Java element is read-only (READ_ONLY)</li>
  * </ul>
  */
 public void save(IProgressMonitor progress, boolean force) throws JavaModelException;
 }
	/*******************************************************************************
	* Copyright (c) 2000, 2016 IBM Corporation and others.
	*
	* This program and the accompanying materials
	* are made available under the terms of the Eclipse Public License 2.0
	* which accompanies this distribution, and is available at
	* https://www.eclipse.org/legal/epl-2.0/
	*
	* SPDX-License-Identifier: EPL-2.0
	*
	* Contributors:
	* IBM Corporation - initial API and implementation
	*******************************************************************************/
	package org.aspectj.org.eclipse.jdt.core;

	import org.eclipse.core.resources.IProject;
	import org.eclipse.core.runtime.IProgressMonitor;

	/**
	* Common protocol for Java elements that must be opened before they can be
	* navigated or modified. Opening a textual element (such as a compilation unit)
	* involves opening a buffer on its contents. While open, any changes to the buffer
	* can be reflected in the element's structure;
	* see {@link #isConsistent} and {@link #makeConsistent(IProgressMonitor)}.
	* <p>
	* To reduce complexity in clients, elements are automatically opened
	* by the Java model as element properties are accessed. The Java model maintains
	* an LRU cache of open elements, and automatically closes elements as they
	* are swapped out of the cache to make room for other elements. Elements with
	* unsaved changes are never removed from the cache, and thus, if the client
	* maintains many open elements with unsaved
	* changes, the LRU cache can grow in size (in this case the cache is not
	* bounded). However, as elements are saved, the cache will shrink back to its
	* original bounded size.
	* </p>
	* <p>
	* To open an element, all openable parent elements must be open.
	* The Java model automatically opens parent elements, as it automatically opens elements.
	* Opening an element may provide access to direct children and other descendants,
	* but does not automatically open any descendents which are themselves {@link IOpenable}.
	* For example, opening a compilation unit provides access to all its constituent elements,
	* but opening a package fragment does not open all compilation units in the package fragment.
	* </p>
	*
	* @noimplement This interface is not intended to be implemented by clients.
	*/
	public interface IOpenable {

	/**
	* Closes this element and its buffer (if any).
	* Closing an element which is not open has no effect.
	*
	* <p>Note: Although {@link #close} is exposed in the API, clients are
	* not expected to open and close elements - the Java model does this automatically
	* as elements are accessed.
	*
	* @exception JavaModelException if an error occurs closing this element
	*/
	public void close() throws JavaModelException;
	/**
	* Finds and returns the recommended line separator for this element.
	* The element's buffer is first searched and the first line separator in this buffer is returned if any.
	* Otherwise the preference {@link org.eclipse.core.runtime.Platform#PREF_LINE_SEPARATOR}
	* on this element's project or workspace is returned.
	* Finally if no such preference is set, the system line separator is returned.
	*
	* @return the recommended line separator for this element
	* @exception JavaModelException if this element does not exist or if an
	* exception occurs while accessing its corresponding resource.
	* @since 3.2
	*/
	public String findRecommendedLineSeparator() throws JavaModelException;
	/**
	* Returns the buffer opened for this element, or <code>null</code>
	* if this element does not have a buffer.
	*
	* @exception JavaModelException if this element does not exist or if an
	* exception occurs while accessing its corresponding resource.
	* @return the buffer opened for this element, or <code>null</code>
	* if this element does not have a buffer
	*/
	public IBuffer getBuffer() throws JavaModelException;
	/**
	* Returns <code>true</code> if this element is open and:
	* <ul>
	* <li>its buffer has unsaved changes, or
	* <li>one of its descendants has unsaved changes, or
	* <li>a working copy has been created on one of this
	* element's children and has not yet destroyed
	* </ul>
	*
	* @exception JavaModelException if this element does not exist or if an
	* exception occurs while accessing its corresponding resource.
	* @return <code>true</code> if this element is open and:
	* <ul>
	* <li>its buffer has unsaved changes, or
	* <li>one of its descendants has unsaved changes, or
	* <li>a working copy has been created on one of this
	* element's children and has not yet destroyed
	* </ul>
	*/
	boolean hasUnsavedChanges() throws JavaModelException;
	/**
	* Returns whether the element is consistent with its underlying resource or buffer.
	* The element is consistent when opened, and is consistent if the underlying resource
	* or buffer has not been modified since it was last consistent.
	*
	* <p>NOTE: Child consistency is not considered. For example, a package fragment
	* responds <code>true</code> when it knows about all of its
	* compilation units present in its underlying folder. However, one or more of
	* the compilation units could be inconsistent.
	*
	* @exception JavaModelException if this element does not exist or if an
	* exception occurs while accessing its corresponding resource.
	* @return true if the element is consistent with its underlying resource or buffer, false otherwise.
	* @see IOpenable#makeConsistent(IProgressMonitor)
	*/
	boolean isConsistent() throws JavaModelException;
	/**
	* Returns whether this openable is open. This is a handle-only method.
	*
	* <p>Note: This method doesn't tell whether an {@link IJavaProject}'s {@link IJavaProject#getProject() getProject()} is open.
	* It is <b>not</b> equivalent to {@link IProject#isOpen()}!</p>
	*
	* <p>Note: Although {@link #isOpen} is exposed in the API, clients
	* rarely have a need to rely on this internal state of the Java model.</p>

	* @return true if this openable is open, false otherwise
	*/
	boolean isOpen();
	/**
	* Makes this element consistent with its underlying resource or buffer
	* by updating the element's structure and properties as necessary.
	*<p>
	* Note: Using this functionality on a working copy will interfere with any
	* subsequent reconciling operation. Indeed, the next
	* {@link ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, IProgressMonitor)} or
	* {@link ICompilationUnit#reconcile(int, boolean, boolean, WorkingCopyOwner, IProgressMonitor)}
	* operation will not account for changes which occurred before an
	* explicit use of {@link #makeConsistent(IProgressMonitor)}
	* <p>
	* @param progress the given progress monitor
	* @exception JavaModelException if the element is unable to access the contents
	* of its underlying resource. Reasons include:
	* <ul>
	* <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
	* </ul>
	* @see IOpenable#isConsistent()
	* @see ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, IProgressMonitor)
	*/
	void makeConsistent(IProgressMonitor progress) throws JavaModelException;
	/**
	* Opens this element and all parent elements that are not already open.
	* For compilation units, a buffer is opened on the contents of the underlying resource.
	*
	* <p>Note: Although {@link #open} is exposed in the API, clients are
	* not expected to open and close elements - the Java model does this automatically
	* as elements are accessed.
	*
	* @param progress the given progress monitor
	* @exception JavaModelException if an error occurs accessing the contents
	* of its underlying resource. Reasons include:
	* <ul>
	* <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
	* </ul>
	*/
	public void open(IProgressMonitor progress) throws JavaModelException;
	/**
	* Saves any changes in this element's buffer to its underlying resource
	* via a workspace resource operation. This has no effect if the element has no underlying
	* buffer, or if there are no unsaved changed in the buffer.
	* <p>
	* The <code>force</code> parameter controls how this method deals with
	* cases where the workbench is not completely in sync with the local file system.
	* If <code>false</code> is specified, this method will only attempt
	* to overwrite a corresponding file in the local file system provided
	* it is in sync with the workbench. This option ensures there is no
	* unintended data loss; it is the recommended setting.
	* However, if <code>true</code> is specified, an attempt will be made
	* to write a corresponding file in the local file system,
	* overwriting any existing one if need be.
	* In either case, if this method succeeds, the resource will be marked
	* as being local (even if it wasn't before).
	* <p>
	* As a result of this operation, the element is consistent with its underlying
	* resource or buffer.
	*
	* @param progress the given progress monitor
	* @param force it controls how this method deals with
	* cases where the workbench is not completely in sync with the local file system
	* @exception JavaModelException if an error occurs accessing the contents
	* of its underlying resource. Reasons include:
	* <ul>
	* <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
	* <li>This Java element is read-only (READ_ONLY)</li>
	* </ul>
	*/
	public void save(IProgressMonitor progress, boolean force) throws JavaModelException;
	}