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