Structured tasks results can serve as a placeholder result for a task and make their data partially available.
Sometimes tasks divide their work into multiple sub-tasks. In this case the result of a task can include values from the sub-tasks. This would require from the parent task to wait all of its child worker tasks and then construct an appropriate object that contains these results. This behaviour can hinder dependent tasks in their execution as this can result in waiting for tasks which are unrelated to the work of the dependent task.
Take the following example:
Task A is a complex task that divides its work into separate partitions. Task A will return a complex
object as a result, with fields of X and Y, each corresponding to the result of its worker tasks.
Task B has an input dependency on task A, and will use the field X of its result. This means
that task B will be stalled until task A finishes completely.
This is an undesirable scenario, as task B only needs the result of the sub-task X, while the long running of sub-task Y can stall the execution of task B.
In order to avoid this, structured task results were introduced which are able to separate the concerns of unrelated results contained by their parent.
With structured results, task B in the example above will not be stalled, as task A can return before the completion of its sub-tasks. Task A returns a structured task results with the fields X and Y, which have the values of the sub-task task identifiers. Task B will receive the structured result from task A, and see the task identifier for sub-task X. It will then wait for sub-task X, and proceed with its execution. We can see that in this case it was not necessary for task B to wait for the completion of sub-task Y to get the result from sub-task X.
Tasks can choose to retrieve the actual objectified, non-structured result by calling
toResult(
If a task doesn't want to handle structured task results (but it is still encouraged to to so), it can choose to call
getActualTaskResult(
The TaskContext instance for the tasks can be used for the TaskResultResolver parameter of the methods in this interface.
Implementations are not required to implement Object.hashCode() and Object.equals(
Note: When constructing strucuted task results, make sure to not have circular references in them.
public static StructuredTaskResult | createLiteral( Creates a structured task result object that returns the argument literal object. |
public static Object | getActualTaskResult( Gets the actual object result for the given task dependency future. |
public static Object | getActualTaskResult( Gets the actual object result for the given task future. |
public static Object | getActualTaskResult( Gets the actual object result for the given task identifier. |
public static TaskResultDependencyHandle | getActualTaskResultDependencyHandle( Gets the dependency handle to the actual object of task results associated with the given task identifier. |
public Object | toResult( Converts the structured result to plain object. |
public default TaskResultDependencyHandle | Gets the task result dependency handle to the plain result object. |
The argument must not be a structured task result in nature. That is, it should be suitable to be directly
returned from the toResult(
The returned structured task result implements Object.hashCode() and Object.equals(
If the result of the specified task is an instance of StructuredTaskResult, it will be objectified by
calling toResult(
null
.
If the result of the specified task is an instance of StructuredTaskResult, it will be objectified by
calling toResult(
null
.
The result of the specified task will be retrieved by calling
TaskResultResolver.getTaskResult(
null
.
The method will get the dependency handle to the result object that would be retrieved using
getActualTaskResult(
The method installs a dependency for the task result of the associated task that signals a change if the StructuredTaskResult nature of the result changes.
null
.Calling this method will ensure that the return value will not have any structured task result related fields in it.
this
instance.null
.
The TaskResultDependencyHandle.get() method must return the semantically same object as
toResult(
The TaskResultDependencyHandle.setTaskOutputChangeDetector(
null
.