com.sun.tools.javac.model
Class JavacElements

java.lang.Object
  com.sun.tools.javac.model.JavacElements

All Implemented Interfaces:

Elements

public class JavacElements
extends java.lang.Object
implements Elements

Utility methods for operating on program elements.

This is NOT part of any API supported by Sun Microsystems. If you write code that depends on this, you do so at your own risk. This code and its internal interfaces are subject to change or deletion without notice.

Field Summary

private Enter	enter
private JavaCompiler	javaCompiler
private static Context.Key<JavacElements>	KEY
private Names	names
private Symtab	syms
private Types	types

Constructor Summary

JavacElements(Context context)
Public for use only by JavacProcessingEnvironment

Method Summary

private void	addMembers(Scope scope, Type type)
private static <T> T	cast(java.lang.Class<T> clazz, java.lang.Object o) Returns an object cast to the specified type.
private static boolean	containsAnnoOfType(List<Attribute.Compound> annos, Type type) Tests whether a list of annotations contains an annotation of a given type.
List<Attribute.Compound>	getAllAnnotationMirrors(Element e) Returns all annotations of an element, whether inherited or directly present.
FilteredMemberList	getAllMembers(TypeElement element) Returns all members of a type element, whether inherited or declared directly.
static <A extends java.lang.annotation.Annotation> A	getAnnotation(Symbol.ClassSymbol annotated, java.lang.Class<A> annoType) An internal-use utility that creates a reified annotation.
static <A extends java.lang.annotation.Annotation> A	getAnnotation(Symbol annotated, java.lang.Class<A> annoType) An internal-use utility that creates a reified annotation.
Name	getBinaryName(TypeElement type) Returns the binary name of a type element.
java.lang.String	getConstantExpression(java.lang.Object value) Returns the text of a constant expression representing a primitive value or a string.
java.lang.String	getDocComment(Element e) Returns the text of the documentation ("Javadoc") comment of an element.
java.util.Map<Symbol.MethodSymbol,Attribute>	getElementValuesWithDefaults(AnnotationMirror a) Returns the values of an annotation's elements, including defaults.
private Env<AttrContext>	getEnterEnv(Symbol sym) Returns a symbol's enter environment, or null if it has none.
Name	getName(java.lang.CharSequence cs) Return a name with the same sequence of characters as the argument.
Symbol.PackageSymbol	getPackageElement(java.lang.CharSequence name) Returns a package given its fully qualified name.
PackageElement	getPackageOf(Element e) Returns the package of an element.
JavacSourcePosition	getSourcePosition(Element e)
JavacSourcePosition	getSourcePosition(Element e, AnnotationMirror a)
JavacSourcePosition	getSourcePosition(Element e, AnnotationMirror a, AnnotationValue v)
JCTree	getTree(Element e) Returns the tree node corresponding to this element, or null if none can be found.
private Pair<JCTree,JCTree.JCCompilationUnit>	getTreeAndTopLevel(Element e) Returns the tree node and compilation unit corresponding to this element, or null if they can't be found.
Pair<JCTree,JCTree.JCCompilationUnit>	getTreeAndTopLevel(Element e, AnnotationMirror a, AnnotationValue v) Returns the best approximation for the tree node and compilation unit corresponding to the given element, annotation and value.
Symbol.ClassSymbol	getTypeElement(java.lang.CharSequence name) Returns a type element given its canonical name.
boolean	hides(Element hiderEl, Element hideeEl) Tests whether one type, method, or field hides another.
static JavacElements	instance(Context context)
boolean	isDeprecated(Element e) Returns true if the element is deprecated, false otherwise.
private boolean	isInherited(Type annotype) Tests whether an annotation type is @Inherited.
private JCTree	matchAnnoToTree(AnnotationMirror findme, Element e, JCTree tree) Returns the tree for an annotation given the annotated element and the element's own tree.
private JCTree	matchAnnoToTree(Attribute.Compound findme, Attribute attr, JCTree tree) Returns the tree for an annotation given an Attribute to search (recursively) and its corresponding tree.
private JCTree	matchAnnoToTree(Attribute.Compound findme, List<Attribute.Compound> annos, List<JCTree.JCAnnotation> trees) Returns the tree for an annotation given a list of annotations in which to search (recursively) and their corresponding trees.
private <S extends Symbol> S	nameToSymbol(java.lang.String nameStr, java.lang.Class<S> clazz) Returns a symbol given the type's or packages's canonical name, or null if the name isn't found.
boolean	overrides(ExecutableElement riderEl, ExecutableElement rideeEl, TypeElement typeEl) Tests whether one method, as a member of a given type, overrides another method.
void	printElements(java.io.Writer w, Element... elements) Print a representation of the elements to the given writer in the specified order.
private JCTree.JCExpression	scanForAssign(Symbol.MethodSymbol sym, JCTree tree) Scans for a JCAssign node with a LHS matching a given symbol, and returns its RHS.
void	setContext(Context context) Use a new context.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

