public final class ScanUtils extends Object
JavaSource.runUserActionTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, 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:
ScanUtils.checkElement(org.netbeans.api.java.source.CompilationInfo, T)
to assert element's presence and validity
ScanUtils.signalIncompleteData(org.netbeans.api.java.source.CompilationInfo, org.netbeans.api.java.source.ElementHandle)
to request restart if running parallel to scan
An example pattern how to use this class is:
final TreePath tp = ... ; // obtain a tree path
ScanUtils.waitUserActionTask(new Task<{@link 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
}
}
};
public static Future<Void> postUserActionTask(@NonNull JavaSource src, @NonNull Task<CompilationController> uat)
JavaSource.runUserActionTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, 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. ScanUtils.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 ScanUtils.postUserTask(org.netbeans.modules.parsing.api.Source, org.netbeans.modules.parsing.api.UserTask)
.
src
- JavaSource to processuat
- action task that will be executedScanUtils.postUserTask(org.netbeans.modules.parsing.api.Source, org.netbeans.modules.parsing.api.UserTask)
,
JavaSource.runUserActionTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, boolean)
public static Future<Void> postUserTask(@NonNull Source src, @NonNull UserTask task)
ScanUtils.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<org.netbeans.api.java.source.CompilationController>, 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.
src
- Source to processtask
- action task that will be executedJavaSource.runUserActionTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, boolean)
public static void waitUserActionTask(@NonNull JavaSource src, @NonNull Task<CompilationController> uat) throws IOException
JavaSource.runUserActionTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, 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. ScanUtils.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 ScanUtils.postUserActionTask(org.netbeans.api.java.source.JavaSource, org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>)
, 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.
src
- java source to processuat
- task to executeIOException
- in the case of a failure in the user task, or scheduling failure (propagated from JavaSource.runUserActionTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, boolean)
,
JavaSource.runWhenScanFinished(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, boolean)
JavaSource.runUserActionTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, boolean)
public static void waitUserTask(@NonNull Source src, @NonNull UserTask task) throws ParseException
ParserManager.parse(java.util.Collection<org.netbeans.modules.parsing.api.Source>, 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. ScanUtils.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 ScanUtils.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.
src
- java source to processtask
- task to executeParseException
- in the case of a failure in the user task, or scheduling failure (propagated from JavaSource.runUserActionTask(org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>, boolean)
,
ParserManager.parseWhenScanFinished(java.util.Collection, org.netbeans.modules.parsing.api.UserTask)
ParserManager.parse(java.util.Collection, org.netbeans.modules.parsing.api.UserTask)
,
ParserManager.parseWhenScanFinished(java.util.Collection, org.netbeans.modules.parsing.api.UserTask)
public static <T extends Element> T checkElement(@NonNull CompilationInfo info, @NullAllowed T e)
null
or erroneous and
scanning is running, the method throws a ScanUtils.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 ScanUtils.waitUserActionTask(org.netbeans.api.java.source.JavaSource, org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>)
, 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 ScanUtils.waitUserActionTask(org.netbeans.api.java.source.JavaSource, org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>)
, 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.
e
- the Element to checkinfo
- the source of the ElementIllegalStateException
- if not called from within user taskpublic static void signalIncompleteData(@NonNull CompilationInfo ci, @NullAllowed ElementHandle handle)
ci
- the Element which causes the troublehandle
- of the ElementIllegalStateException
- if not called from within ScanUtils.waitUserActionTask(org.netbeans.api.java.source.JavaSource, org.netbeans.api.java.source.Task<org.netbeans.api.java.source.CompilationController>)
and the like