09ef815bc380e6c22e52cac66b1e8380365a9f96
[phpeclipse.git] / net.sourceforge.phpeclipse / src / net / sourceforge / phpdt / core / ISourceReference.java
1 /*******************************************************************************
2  * Copyright (c) 2000, 2001, 2002 International Business Machines Corp. and others.
3  * All rights reserved. This program and the accompanying materials 
4  * are made available under the terms of the Common Public License v0.5 
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/cpl-v05.html
7  * 
8  * Contributors:
9  *     IBM Corporation - initial API and implementation
10  ******************************************************************************/
11 package net.sourceforge.phpdt.core;
12
13 /**
14  * Common protocol for Java elements that have associated source code.
15  * This set consists of <code>IClassFile</code>, <code>ICompilationUnit</code>,
16  * <code>IPackageDeclaration</code>, <code>IImportDeclaration</code>,
17  * <code>IImportContainer</code>, <code>IType</code>, <code>IField</code>,
18  * <code>IMethod</code>, and <code>IInitializer</code>.
19  * </ul>
20  * <p>
21  * Note: For <code>IClassFile</code>, <code>IType</code> and other members
22  * derived from a binary type, the implementation returns source iff the
23  * element has attached source code.
24  * </p>
25  * <p>
26  * Source reference elements may be working copies if they were created from
27  * a compilation unit that is a working copy.
28  * </p>
29  * <p>
30  * This interface is not intended to be implemented by clients.
31  * </p>
32  *
33  * @see IPackageFragmentRoot#attachSource
34  */
35 public interface ISourceReference {
36 /**
37  * Returns whether this element exists in the model.
38  *
39  * @return <code>true</code> if this element exists in the Java model
40  * @since 2.0
41  */
42 boolean exists();
43         
44 /**
45  * Returns the source code associated with this element.
46  * This extracts the substring from the source buffer containing this source
47  * element. This corresponds to the source range that would be returned by
48  * <code>getSourceRange</code>.
49  * <p>
50  * For class files, this returns the source of the entire compilation unit 
51  * associated with the class file (if there is one).
52  * </p>
53  *
54  * @return the source code, or <code>null</code> if this element has no 
55  *   associated source code
56  * @exception JavaModelException if this element does not exist or if an
57  *      exception occurs while accessing its corresponding resource
58  */
59 String getSource() throws JavaModelException;
60 /**
61  * Returns the source range associated with this element.
62  * <p>
63  * For class files, this returns the range of the entire compilation unit 
64  * associated with the class file (if there is one).
65  * </p>
66  *
67  * @return the source range, or <code>null</code> if this element has no 
68  *   associated source code
69  * @exception JavaModelException if this element does not exist or if an
70  *      exception occurs while accessing its corresponding resource
71  */
72 ISourceRange getSourceRange() throws JavaModelException;
73 }