javaCompiler

private JavaCompiler javaCompiler

syms

private Symtab syms

names

private Names names

types

private Types types

enter

private Enter enter

KEY

private static final Context.Key<JavacElements> KEY

Constructor Detail

JavacElements

public JavacElements(Context context)

Public for use only by JavacProcessingEnvironment

Method Detail

instance

public static JavacElements instance(Context context)

setContext

public void setContext(Context context)

Use a new context. May be called from outside to update internal state for a new annotation-processing round. This instance is *not* then registered with the new context.

getAnnotation

public static <A extends java.lang.annotation.Annotation> A getAnnotation(Symbol annotated,
                                                                          java.lang.Class<A> annoType)

An internal-use utility that creates a reified annotation.

getAnnotation

public static <A extends java.lang.annotation.Annotation> A getAnnotation(Symbol.ClassSymbol annotated,
                                                                          java.lang.Class<A> annoType)

An internal-use utility that creates a reified annotation. This overloaded version take annotation inheritance into account.

getPackageElement

public Symbol.PackageSymbol getPackageElement(java.lang.CharSequence name)

Description copied from interface: Elements

Returns a package given its fully qualified name.

Specified by:

getPackageElement in interface Elements

Parameters:

name - fully qualified package name, or "" for an unnamed package

Returns:

the named package, or null if it cannot be found

getTypeElement

public Symbol.ClassSymbol getTypeElement(java.lang.CharSequence name)

Description copied from interface: Elements

Returns a type element given its canonical name.

Specified by:

getTypeElement in interface Elements

Parameters:

name - the canonical name

Returns:

the named type element, or null if it cannot be found

nameToSymbol

private <S extends Symbol> S nameToSymbol(java.lang.String nameStr,
                                          java.lang.Class<S> clazz)

Returns a symbol given the type's or packages's canonical name, or null if the name isn't found.

getSourcePosition

public JavacSourcePosition getSourcePosition(Element e)

getSourcePosition

public JavacSourcePosition getSourcePosition(Element e,
                                             AnnotationMirror a)

getSourcePosition

public JavacSourcePosition getSourcePosition(Element e,
                                             AnnotationMirror a,
                                             AnnotationValue v)

matchAnnoToTree

private JCTree matchAnnoToTree(AnnotationMirror findme,
                               Element e,
                               JCTree tree)

Returns the tree for an annotation given the annotated element and the element's own tree. Returns null if the tree cannot be found.

matchAnnoToTree

private JCTree matchAnnoToTree(Attribute.Compound findme,
                               List<Attribute.Compound> annos,
                               List<JCTree.JCAnnotation> trees)

Returns the tree for an annotation given a list of annotations in which to search (recursively) and their corresponding trees. Returns null if the tree cannot be found.

matchAnnoToTree

private JCTree matchAnnoToTree(Attribute.Compound findme,
                               Attribute attr,
                               JCTree tree)

Returns the tree for an annotation given an Attribute to search (recursively) and its corresponding tree. Returns null if the tree cannot be found.

scanForAssign

private JCTree.JCExpression scanForAssign(Symbol.MethodSymbol sym,
                                          JCTree tree)

Scans for a JCAssign node with a LHS matching a given symbol, and returns its RHS. Does not scan nested JCAnnotations.

getTree

public JCTree getTree(Element e)

Returns the tree node corresponding to this element, or null if none can be found.

getDocComment

public java.lang.String getDocComment(Element e)

Description copied from interface: Elements

Returns the text of the documentation ("Javadoc") comment of an element.

Specified by:

getDocComment in interface Elements

Parameters:

e - the element being examined

Returns:

the documentation comment of the element, or null if there is none

getPackageOf

public PackageElement getPackageOf(Element e)

Description copied from interface: Elements

Returns the package of an element. The package of a package is itself.

Specified by:

getPackageOf in interface Elements

Parameters:

e - the element being examined

Returns:

the package of an element

isDeprecated

public boolean isDeprecated(Element e)

Description copied from interface: Elements

Returns true if the element is deprecated, false otherwise.

Specified by:

isDeprecated in interface Elements

Parameters:

e - the element being examined

Returns:

true if the element is deprecated, false otherwise

getBinaryName

public Name getBinaryName(TypeElement type)

Description copied from interface: Elements

Returns the binary name of a type element.

Specified by:

getBinaryName in interface Elements

Parameters:

type - the type element being examined

Returns:

the binary name

See Also:

TypeElement.getQualifiedName()

getElementValuesWithDefaults

public java.util.Map<Symbol.MethodSymbol,Attribute> getElementValuesWithDefaults(AnnotationMirror a)

Description copied from interface: Elements

Returns the values of an annotation's elements, including defaults.

Specified by:

getElementValuesWithDefaults in interface Elements

Parameters:

a - annotation to examine

