org.netbeans.api.java.source

Class SourceUtils

java.lang.Object

org.netbeans.api.java.source.SourceUtils

public class SourceUtils
extends Object

Method Summary

Modifier and Type	Method and Description
static boolean	checkTypesAssignable(CompilationInfo info, TypeMirror from, TypeMirror to)
static Set<TreePath>	computeDuplicates(CompilationInfo info, TreePath searchingFor, TreePath scope, AtomicBoolean cancel) Find duplicates for provided expression
static List<? extends Completion>	getAttributeValueCompletions(CompilationInfo info, Element element, AnnotationMirror annotation, ExecutableElement member, String userText) Returns a list of completions for an annotation attribute value suggested by annotation processors.
static TypeMirror	getBound(WildcardType wildcardType)
static Set<URL>	getDependentRoots(URL root) Returns the dependent source path roots for given source root.
static Set<URL>	getDependentRoots(URL root, boolean filterNonOpenedProjects) Returns the dependent source path roots for given source root.
static Object	getDiagnosticParam(Diagnostic<?> d, int index) Extracts diagnostic params from a diagnostic.
static TypeElement	getEnclosingTypeElement(Element element) Deprecated. use ElementUtilities.enclosingTypeElement(javax.lang.model.element.Element)
static FileObject	getFile(Element element, ClasspathInfo cpInfo) Deprecated. use getFile(ElementHandle, ClasspathInfo)
static FileObject	getFile(ElementHandle<? extends Element> handle, ClasspathInfo cpInfo) Returns a FileObject of the source file in which the handle is declared.
static Collection<? extends Element>	getForwardReferences(TreePath path, int pos, SourcePositions sourcePositions, Trees trees) Returns all elements of the given scope that are declared after given position in a source.
static Collection<? extends URL>	getJavadoc(Element element) Finds URLs of a javadoc page for given element when available.
static URL	getJavadoc(Element element, ClasspathInfo cpInfo) Deprecated. use getJavadoc(javax.lang.model.element.Element) or getPreferredJavadoc(javax.lang.model.element.Element)
static TokenSequence<org.netbeans.api.java.lexer.JavaTokenId>	getJavaTokenSequence(TokenHierarchy hierarchy, int offset)
static String[]	getJVMSignature(ElementHandle<?> handle) Returns an array containing the JVM signature of the ElementHandle.
static Collection<ElementHandle<TypeElement>>	getMainClasses(FileObject fo) Returns classes declared in the given source file which have the main method.
static Collection<ElementHandle<TypeElement>>	getMainClasses(FileObject[] sourceRoots) Returns classes declared under the given source roots which have the main method.
static String	getModuleName(URL rootUrl) Returns the name of the module.
static String	getModuleName(URL rootUrl, boolean canUseSources) Returns the name of the module.
static Set<String>	getModuleNames(CompilationInfo info, Set<? extends ClassIndex.SearchScopeType> scope) Returns names of all modules within given scope.
static TypeElement	getOutermostEnclosingTypeElement(Element element)
static URL	getPreferredJavadoc(Element element) Returns preferred Javadoc URL.
static boolean	isMainClass(String qualifiedName, ClasspathInfo cpInfo) Returns true when the class contains main method.
static boolean	isMainClass(String qualifiedName, ClasspathInfo cpInfo, boolean optimistic) Returns true when the class contains main method.
static boolean	isMainMethod(ExecutableElement method) Returns true if the method is a main method
static boolean	isScanInProgress() Tests whether the initial scan is in progress.
static String	parseModuleName(FileObject moduleInfo) Returns a module name parsed from the given module-info.java.
static TypeMirror	resolveCapturedType(CompilationInfo info, TypeMirror tm) Resolves all captured type variables to their respective wildcards in the given type.
static WildcardType	resolveCapturedType(TypeMirror type)
static String	resolveImport(CompilationInfo info, TreePath context, String fqn) Resolve full qualified name in the given context.
static void	waitScanFinished() Deprecated. use JavaSource.runWhenScanFinished(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, boolean)

Methods inherited from class java.lang.Object

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

Method Detail

getJavaTokenSequence

public static TokenSequence<org.netbeans.api.java.lexer.JavaTokenId> getJavaTokenSequence(TokenHierarchy hierarchy,
                                                                                          int offset)

Since:

0.21

computeDuplicates

public static Set<TreePath> computeDuplicates(CompilationInfo info,
                                              TreePath searchingFor,
                                              TreePath scope,
                                              AtomicBoolean cancel)

Find duplicates for provided expression

Parameters:

info - CompilationInfo

searchingFor - expression which is being searched

scope - scope for search

cancel - option to cancel find duplicates

Returns:

set of TreePaths representing duplicates

Since:

0.85

checkTypesAssignable

public static boolean checkTypesAssignable(CompilationInfo info,
                                           TypeMirror from,
                                           TypeMirror to)

getBound

public static TypeMirror getBound(WildcardType wildcardType)

getAttributeValueCompletions

