/*******************************************************************************
* Copyright (c) 2000, 2003 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Common Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/cpl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package net.sourceforge.phpdt.core;
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
* isConsistent
and makeConsistent(IProgressMonitor)
.
*
* 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. *
*
* 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 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.
*
* 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. * *
* Note: although 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;
/**
* Returns the buffer opened for this element, or null
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 null
if
* this element does not have a buffer
*/
public IBuffer getBuffer() throws JavaModelException;
/**
* Returns true
if this element is open and:
*
true
if this element is open and:
*
* NOTE: Child consistency is not considered. For example, a package
* fragment responds true
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
*/
boolean isConsistent() throws JavaModelException;
/**
* Returns whether this openable is open. This is a handle-only method.
*
* @return true if this openable is open, false otherwise
*/
boolean isOpen();
/**
* 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.
*
*
* Note: although 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:
*
* Note: although 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:
*
* The force
parameter controls how this method deals with
* cases where the workbench is not completely in sync with the local file
* system. If false
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
* true
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).
*
* 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: *