org.netbeans.api.java.source

Class ElementHandle<T extends Element>

java.lang.Object

org.netbeans.api.java.source.ElementHandle<T>

public final class ElementHandle<T extends Element>
extends Object

Represents a handle for Element which can be kept and later resolved by another javac. The javac Elements are valid only in a single CompilationTask or a single run of a CancellableTask. A client needing to keep a reference to an Element and use it in another CancellableTask must serialize it into an ElementHandle. Currently not all Elements can be serialized. See create(T) for details.

Typical usage of ElementHandle is as follows:

 final ElementHandle[] elementHandle = new ElementHandle[1];
 javaSource.runUserActionTask(new Task<CompilationController>() {
     public void run(CompilationController compilationController) {
         compilationController.toPhase(Phase.RESOLVED);
         CompilationUnitTree cu = compilationController.getTree();
         List<? extends Tree> types = getTypeDecls(cu);
         Tree tree = getInterestingElementTree(types);
         Element element = compilationController.getElement(tree);
         elementHandle[0] = ElementHandle.create(element);
    }
 }, true);

 otherJavaSource.runUserActionTask(new Task<CompilationController>() {
     public void run(CompilationController compilationController) {
         compilationController.toPhase(Phase.RESOLVED);
         Element element = elementHandle[0].resolve(compilationController);
         // ....
    }
 }, true);
 

Method Summary

Methods

Modifier and Type	Method and Description
static <T extends Element> ElementHandle<T>	create(T element) Factory method for creating ElementHandle.
static ElementHandle<PackageElement>	createPackageElementHandle(String packageName) Creates an ElementHandle representing a PackageElement.
static ElementHandle<TypeElement>	createTypeElementHandle(ElementKind kind, String binaryName) Creates an ElementHandle representing a TypeElement.
boolean	equals(Object other)
static ElementHandle<? extends TypeElement>	from(TypeMirrorHandle<? extends DeclaredType> typeMirrorHandle) Gets ElementHandle from TypeMirrorHandle representing DeclaredType.
String	getBinaryName() Returns a binary name of the TypeElement represented by this ElementHandle.
ElementKind	getKind() Returns the ElementKind of this element handle, it is the kind of the Element from which the handle was created.
String	getQualifiedName() Returns a qualified name of the TypeElement represented by this ElementHandle.
int	hashCode()
T	resolve(CompilationInfo compilationInfo) Resolves an Element from the ElementHandle.
boolean	signatureEquals(ElementHandle<? extends Element> handle) Tests if the handle has the same signature as the parameter.
boolean	signatureEquals(T element) Tests if the handle has this same signature as the parameter.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

resolve

@CheckForNull
public T resolve(@NonNull
                     CompilationInfo compilationInfo)

Resolves an Element from the ElementHandle.

Parameters:

compilationInfo - representing the CompilationTask in which the Element should be resolved.

Returns:

resolved subclass of Element or null if the elment does not exist on the classpath/sourcepath of CompilationTask.

signatureEquals

public boolean signatureEquals(@NonNull
                      ElementHandle<? extends Element> handle)

Tests if the handle has the same signature as the parameter. The handles with the same signatures are resolved into the same element in the same JavaCompiler task, but may be resolved into the different Elements in the different JavaCompiler tasks.

Parameters:

handle - to be checked

Returns:

true if the handles resolve into the same Elements in the same JavaCompiler task.

getBinaryName

@NonNull
public String getBinaryName()
                     throws IllegalStateException

Returns a binary name of the TypeElement represented by this ElementHandle. When the ElementHandle doesn't represent a TypeElement it throws a IllegalStateException

Returns:

the qualified name

Throws:

an - IllegalStateException when this ElementHandle isn't created for the TypeElement.

IllegalStateException

getQualifiedName

@NonNull
public String getQualifiedName()
                        throws IllegalStateException

Returns a qualified name of the TypeElement represented by this ElementHandle. When the ElementHandle doesn't represent a TypeElement it throws a IllegalStateException

Returns:

the qualified name

Throws:

an - IllegalStateException when this ElementHandle isn't creatred for the TypeElement.

IllegalStateException

signatureEquals

public boolean signatureEquals(@NonNull
                      T element)

Tests if the handle has this same signature as the parameter. The handles has the same signatures if it is resolved into the same element in the same JavaCompiler task, but may be resolved into the different Element in the different JavaCompiler task.

Parameters:

element - to be checked

Returns:

true if this handle resolves into the same Element in the same JavaCompiler task.

getKind

@NonNull
public ElementKind getKind()

Returns the ElementKind of this element handle, it is the kind of the Element from which the handle was created.

Returns:

ElementKind

create

@NonNull
public static <T extends Element> ElementHandle<T> create(@NonNull
                                                  T element)
                                               throws IllegalArgumentException

Factory method for creating ElementHandle.

Parameters:

element - for which the ElementHandle should be created. Permitted ElementKinds are: ElementKind.PACKAGE, ElementKind.CLASS, ElementKind.INTERFACE, ElementKind.ENUM, ElementKind.ANNOTATION_TYPE, ElementKind.METHOD, ElementKind.CONSTRUCTOR, ElementKind.INSTANCE_INIT, ElementKind.STATIC_INIT, ElementKind.FIELD, and ElementKind.ENUM_CONSTANT.

Returns:

a new ElementHandle

Throws:

IllegalArgumentException - if the element is of an unsupported ElementKind

createPackageElementHandle

@NonNull
public static ElementHandle<PackageElement> createPackageElementHandle(@NonNull
                                                               String packageName)

Creates an ElementHandle representing a PackageElement.

Parameters:

packageName - the name of the package

Returns:

the created ElementHandle

Since:

0.98

createTypeElementHandle

@NonNull
public static ElementHandle<TypeElement> createTypeElementHandle(@NonNull
                                                         ElementKind kind,
                                                         @NonNull
                                                         String binaryName)
                                                          throws IllegalArgumentException

Creates an ElementHandle representing a TypeElement.

Parameters:

kind - the ElementKind of the TypeElement, allowed values are ElementKind.CLASS, ElementKind.INTERFACE, ElementKind.ENUM and ElementKind.ANNOTATION_TYPE.

binaryName - the class binary name as specified by JLS §13.1

Returns:

the created ElementHandle

Throws:

IllegalArgumentException - if kind is neither class nor interface

Since:

0.98

from

@NonNull
public static ElementHandle<? extends TypeElement> from(@NonNull
                                                TypeMirrorHandle<? extends DeclaredType> typeMirrorHandle)

Gets ElementHandle from TypeMirrorHandle representing DeclaredType.

Parameters:

typeMirrorHandle - from which the ElementHandle should be retrieved. Permitted TypeKind is TypeKind.DECLARED.

Returns:

an ElementHandle

Since:

0.29.0

toString

public String toString()

Overrides:

toString in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object other)

Overrides:

equals in class Object