© Markus Duft 2018
Markus DuftEclipse TEA Revealedhttps://doi.org/10.1007/978-1-4842-4093-9_5

5. Tasks

Markus Duft1 
(1)
Peggau, Steiermark, Austria
 

A Task is basically a piece of executable code that is dynamically created and managed by TEA. You can use dependency injection (DI) to obtain objects in the DI context of the Task (or any parent context—see Figure 3-4). You can think of it as a more powerful Runnable.

A simple Task implementation looks like the code snippet in Listing 5-1.
import org.eclipse.e4.core.di.annotations.Execute;
import org.eclipse.tea.core.services.TaskingLog;
public class SampleSimpleTask {
      @Execute
      public void doIt(TaskingLog log) {
            log.info("Hello World");
      }
}
Listing 5-1

A Very Simple Task

Something worth noting here is that the sample Task does not implement an interface. The only requirement for a Task is that it has a single method annotated with @Execute. This method can use DI. Every Task has its own dependency injection context. This is important, for instance, when injecting a TaskProgressTracker , which we will cover in detail in Chapter 8.

Naming

Apart from the required @Execute method , you can influence how TEA handles and presents a Task (in logs, UI, etc.).

Providing a proper name for a Task is the most basic thing you need to do. By default, TEA will use the simple class name of a Task to show in logs and the Tasking Live View (If you revisit any of the samples from Chapter 4, you will see this because we have not named a Task until now. For instance, see Figure 4-7.)

The recommended method of providing a name is to use the @Named annotation . This annotation is usually used in DI to point to a certain named object in the context instead of using the class name as key. In this case it provides the name for the Task, as shown in Listing 5-2.
@Named("Named Task")
public class TaskStaticNamed {
      @Execute
      public void run(TaskingLog log) {
            log.info("Hello World");
      }
}
Listing 5-2

Naming a Task with the @Named annotation

This Task will be shown as "Named Task" instead of TaskStaticNamed whenever TEA needs to display a Task name—in the log as well as in the Tasking Live View.

The second method of giving a Task a name is to provide a toString method on the object, as seen in Listing 5-3.
public class TaskDynamicNamed {
      @Execute
      public void run(TaskingLog log) {
            log.info("Hello World");
      }
      @Override
      public String toString() {
             return "Named " +
                   System.currentTimeMillis();
      }
}
Listing 5-3

Naming a Task with the toString Method

Both methods have the exact same effect with regards to TEA. However, the first one is preferred because it is more compact to write and it is possible to implement a toString method for different use cases if the annotation is present. The toString method will not be evaluated if the annotation is present. On the other hand, the annotation can only hold a static value. Using toString allows for a more dynamic name (as seen in Listing 5-3). Figure 5-1 shows how both variants look in action.
../images/470772_1_En_5_Chapter/470772_1_En_5_Fig1_HTML.jpg
Figure 5-1

@Named and toString in Action

Hint

Run the TEA-Book-Samples launch configuration and find the TEA ➤ Samples ➤ CH05-S01: Naming entry in the TEA menu.

Incidentally, the same naming logic is also used for TaskChain implementations.

Return Values

It is not normally possible to return any values from a Task . Since the framework is always the caller for each Task (as we will describe in Chapter 6, Tasks are passed to the framework, and the framework is responsible for executing them at the right point in time), it would not make that much sense in the first place.

But, to be able to tell the framework how well the Task did, it can return an IStatus1 to it, as shown in Listing 5-4.
public class TaskRunSomething{
      @Execute
      public IStatus run() {
             return new Status(IStatus.WARNING,
                   "org.eclipse.tea.demo",
                   "Something smells fishy");
      }
}
Listing 5-4

Returning Information from a Task

The Task will be displayed and/or logged with a warning accordingly; see Figure 5-2. The second way to influence a Task result is by throwing an OperationCanceledException . Both methods are described in more detail when we talk about progress reporting in Chapter 8.
../images/470772_1_En_5_Chapter/470772_1_En_5_Fig2_HTML.jpg
Figure 5-2

Returning an IStatus to the TEA framework

Output Capturing

Sometimes a Task needs to call code that is not aware of TEA at all; it could be any preexisting code. In this case, the code may do a plethora of different things to log things, including writing to System.out and System.err. This will work just fine in headless environments because TEA logs to the same place in these cases. However, when running a Task in the IDE, this is suboptimal. Output is partially in the Tasking Console, and the System.out/System.err part goes to the output streams of the IDE itself. That’s definitely what we don’t want.

To get around this, TEA provides an annotation (@TaskCaptureStdOutput) for Task implementations that instructs the framework to redirect System.out and System.err to the TaskingLog for as long as the Task @Execute method runs, as seen in Listing 5-5.
@TaskCaptureStdOutput
public class TaskRunSomething{
      private void someExternalStuff() {
             System.err.println("Something hidden");
      }
      @Execute
      public void callExternal() {
            someExternalStuff();
      }
}
Listing 5-5

Capturing Output of Third-party Code

Figure 5-3 shows how the code in Listing 5-5 will show up in the sample IDE (run TEA ➤ Samples ➤ CH05-S03: Output Capturing).
../images/470772_1_En_5_Chapter/470772_1_En_5_Fig3_HTML.jpg
Figure 5-3

Capturing output from System.err

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
13.58.247.31