Returns:

the values of the annotation's elements, including defaults

See Also:

AnnotationMirror.getElementValues()

getAllMembers

public FilteredMemberList getAllMembers(TypeElement element)

Returns all members of a type element, whether inherited or declared directly. For a class the result also includes its constructors, but not local or anonymous classes.

Note that elements of certain kinds can be isolated using methods in ElementFilter.

Specified by:

getAllMembers in interface Elements

Parameters:

element - the type being examined

Returns:

all members of the type

See Also:

Element.getEnclosedElements()

addMembers

private void addMembers(Scope scope,
                        Type type)

getAllAnnotationMirrors

public List<Attribute.Compound> getAllAnnotationMirrors(Element e)

Returns all annotations of an element, whether inherited or directly present.

Specified by:

getAllAnnotationMirrors in interface Elements

Parameters:

e - the element being examined

Returns:

all annotations of the element

See Also:

Element.getAnnotationMirrors()

isInherited

private boolean isInherited(Type annotype)

Tests whether an annotation type is @Inherited.

containsAnnoOfType

private static boolean containsAnnoOfType(List<Attribute.Compound> annos,
                                          Type type)

Tests whether a list of annotations contains an annotation of a given type.

hides

public boolean hides(Element hiderEl,
                     Element hideeEl)

Description copied from interface: Elements

Tests whether one type, method, or field hides another.

Specified by:

hides in interface Elements

Parameters:

hiderEl - the first element

hideeEl - the second element

Returns:

true if and only if the first element hides the second

overrides

public boolean overrides(ExecutableElement riderEl,
                         ExecutableElement rideeEl,
                         TypeElement typeEl)

Description copied from interface: Elements

Tests whether one method, as a member of a given type, overrides another method. When a non-abstract method overrides an abstract one, the former is also said to implement the latter.

In the simplest and most typical usage, the value of the type parameter will simply be the class or interface directly enclosing overrider (the possibly-overriding method). For example, suppose m1 represents the method String.hashCode and m2 represents Object.hashCode. We can then ask whether m1 overrides m2 within the class String (it does):

assert elements.overrides(m1, m2, elements.getTypeElement("java.lang.String"));

A more interesting case can be illustrated by the following example in which a method in type A does not override a like-named method in type B:

class A { public void m() {} }
interface B { void m(); }
...
m1 = ...; // A.m
m2 = ...; // B.m
assert ! elements.overrides(m1, m2, elements.getTypeElement("A"));

When viewed as a member of a third type C, however, the method in A does override the one in B:

class C extends A implements B {}
...
assert elements.overrides(m1, m2, elements.getTypeElement("C"));

Specified by:

overrides in interface Elements

Parameters:

riderEl - the first method, possible overrider

rideeEl - the second method, possibly being overridden

typeEl - the type of which the first method is a member

Returns:

true if and only if the first method overrides the second

getConstantExpression

public java.lang.String getConstantExpression(java.lang.Object value)

Description copied from interface: Elements

Returns the text of a constant expression representing a primitive value or a string. The text returned is in a form suitable for representing the value in source code.

Specified by:

getConstantExpression in interface Elements

Parameters:

value - a primitive value or string

Returns:

the text of a constant expression

See Also:

VariableElement.getConstantValue()

printElements

public void printElements(java.io.Writer w,
                          Element... elements)

Print a representation of the elements to the given writer in the specified order. The main purpose of this method is for diagnostics. The exact format of the output is not specified and is subject to change.

Specified by:

printElements in interface Elements

Parameters:

w - the writer to print the output to

elements - the elements to print

getName

public Name getName(java.lang.CharSequence cs)

Description copied from interface: Elements

Return a name with the same sequence of characters as the argument.

Specified by:

getName in interface Elements

Parameters:

cs - the character sequence to return as a name

getTreeAndTopLevel

private Pair<JCTree,JCTree.JCCompilationUnit> getTreeAndTopLevel(Element e)

Returns the tree node and compilation unit corresponding to this element, or null if they can't be found.

getTreeAndTopLevel

public Pair<JCTree,JCTree.JCCompilationUnit> getTreeAndTopLevel(Element e,
                                                                AnnotationMirror a,
                                                                AnnotationValue v)

Returns the best approximation for the tree node and compilation unit corresponding to the given element, annotation and value. If the element is null, null is returned. If the annotation is null or cannot be found, the tree node and compilation unit for the element is returned. If the annotation value is null or cannot be found, the tree node and compilation unit for the annotation is returned.

getEnterEnv

private Env<AttrContext> getEnterEnv(Symbol sym)

Returns a symbol's enter environment, or null if it has none.

cast

private static <T> T cast(java.lang.Class<T> clazz,
                          java.lang.Object o)

Returns an object cast to the specified type.

Throws:

java.lang.NullPointerException - if the object is null

java.lang.IllegalArgumentException - if the object is of the wrong type