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

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 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.IBufferFactory;
  14 import net.sourceforge.phpdt.core.ICompilationUnit;
  15 import net.sourceforge.phpdt.core.IJavaElement;
  16 import net.sourceforge.phpdt.core.IProblemRequestor;
  17 import net.sourceforge.phpdt.core.IType;
  18 import net.sourceforge.phpdt.core.JavaModelException;
  19 import net.sourceforge.phpdt.core.WorkingCopyOwner;
  20
  21 import org.eclipse.core.runtime.IProgressMonitor;
  22
  23 /**
  24  * Represents an entire binary type (single <code>.class</code> file).
  25  * A class file has a single child of type <code>IType</code>.
  26  * Class file elements need to be opened before they can be navigated.
  27  * If a class file cannot be parsed, its structure remains unknown. Use
  28  * <code>IJavaElement.isStructureKnown</code> to determine whether this is the
  29  * case.
  30  * <p>
  31  * Note: <code>IClassFile</code> extends <code>ISourceReference</code>.
  32  * Source can be obtained for a class file if and only if source has been attached to this
  33  * class file. The source associated with a class file is the source code of
  34  * the compilation unit it was (nominally) generated from.
  35  * </p>
  36  * <p>
  37  * This interface is not intended to be implemented by clients.
  38  * </p>
  39  *
  40  * @see IPackageFragmentRoot#attachSource(org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath, IProgressMonitor)
  41  */
  42
  43 public interface IClassFile extends ITypeRoot {
  44
  45 /**
  46  * Changes this class file handle into a working copy. A new {@link IBuffer} is
  47  * created using the given owner. Uses the primary owner if <code>null</code> is
  48  * specified.
  49  * <p>
  50  * When switching to working copy mode, problems are reported to the given
  51  * {@link IProblemRequestor}. Note that once in working copy mode, the given
  52  * {@link IProblemRequestor} is ignored. Only the original {@link IProblemRequestor}
  53  * is used to report subsequent problems.
  54  * </p>
  55  * <p>
  56  * Once in working copy mode, changes to this working copy or its children are done in memory.
  57  * Only the new buffer is affected.
  58  * </p>
  59  * <p>
  60  * Using {@link ICompilationUnit#commitWorkingCopy(boolean, IProgressMonitor)} on the working copy
  61  * will throw a <code>JavaModelException</code> as a class file is implicetly read-only.
  62  * </p>
  63  * <p>
  64  * If this class file was already in working copy mode, an internal counter is incremented and no
  65  * other action is taken on this working copy. To bring this working copy back into the original mode
  66  * (where it reflects the underlying resource), {@link ICompilationUnit#discardWorkingCopy} must be call as many
  67  * times as {@link #becomeWorkingCopy(IProblemRequestor, WorkingCopyOwner, IProgressMonitor)}.
  68  * </p>
  69  * <p>
  70  * The primary compilation unit of a class file's working copy does not exist if the class file is not
  71  * in working copy mode (<code>classFileWorkingCopy.getPrimary().exists() == false</code>).
  72  * </p>
  73  * <p>
  74  * The resource of a class file's working copy is <code>null</code> if the class file is in an external jar file.
  75  * </p>
  76  *
  77  * @param problemRequestor a requestor which will get notified of problems detected during
  78  *      reconciling as they are discovered. The requestor can be set to <code>null</code> indicating
  79  *      that the client is not interested in problems.
  80  * @param owner the given {@link WorkingCopyOwner}, or <code>null</code> for the primary owner
  81  * @param monitor a progress monitor used to report progress while opening this compilation unit
  82  *      or <code>null</code> if no progress should be reported
  83  * @return a working copy for this class file
  84  * @throws JavaModelException if this compilation unit could not become a working copy.
  85  * @see ICompilationUnit#discardWorkingCopy()
  86  * @since 3.2
  87  * @deprecated Use {@link ITypeRoot#getWorkingCopy(WorkingCopyOwner, IProgressMonitor)} instead.
  88  *      Note that if this deprecated method is used, problems will be reported to the given problem requestor
  89  *      as well as the problem requestor returned by the working copy owner (if not null).
  90  */
  91 ICompilationUnit becomeWorkingCopy(IProblemRequestor problemRequestor, WorkingCopyOwner owner, IProgressMonitor monitor) throws JavaModelException;
  92 /**
  93  * Returns the bytes contained in this class file.
  94  *
  95  * @return the bytes contained in this class file
  96  *
  97  * @exception JavaModelException if this element does not exist or if an
  98  *      exception occurs while accessing its corresponding resource
  99  * @since 3.3
 100  */
 101 byte[] getBytes() throws JavaModelException;
 102 /**
 103  * Returns the type contained in this class file.
 104  * This is a handle-only method. The type may or may not exist.
 105  *
 106  * @return the type contained in this class file
 107  */
 108 IType getType();
 109 /**
 110  * Returns a working copy on the source associated with this class file using the given
 111  * factory to create the buffer, or <code>null</code> if there is no source associated
 112  * with the class file.
 113  * <p>
 114  * The buffer will be automatically initialized with the source of the class file
 115  * upon creation.
 116  * <p>
 117  * The only valid operations on this working copy are <code>getBuffer()</code> or <code>getOriginalElement</code>.
 118  *
 119  * @param monitor a progress monitor used to report progress while opening this compilation unit
 120  *                 or <code>null</code> if no progress should be reported
 121  * @param factory the factory that creates a buffer that is used to get the content of the working copy
 122  *                 or <code>null</code> if the internal factory should be used
 123  * @return a  a working copy on the source associated with this class file
 124  * @exception JavaModelException if the source of this class file can
 125  *   not be determined. Reasons include:
 126  * <ul>
 127  * <li> This class file does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 128  * </ul>
 129  * @since 2.0
 130  * @deprecated Use {@link ITypeRoot#getWorkingCopy(WorkingCopyOwner, IProgressMonitor)} instead
 131  */
 132 IJavaElement getWorkingCopy(IProgressMonitor monitor, IBufferFactory factory) throws JavaModelException;
 133 /**
 134  * Returns whether this type represents a class. This is not guaranteed to be
 135  * instantaneous, as it may require parsing the underlying file.
 136  *
 137  * @return <code>true</code> if the class file represents a class.
 138  *
 139  * @exception JavaModelException if this element does not exist or if an
 140  *      exception occurs while accessing its corresponding resource
 141  */
 142 boolean isClass() throws JavaModelException;
 143 /**
 144  * Returns whether this type represents an interface. This is not guaranteed to
 145  * be instantaneous, as it may require parsing the underlying file.
 146  *
 147  * @return <code>true</code> if the class file represents an interface.
 148  *
 149  * @exception JavaModelException if this element does not exist or if an
 150  *      exception occurs while accessing its corresponding resource
 151  */
 152 boolean isInterface() throws JavaModelException;
 153 }