net.sourceforge.phpeclipse.xdebug.core/src/net/sourceforge/phpeclipse/xdebug/php/model/ITypeRoot.java

   1 /*******************************************************************************
   2  * Copyright (c) 2006, 2007 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Eclipse Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/epl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpeclipse.xdebug.php.model;
  12
  13 import net.sourceforge.phpdt.core.ICodeAssist;
  14 import net.sourceforge.phpdt.core.ICompilationUnit;
  15 import net.sourceforge.phpdt.core.IOpenable;
  16 import net.sourceforge.phpdt.core.IJavaElement;
  17 import net.sourceforge.phpdt.core.IParent;
  18 import net.sourceforge.phpdt.core.ISourceReference;
  19 import net.sourceforge.phpdt.core.IType;
  20 import net.sourceforge.phpdt.core.JavaModelException;
  21 import net.sourceforge.phpdt.core.WorkingCopyOwner;
  22
  23 import org.eclipse.core.runtime.IProgressMonitor;
  24
  25
  26 /**
  27  * Represents an entire Java type root (either an <code>ICompilationUnit</code>
  28  * or an <code>IClassFile</code>).
  29  *
  30  * <p>
  31  * This interface is not intended to be implemented by clients.
  32  * </p>
  33  *
  34  * @see ICompilationUnit Note that methods {@link #findPrimaryType()} and {@link #getElementAt(int)}
  35  *      were already implemented in this interface respectively since version 3.0 and version 1.0.
  36  * @see IClassFile Note that method {@link #getWorkingCopy(WorkingCopyOwner, IProgressMonitor)}
  37  *      was already implemented in this interface since version 3.0.
  38  * @since 3.3
  39  */
  40 public interface ITypeRoot extends IJavaElement, IParent, IOpenable, ISourceReference, ICodeAssist {
  41
  42 /**
  43  * Finds the primary type of this Java type root (that is, the type with the same name as the
  44  * compilation unit, or the type of a class file), or <code>null</code> if no such a type exists.
  45  *
  46  * @return the found primary type of this Java type root, or <code>null</code> if no such a type exists
  47  */
  48 IType findPrimaryType();
  49
  50 /**
  51  * Returns the smallest element within this Java type root that
  52  * includes the given source position (that is, a method, field, etc.), or
  53  * <code>null</code> if there is no element other than the Java type root
  54  * itself at the given position, or if the given position is not
  55  * within the source range of the source of this Java type root.
  56  *
  57  * @param position a source position inside the Java type root
  58  * @return the innermost Java element enclosing a given source position or <code>null</code>
  59  *      if none (excluding the Java type root).
  60  * @throws JavaModelException if the Java type root does not exist or if an
  61  *      exception occurs while accessing its corresponding resource
  62  */
  63 IJavaElement getElementAt(int position) throws JavaModelException;
  64
  65 /**
  66  * Returns a shared working copy on this compilation unit or class file using the given working copy owner to create
  67  * the buffer. If this is already a working copy of the given owner, the element itself is returned.
  68  * This API can only answer an already existing working copy if it is based on the same
  69  * original Java type root AND was using the same working copy owner (that is, as defined by {@link Object#equals}).
  70  * <p>
  71  * The life time of a shared working copy is as follows:
  72  * <ul>
  73  * <li>The first call to {@link #getWorkingCopy(WorkingCopyOwner, IProgressMonitor)}
  74  *      creates a new working copy for this element</li>
  75  * <li>Subsequent calls increment an internal counter.</li>
  76  * <li>A call to {@link ICompilationUnit#discardWorkingCopy()} decrements the internal counter.</li>
  77  * <li>When this counter is 0, the working copy is discarded.
  78  * </ul>
  79  * So users of this method must discard exactly once the working copy.
  80  * <p>
  81  * Note that the working copy owner will be used for the life time of the shared working copy, that is if the
  82  * working copy is closed then reopened, this owner will be used.
  83  * The buffer will be automatically initialized with the original's Java type root content upon creation.
  84  * <p>
  85  * When the shared working copy instance is created, an ADDED IJavaElementDelta is reported on this
  86  * working copy.
  87  * </p><p>
  88  * A working copy can be created on a not-yet existing compilation unit.
  89  * In particular, such a working copy can then be committed in order to create
  90  * the corresponding compilation unit.
  91  * </p><p>
  92  * Note that possible problems of this working copy are reported using this method only
  93  * if the given working copy owner returns a problem requestor for this working copy
  94  * (see {@link WorkingCopyOwner#getProblemRequestor(ICompilationUnit)}).
  95  * </p>
  96  *
  97  * @param owner the working copy owner that creates a buffer that is used to get the content
  98  *                              of the working copy
  99  * @param monitor a progress monitor used to report progress while opening this compilation unit
 100  *                 or <code>null</code> if no progress should be reported
 101  * @throws JavaModelException if the contents of this element can
 102  *      not be determined.
 103  * @return a new working copy of this Java type root using the given owner to create
 104  *              the buffer, or this Java type root if it is already a working copy
 105  */
 106 ICompilationUnit getWorkingCopy(WorkingCopyOwner owner, IProgressMonitor monitor) throws JavaModelException;
 107
 108 }