ShadowChain (PMD Java 7.0.0-rc2 API)

Type Parameters:

S - Type of symbols this chain tracks

I - Type of the "scope tag", some data used to help identify the reason why a declaration is in scope. This can be retrieved with ShadowChainIterator.getScopeTag().
```
public interface ShadowChain<S,I>
```
A shadow chain is a linked list of NameResolvers, which handles shadowing relations between declarations. Chains track the scope of declarations of a single kind, corresponding to a namespace (eg types or methods).
Basic usage:
```
   List<JVariableSymbol> foo = chain.resolve("foo");
   if (foo.isEmpty()) {
      // failed
   } else if (foo.size() > 1) {
      // ambiguity between all the members of the list
   } else {
      JVariableSymbol varFoo = foo.get(0); // it's this symbol
   }
 
```
More advanced functionality is provided by ShadowChainIterator. ShadowChain instances can be viewed as both a node in the chain or as the entire chain. The former interpretation is rendered by the lower-level API of ShadowChainNode.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method	Description
`ShadowChainNode<S,I>`	`asNode()`	Returns the API of this instance that views the chain as individual nodes.
`default ShadowChainIterator<S,I>`	`iterateResults(String name)`	Returns an iterator that iterates over sets of shadowed declarations with the given name.
`@NonNull List<S>`	`resolve(String name)`	Returns the list of symbols accessible by simple name in the scope of this group.
`S`	`resolveFirst(String name)`	Returns the first symbol that would be yielded by `resolve(String)`, if it would return a non-empty list.

- Method Detail
  - resolve
```
@NonNull List<S> resolve(String name)
```
    Returns the list of symbols accessible by simple name in the scope of this group. No name in this list shadows another. An empty list means no such symbol exist. A list with more than one element may mean there is ambiguity. For methods, ambiguity may be resolved through overload resolution, for other kinds of symbols, it causes an error.
    The ordering in the list is defined to be innermost first.
    
    Parameters:
    
    name - Simple name of the symbols to find
    
    Returns:
    
    A list of symbols
  - resolveFirst
```
S resolveFirst(String name)
```
    Returns the first symbol that would be yielded by resolve(String), if it would return a non-empty list. Otherwise returns null.
    
    Parameters:
    
    name - Simple name of the symbol to find
    
    Returns:
    
    An optional symbol
  - iterateResults
```
default ShadowChainIterator<S,I> iterateResults(String name)
```
    Returns an iterator that iterates over sets of shadowed declarations with the given name.
    
    Parameters:
    
    name - Simple name of the symbols to find
  - asNode
```
ShadowChainNode<S,I> asNode()
```
    Returns the API of this instance that views the chain as individual nodes.