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   
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  }