org.netbeans.spi.project

Class ActionProgress

java.lang.Object

org.netbeans.spi.project.ActionProgress

public abstract class ActionProgress
extends Object

Permits the invoker of an action to follow its progress.

An implementation may be added by a caller to the context of ActionProvider.invokeAction(java.lang.String, org.openide.util.Lookup). If the action provider supports this interface, it should call ActionProgress.start(org.openide.util.Lookup) before returning from invokeAction, and at some subsequent point (possibly still within invokeAction but generally later from a separate task thread) call ActionProgress.finished(boolean) once on the result.

It is best if the provider only calls start if and when it is actually attempting to run an action at this time, avoiding ActionProgress entirely when the action is being skipped—for example, if some precondition is unsatisfied and a warning dialog is displayed rather than building or running anything. However when it would be cumbersome or impossible to determine within the dynamic scope of invokeAction whether or not any real action should be run, for example because those checks are time-consuming and should not block the event thread, the provider may call start and later finished(false) to signify that the action was not successfully run.

SPI example using Ant:

  @Override public void invokeAction(String command, Lookup context) {
     FileObject buildXml = ...;
     String[] antTargets = ...decide on targets using command...;
     if (antTargets == null) { // wrong conditions, not even pretending to run this action
         showWarningDialog();
         return;
     }
     final ActionProgress listener = ActionProgress.start(context);
     try {
         ActionUtils.runTarget(buildXml, antTargets, null).addTaskListener(new TaskListener() {
              @Override public void taskFinished(Task task) {
                 listener.finished(((ExecutorTask) task).result() == 0);
             }
         });
     } catch (IOException x) {
         LOG.log(Level.FINE, "could not start program", x);
         listener.finished(false);
     }
 }
 

Since:

1.43

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ActionProgress() Constructor for subclasses.

Method Summary

Modifier and Type	Method and Description
abstract void	finished(boolean success) Called when the action has completed.
static ActionProgress	start(Lookup context) Locates a progress listener in an action context.
protected abstract void	started() Called when the action is started.

Methods inherited from class java.lang.Object

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

Constructor Detail

ActionProgress

protected ActionProgress()

Constructor for subclasses.

Method Detail

start

@NonNull
public static ActionProgress start(@NonNull
                                            Lookup context)

Locates a progress listener in an action context. ActionProgress.started() is called on the listener immediately. If none was defined by the caller, a dummy implementation is provided so that the ActionProvider need not do a null check.

Parameters:

context - a context as supplied to ActionProvider.invokeAction(java.lang.String, org.openide.util.Lookup)

Returns:

a progress listener (or dummy stub)

started

protected abstract void started()

Called when the action is started. Serves no purpose other than confirming to the caller that this action provider does in fact support this interface and that it should wait for action completion. If this method is not called, the caller will not know when the action is truly finished. Called automatically by ActionProgress.start(org.openide.util.Lookup), so action providers need not pay attention.

finished

public abstract void finished(boolean success)

Called when the action has completed.

The meaning of the success parameter depends on the action and may vary from implementation to implementation, but a caller may expect that an action such as ActionProvider.COMMAND_BUILD will fail if the project could not be built; and an action such as ActionProvider.COMMAND_RUN will fail if the program could not even be started (but perhaps also if it ran and terminated with an erroneous exit code). Some callers may ignore this parameter, but callers which intend to run multiple actions in succession (on the same or different projects) may abort the chain in case one fails.

Parameters:

success - true if the action ran normally, false if it somehow failed