1 /**
2 * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
3 */
4 package net.sourceforge.pmd.lang.symboltable;
5
6 import java.util.List;
7 import java.util.Map;
8
9 /**
10 * A scope is a region within variables and other declarations are visible.
11 * Scopes can be nested and form a tree. This is expressed through "parent scopes".
12 * Each scope manages its own declarations.
13 *
14 * @see AbstractScope AbstractScope as a base class
15 * @see <a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-6.html#jls-6.3">Java Language Specification, 6.3: Scope of a Declaration</a>
16 */
17 public interface Scope {
18 /**
19 * Retrieves this scope's parent
20 */
21 Scope getParent();
22
23 /**
24 * Points this scope to its parent
25 */
26 void setParent(Scope parent);
27
28 /**
29 * Helper method that goes up the parent scopes to find a scope
30 * of the specified type
31 * @param clazz the type of the Scope to search for
32 * @return the found scope of the specified type or <code>null</code> if no
33 * such scope was found.
34 */
35 <T extends Scope> T getEnclosingScope(Class<T> clazz);
36
37 /**
38 * Gets all the declaration with the occurrences in this scope.
39 * @return map of declarations with occurrences.
40 */
41 Map<NameDeclaration, List<NameOccurrence>> getDeclarations();
42
43 /**
44 * Helper method to get only a specific type of name declarations.
45 * The return map elemens have already been casted to the correct type.
46 * This method usually returns a subset of {@link #getDeclarations()}.
47 * @param clazz the type of name declarations to use
48 * @return map of declarations with occurrences.
49 */
50 <T extends NameDeclaration> Map<T, List<NameOccurrence>> getDeclarations(Class<T> clazz);
51
52 /**
53 * Tests whether or not a {@link NameOccurrence} is directly contained in the scope.
54 * This means, whether the given {@link NameOccurrence} references a declaration, that has been
55 * declared within this scope.
56 * Note that this search is just for this scope - it doesn't go diving into any
57 * parent scopes.
58 */
59 boolean contains(NameOccurrence occ);
60
61 /**
62 * Adds a new declaration to this scope. Only after the declaration has been added,
63 * {@link #contains(NameOccurrence)} and {@link #addNameOccurrence(NameOccurrence)} can
64 * be used correctly.
65 * @param declaration the declaration to add
66 */
67 void addDeclaration(NameDeclaration declaration);
68
69 /**
70 * Adds a {@link NameOccurrence} to this scope - only call this after getting
71 * a true back from {@link #contains(NameOccurrence)}.
72 * @return the {@link NameDeclaration} that is references by the given {@link NameOccurrence},
73 * if the {@link NameOccurrence} could be added. Otherwise <code>null</code> is returned.
74 */
75 NameDeclaration addNameOccurrence(NameOccurrence occurrence);
76 }