org.netbeans.api.java.source
Class ScanUtils

java.lang.Object
  org.netbeans.api.java.source.ScanUtils

public final class ScanUtils
extends Object

Utility methods, which help JavaSource processing tasks to coordinate with the indexing/scanning process. There are two variants of JavaSource.runUserActionTask(org.netbeans.api.java.source.Task, boolean), which support abort and restart of the user task, if the task indicates incomplete data and the scanning is in progress. The restart is done in a hope that, after scanning completes, the missing types or elements will appear.

The user task may use other provided wrapper methods to:

• checkElement(org.netbeans.api.java.source.CompilationInfo, T) to assert element's presence and validity
• signalIncompleteData(org.netbeans.api.java.source.CompilationInfo, org.netbeans.api.java.source.ElementHandle) to request restart if running parallel to scan

Note that even though the user task run when all the parsing/scanning is over, there's no guarantee that data obtained from the parser structures will be complete and valid - the source code may be really broken, dependency could be missing etc.

An example pattern how to use this class is:

 final TreePath tp = ... ; // obtain a tree path
 ScanUtils.waitUserActionTask(new Task<CompilationController>() {
      public void run(CompilationController ctrl) {
 
          // possibly abort and wait for all info to become available
          Element e = ScanUtils.checkElement(tp.resolve(ctrl));
          if (!ctrl.getElementUtilities().isErroneous(e)) {
              // report the error; element is not found or is otherwise unusable
          } else {
              // do the really useful work on Element e
          }
      }
 };
 

Since:

0.95

Method Summary

static <T extends Element> T	checkElement(CompilationInfo info, T e) Checks that the Element is valid, is not erroneous.
static Future<Void>	postUserActionTask(JavaSource src, Task<CompilationController> uat) Runs the user task through JavaSource.runUserActionTask(org.netbeans.api.java.source.Task, boolean), and returns Future completion handle for it.
static Future<Void>	postUserTask(Source src, UserTask task) Runs the user task, and returns Future completion handle for it.
static void	signalIncompleteData(CompilationInfo ci, ElementHandle handle) Aborts the user task and calls it again when parsing finishes, if a typename is not available.
static void	waitUserActionTask(JavaSource src, Task<CompilationController> uat) Runs user action over source 'src' using JavaSource.runUserActionTask(org.netbeans.api.java.source.Task, boolean) and waits for its completion.
static void	waitUserTask(Source src, UserTask task) Runs user action over source 'src' using ParserManager.parse(java.util.Collection, org.netbeans.modules.parsing.api.UserTask) and waits for its completion.

Methods inherited from class java.lang.Object

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

Method Detail

postUserActionTask

public static Future<Void> postUserActionTask(@NonNull
                                              JavaSource src,
                                              @NonNull
                                              Task<CompilationController> uat)

Runs the user task through JavaSource.runUserActionTask(org.netbeans.api.java.source.Task, boolean), and returns Future completion handle for it. The executed Task may indicate that it does not have enough data when scan is in progress, through e.g. checkElement(org.netbeans.api.java.source.CompilationInfo, T). If so, processing of the Task will abort, and will be restarted when the scan finishes.

For more details, see description of postUserTask(org.netbeans.modules.parsing.api.Source, org.netbeans.modules.parsing.api.UserTask).

Parameters:

src - JavaSource to process

uat - action task that will be executed

Returns:

Future that allows to wait for task's completion.

See Also:

postUserTask(org.netbeans.modules.parsing.api.Source, org.netbeans.modules.parsing.api.UserTask), JavaSource.runUserActionTask(org.netbeans.api.java.source.Task, boolean)

postUserTask

public static Future<Void> postUserTask(@NonNull
                                        Source src,
                                        @NonNull
                                        UserTask task)

Runs the user task, and returns Future completion handle for it. The executed Task may indicate that it does not have enough data when scan is in progress, through e.g. checkElement(org.netbeans.api.java.source.CompilationInfo, T). If so, processing of the Task will abort, and will be restarted when the scan finishes.

The task may run asynchronously, pay attention to synchronization of task's output data. The first attempt to run the task MAY execute synchronously. Do not call the method from Swing EDT, if the task typically takes non-trivial time to complete (see JavaSource.runUserActionTask(org.netbeans.api.java.source.Task, boolean) for discussion).

As postUserTask may decide to defer the task execution, postUserTask cannot reliably report exceptions thrown from the parsing infrastructure. The Task itself is responsible for handling exceptions and propagating them to the caller, the post method will just log the exception.

Parameters:

src - Source to process

task - action task that will be executed

Returns:

Future that allows to wait for task's completion.

See Also:

JavaSource.runUserActionTask(org.netbeans.api.java.source.Task, boolean)

waitUserActionTask

public static void waitUserActionTask(@NonNull
                                      JavaSource src,
                                      @NonNull
                                      Task<CompilationController> uat)
                               throws IOException

Runs user action over source 'src' using JavaSource.runUserActionTask(org.netbeans.api.java.source.Task, boolean) and waits for its completion. The executed Task may indicate that it does not have enough data when scan is in progress, through e.g. checkElement(org.netbeans.api.java.source.CompilationInfo, T). If so, processing of the Task will abort, and will be restarted when the scan finishes. The waitUserActionTask method will wait until the rescheduled task completes.

Unlike postUserActionTask(org.netbeans.api.java.source.JavaSource, org.netbeans.api.java.source.Task), this method propagates exceptiosn from the Task to the caller, even if the Task is postponed and waited for.

Calling this method from Swing ED thread is prohibited.

Parameters:

src - java source to process

uat - task to execute

Throws:

IOException - in the case of a failure in the user task, or scheduling failure (propagated from JavaSource.runUserActionTask(org.netbeans.api.java.source.Task, boolean), JavaSource.runWhenScanFinished(org.netbeans.api.java.source.Task, boolean)

See Also:

JavaSource.runUserActionTask(org.netbeans.api.java.source.Task, boolean)

waitUserTask

public static void waitUserTask(@NonNull
                                Source src,
                                @NonNull
                                UserTask task)
                         throws ParseException

Runs user action over source 'src' using ParserManager.parse(java.util.Collection, org.netbeans.modules.parsing.api.UserTask) and waits for its completion. The executed Task may indicate that it does not have enough data when scan is in progress, through e.g. checkElement(org.netbeans.api.java.source.CompilationInfo, T). If so, processing of the Task will abort, and will be restarted when the scan finishes. The waitUserTask method will wait until the rescheduled task completes.

Unlike postUserTask(org.netbeans.modules.parsing.api.Source, org.netbeans.modules.parsing.api.UserTask), this method propagates exceptiosn from the Task to the caller, even if the Task is postponed and waited for.

Calling this method from Swing ED thread is prohibited.

Parameters:

src - java source to process

uat - task to execute

Throws:

ParseException - in the case of a failure in the user task, or scheduling failure (propagated from JavaSource.runUserActionTask(org.netbeans.api.java.source.Task, boolean), {@link ParserManager#parseWhenScanFinished(java.util.Collection, org.netbeans.modules.parsing.api.UserTask)

See Also:

ParserManager.parse(java.util.Collection, org.netbeans.modules.parsing.api.UserTask), ParserManager.parseWhenScanFinished(java.util.Collection, org.netbeans.modules.parsing.api.UserTask)

checkElement

public static <T extends Element> T checkElement(@NonNull
                                                 CompilationInfo info,
                                                 @NullAllowed
                                                 T e)

Checks that the Element is valid, is not erroneous. If the Element is null or erroneous and scanning is running, the method throws a RetryWhenScanFinished exception to indicate that the action should be retried. The method should be only used in code, which is directly or indirectly executed by waitUserActionTask(org.netbeans.api.java.source.JavaSource, org.netbeans.api.java.source.Task), otherwise IllegalStateException will be thrown.

If scan is not running, the method always returns the value of 'e' parameter.

An example usage is as follows: TreePath tp = ...; Element e = checkElement(cu.getTrees().getElement(tp));

Note: the method may be only called from within waitUserActionTask(org.netbeans.api.java.source.JavaSource, org.netbeans.api.java.source.Task), it aborts the current processing under assumption the user task will be restarted. It is illegal to call the method if not running as user task - IllegalStateException will be thrown.

Parameters:

e - the Element to check

s - the source of the Element

Returns:

the original Element, to support 'fluent' pattern

Throws:

IllegalStateException - if not called from within user task

signalIncompleteData

public static void signalIncompleteData(@NonNull
                                        CompilationInfo ci,
                                        @NullAllowed
                                        ElementHandle handle)

Aborts the user task and calls it again when parsing finishes, if a typename is not available.

Parameters:

el - the Element which causes the trouble

s - source of the Element

Throws:

IllegalStateException - if not called from within waitUserActionTask(org.netbeans.api.java.source.JavaSource, org.netbeans.api.java.source.Task) and the like