You can customize a transformation to update the progress
bar in a progress window as the transformation completes its tasks.
This feature provides transformation users with more accurate information
about how much work the transformation has completed.
Before you begin
A transformation author must register the transformation
with the transformation service.
For more information about
the properties that this topic describes, see the link to the related
reference topic at the end of this topic.
About this task
Conceptually, the progress bar is divided into equal portions,
where each portion corresponds to a work unit. By default, the transformation
core defines
x+1 work units for the progress bar,
where
x represents the number of utilities that
a transformation invokes, plus one work unit for the transformation
itself. Consider the following examples:
- If a transformation does not invoke any utilities, the transformation
core defines one work unit for the progress bar. The progress bar
shows how much work the transformation has completed.
- If a transformation invokes two utilities, the transformation
core defines three work units for the progress bar. When a utility
is complete, the transformation core updates one portion of the progress
bar. As the transformation completes its tasks, it updates the progress
bar by the number of work units that the transformation author allocates
for each task.
For the work unit of the progress bar that is allocated
to the transformation, you can control updates to the progress bar
by dividing the work unit into several smaller work units. Each smaller
work unit represents a task that the transformation completes.
Typically
a transformation completes multiple tasks, where each task is completed
by a transformation element such as a rule, extractor, or transform.
As a transformation author, you can identify the points at which the
transformation completes tasks. At these points, you can add code
that updates the progress bar as the transformation completes its
tasks.
After you understand the implementation details of the
transformation, you can add code that updates the progress bar in
one of the following ways:
- Invoke the methods from the IProgressMonitor interface. You might
invoke these methods from the following locations:
Consider a basic transformation that completes two tasks:
parsing the transformation source, and generating the output, which
you might estimate to be 100 files. For this example, assume that
you set the
PROGRESS_MONITOR_WORK_UNITS property
to 200. You might allocate the progress bar work units in the following
way:
- After the transformation parses the source, increment the progress
bar by half of the units specified in the PROGRESS_MONITOR_WORK_UNITS property.
- When the transformation generates output, for each artifact that
it generates, increment the progress bar by one unit.
- Run an instance of the com.ibm.xtools.transform.core.UpdateProgressMonitorRule rule.
Consider
a transformation that contains a transform that processes classes
in a source model, perhaps by invoking a Class extractor. Depending
on the source model, this transform might process UML classes or code
classes. For each class in the source model, the Class transform runs.
After the transform processes a class, the transform runs an instance
of the com.ibm.xtools.transform.core.UpdateProgressMonitorRule rule
to update the progress bar by the number of units that the PROGRESS_MONITOR_INCREMENT property
specifies.
The code fragment in the table in step 3 shows the skeleton
of a transform that processes classes and runs an instance of the com.ibm.xtools.transform.core.UpdateProgressMonitorRule rule. The comments
in the code fragment describe the tasks that the transform completes,
and the order in which it completes them.
To refine the accuracy of the progress
bar when a transformation runs, complete the following steps:
Results
To test the updates to progress bar, complete the following
steps:
- Start a runtime workbench.
- In the runtime workbench, create a transformation configuration
for the transformation to run.
- Run the transformation.
When the transformation runs, the progress bar in the progress
window updates more accurately than if the transformation code did
not update the progress bar.