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 */
becomeWorkingCopy(IProblemRequestor problemRequestor, WorkingCopyOwner owner, IProgressMonitor monitor)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 */
getBytes()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 */
getType()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 */
getWorkingCopy(IProgressMonitor monitor, IBufferFactory factory)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 */
isClass()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 */
isInterface()152 boolean isInterface() throws JavaModelException;
153 }
154