public static List<? extends Completion> getAttributeValueCompletions(CompilationInfo info,
                                                                      Element element,
                                                                      AnnotationMirror annotation,
                                                                      ExecutableElement member,
                                                                      String userText)

Returns a list of completions for an annotation attribute value suggested by annotation processors.

Parameters:

info - the CompilationInfo used to resolve annotation processors

element - the element being annotated

annotation - the (perhaps partial) annotation being applied to the element

member - the annotation member to return possible completions for

userText - source code text to be completed

Returns:

suggested completions to the annotation member

Since:

0.57

getEnclosingTypeElement

@Deprecated
public static TypeElement getEnclosingTypeElement(Element element)
                                                       throws IllegalArgumentException

Deprecated. use ElementUtilities.enclosingTypeElement(javax.lang.model.element.Element)

Returns the type element within which this member or constructor is declared. Does not accept packages If this is the declaration of a top-level type (a non-nested class or interface), returns null.

Returns:

the type declaration within which this member or constructor is declared, or null if there is none

Throws:

IllegalArgumentException - if the provided element is a package element

getOutermostEnclosingTypeElement

public static TypeElement getOutermostEnclosingTypeElement(Element element)

getJVMSignature

@NonNull
public static String[] getJVMSignature(@NonNull
                                                ElementHandle<?> handle)

Returns an array containing the JVM signature of the ElementHandle.

Parameters:

handle - to obtain the JVM signature for.

Returns:

an array containing the JVM signature. The signature depends on the ElementHandle's ElementKind. For class or package it returns a single element array containing the class (package) binary name (JLS section 13.1). For field (method) it returns three element array containing owner class binary name (JLS section 13.1) in the first element, field (method) name in the second element and JVM type (JVM method formal parameters (JVMS section 2.10.1)) in the third element.

Since:

0.84

resolveImport

public static String resolveImport(CompilationInfo info,
                                   TreePath context,
                                   String fqn)
                            throws NullPointerException,
                                   IOException

Resolve full qualified name in the given context. Adds import statement as necessary. Returns name that resolved to a given FQN in given context (either simple name or full qualified name). Handles import conflicts.
Note: if the info passed to this method is not an instance of WorkingCopy, missing import statement is added from a separate modification task executed asynchronously.
Note: after calling this method, it is not permitted to rewrite copy.getCompilationUnit().

Parameters:

info - CompilationInfo over which the method should work

context - in which the fully qualified should be resolved

fqn - the fully qualified name to resolve

Returns:

either a simple name or a FQN that will resolve to given fqn in given context

Throws:

NullPointerException

IOException

getFile

public static FileObject getFile(Element element,
                                 ClasspathInfo cpInfo)

Deprecated. use getFile(ElementHandle, ClasspathInfo)

Returns a FileObject in which the Element is defined.

Parameters:

element - for which the FileObject should be located

cpInfo - the classpaths context

Returns:

the defining FileObject or null if it cannot be found

getFile

public static FileObject getFile(ElementHandle<? extends Element> handle,
                                 ClasspathInfo cpInfo)

Returns a FileObject of the source file in which the handle is declared.

Parameters:

handle - to find the FileObject for

cpInfo - classpaths for resolving handle

Returns:

FileObject or null when the source file cannot be found

getJavadoc

@Deprecated
public static URL getJavadoc(Element element,
                                         ClasspathInfo cpInfo)

Deprecated. use getJavadoc(javax.lang.model.element.Element) or getPreferredJavadoc(javax.lang.model.element.Element)

Finds URL of a javadoc page for given element when available. This method uses JavadocForBinaryQuery to find the javadoc page for the give element. For PackageElement it returns the package-summary.html for given package.

Parameters:

element - to find the Javadoc for

cpInfo - classpaths used to resolve (currently unused)

Returns:

the URL of the javadoc page or null when the javadoc is not available.

getPreferredJavadoc

@CheckForNull
public static URL getPreferredJavadoc(@NonNull
                                                    Element element)

Returns preferred Javadoc URL. Threading: The method parses the javadoc to find out the used doclet, so it should not be called from EDT.

Parameters:

element - to find the Javadoc for

Returns:

the URL of the javadoc page or null when the javadoc is not available.

Since:

0.134

getJavadoc

@NonNull
public static Collection<? extends URL> getJavadoc(@NonNull
                                                            Element element)

Finds URLs of a javadoc page for given element when available. This method uses JavadocForBinaryQuery to find the javadoc page for the give element. For PackageElement it returns the package-summary.html for given package. Due to the https://bugs.openjdk.java.net/browse/JDK-8025633 there are more possible URLs for ExecutableElements, this method returns all of them.

Parameters:

element - to find the Javadoc for

Returns:

the URLs of the javadoc page or an empty collection when the javadoc is not available.

Since:

0.133

isScanInProgress

public static boolean isScanInProgress()

Tests whether the initial scan is in progress.

waitScanFinished

public static void waitScanFinished()
                             throws InterruptedException

Deprecated. use JavaSource.runWhenScanFinished(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, boolean)

