Interface IOpenable

  • All Known Subinterfaces:
    IClassFile, ICompilationUnit, IJavaModel, IJavaProject, IModularClassFile, IOrdinaryClassFile, IPackageFragment, IPackageFragmentRoot, ITypeRoot

    public interface IOpenable
    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.

    Restriction:
    This interface is not intended to be implemented by clients.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void close()
      Closes this element and its buffer (if any).
      String findRecommendedLineSeparator()
      Finds and returns the recommended line separator for this element.
      IBuffer getBuffer()
      Returns the buffer opened for this element, or null if this element does not have a buffer.
      boolean hasUnsavedChanges()
      Returns true if this element is open and: its buffer has unsaved changes, or one of its descendants has unsaved changes, or a working copy has been created on one of this element's children and has not yet destroyed
      boolean isConsistent()
      Returns whether the element is consistent with its underlying resource or buffer.
      boolean isOpen()
      Returns whether this openable is open.
      void makeConsistent​(IProgressMonitor progress)
      Makes this element consistent with its underlying resource or buffer by updating the element's structure and properties as necessary.
      void open​(IProgressMonitor progress)
      Opens this element and all parent elements that are not already open.
      void save​(IProgressMonitor progress, boolean force)
      Saves any changes in this element's buffer to its underlying resource via a workspace resource operation.
    • Method Detail

      • close

        void close()
            throws JavaModelException
        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.

        Throws:
        JavaModelException - if an error occurs closing this element
      • findRecommendedLineSeparator

        String findRecommendedLineSeparator()
                                     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 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.
        Returns:
        the recommended line separator for this element
        Throws:
        JavaModelException - if this element does not exist or if an exception occurs while accessing its corresponding resource.
        Since:
        3.2
      • getBuffer

        IBuffer getBuffer()
                   throws JavaModelException
        Returns the buffer opened for this element, or null if this element does not have a buffer.
        Returns:
        the buffer opened for this element, or null if this element does not have a buffer
        Throws:
        JavaModelException - if this element does not exist or if an exception occurs while accessing its corresponding resource.
      • hasUnsavedChanges

        boolean hasUnsavedChanges()
                           throws JavaModelException
        Returns true if this element is open and:
        • its buffer has unsaved changes, or
        • one of its descendants has unsaved changes, or
        • a working copy has been created on one of this element's children and has not yet destroyed
        Returns:
        true if this element is open and:
        • its buffer has unsaved changes, or
        • one of its descendants has unsaved changes, or
        • a working copy has been created on one of this element's children and has not yet destroyed
        Throws:
        JavaModelException - if this element does not exist or if an exception occurs while accessing its corresponding resource.
      • isConsistent

        boolean isConsistent()
                      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.

        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.

        Returns:
        true if the element is consistent with its underlying resource or buffer, false otherwise.
        Throws:
        JavaModelException - if this element does not exist or if an exception occurs while accessing its corresponding resource.
        See Also:
        makeConsistent(IProgressMonitor)
      • isOpen

        boolean isOpen()
        Returns whether this openable is open. This is a handle-only method.

        Note: This method doesn't tell whether an IJavaProject's getProject() is open. It is not equivalent to IProject.isOpen()!

        Note: Although isOpen() is exposed in the API, clients rarely have a need to rely on this internal state of the Java model.

        Returns:
        true if this openable is open, false otherwise
      • open

        void open​(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.

        Note: Although open(org.eclipse.core.runtime.IProgressMonitor) is exposed in the API, clients are not expected to open and close elements - the Java model does this automatically as elements are accessed.

        Parameters:
        progress - the given progress monitor
        Throws:
        JavaModelException - if an error occurs accessing the contents of its underlying resource. Reasons include:
        • This Java element does not exist (ELEMENT_DOES_NOT_EXIST)
      • save

        void save​(IProgressMonitor progress,
                  boolean force)
           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.

        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.

        Parameters:
        progress - the given progress monitor
        force - it controls how this method deals with cases where the workbench is not completely in sync with the local file system
        Throws:
        JavaModelException - if an error occurs accessing the contents of its underlying resource. Reasons include:
        • This Java element does not exist (ELEMENT_DOES_NOT_EXIST)
        • This Java element is read-only (READ_ONLY)