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 }