Waits for the end of the initial scan, this helper method is designed for tests which require to wait for end of initial scan.

Throws:

InterruptedException - is thrown when the waiting thread is interrupted.

getDependentRoots

@NonNull
public static Set<URL> getDependentRoots(@NonNull
                                                  URL root)

Returns the dependent source path roots for given source root. It returns all the open project source roots which have either direct or transitive dependency on the given source root.

Parameters:

root - to find the dependent roots for

Returns:

Set of URLs containing at least the incoming root, never returns null.

Since:

0.10

getDependentRoots

@NonNull
public static Set<URL> getDependentRoots(@NonNull
                                                  URL root,
                                                  boolean filterNonOpenedProjects)

Returns the dependent source path roots for given source root. It returns all the source roots which have either direct or transitive dependency on the given source root.

Parameters:

root - to find the dependent roots for

filterNonOpenedProjects - true if the results should only contain roots for opened projects

Returns:

Set of URLs containing at least the incoming root, never returns null.

Since:

0.110

getMainClasses

public static Collection<ElementHandle<TypeElement>> getMainClasses(@NonNull
                                                                    FileObject fo)

Returns classes declared in the given source file which have the main method.

Parameters:

fo - source file

Returns:

the classes containing main method

Throws:

IllegalArgumentException - when file does not exist or is not a java source file.

isMainClass

public static boolean isMainClass(String qualifiedName,
                                  ClasspathInfo cpInfo)

Returns true when the class contains main method.

Parameters:

qualifiedName - the fully qualified name of class

cpInfo - the classpath used to resolve the class

Returns:

true when the class contains a main method

isMainClass

public static boolean isMainClass(String qualifiedName,
                                  ClasspathInfo cpInfo,
                                  boolean optimistic)

Returns true when the class contains main method.

Parameters:

qualifiedName - the fully qualified name of class

cpInfo - the classpath used to resolve the class

optimistic - when true does only index check without parsing the file. The optimistic check is faster but it works only for source file not for binaries for which index does not exist. It also does not handle inheritance of the main method.

Returns:

true when the class contains a main method

Since:

0.71

isMainMethod

public static boolean isMainMethod(ExecutableElement method)

Returns true if the method is a main method

Parameters:

method - to be checked

Returns:

true when the method is a main method

getMainClasses

public static Collection<ElementHandle<TypeElement>> getMainClasses(FileObject[] sourceRoots)

Returns classes declared under the given source roots which have the main method.

Parameters:

sourceRoots - the source roots

Returns:

the classes containing the main methods Currently this method is not optimized and may be slow

resolveCapturedType

public static TypeMirror resolveCapturedType(CompilationInfo info,
                                             TypeMirror tm)

Resolves all captured type variables to their respective wildcards in the given type.

Parameters:

info - CompilationInfo over which the method should work

tm - type to resolve

Returns:

resolved type

Since:

0.136

resolveCapturedType

public static WildcardType resolveCapturedType(TypeMirror type)

Since:

0.24

getForwardReferences

public static Collection<? extends Element> getForwardReferences(TreePath path,
                                                                 int pos,
                                                                 SourcePositions sourcePositions,
                                                                 Trees trees)

Returns all elements of the given scope that are declared after given position in a source.

Parameters:

path - to the given search scope

pos - position in the source

sourcePositions -

trees -

Returns:

collection of forward references

Since:

0.136

getModuleNames

public static Set<String> getModuleNames(CompilationInfo info,
                                         @NonNull
                                         Set<? extends ClassIndex.SearchScopeType> scope)

Returns names of all modules within given scope.

Parameters:

info - the CompilationInfo used to resolve modules

scope - to search in SearchScope

Returns:

set of module names

Since:

2.23

getModuleName

@CheckForNull
public static String getModuleName(@NonNull
                                                 URL rootUrl)

Returns the name of the module.

Parameters:

rootUrl - the binary root

Returns:

the module name or null when no or invalid module

Since:

2.23

getModuleName

@CheckForNull
public static String getModuleName(@NonNull
                                                 URL rootUrl,
                                                 @NonNull
                                                 boolean canUseSources)

Returns the name of the module.

Parameters:

rootUrl - the binary root

canUseSources -

Returns:

the module name or null when no or invalid module

Since:

2.23

parseModuleName

@CheckForNull
public static String parseModuleName(@NonNull
                                                   FileObject moduleInfo)

Returns a module name parsed from the given module-info.java.

Parameters:

moduleInfo - the module-info java file to parse the module name from

Returns:

the module name or null

Since:

2.28

getDiagnosticParam

public static Object getDiagnosticParam(Diagnostic<?> d,
                                        int index)

Extracts diagnostic params from a diagnostic. Gets under hood of Javac Diagnostic objects and extracts parameters which are otherwise just used to produce a message. Keep in mind that the positions and types of parameters may change in each nbjavac update!

Parameters:

d - diagnostic

index - parameter index to extract

Returns:

parameter value, null if index is out of range

Since:

2.20