Customizing progress bars for transformations

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:
    • In a rule, transform, or extractor
    • In the body of a loop

      For example, if each iteration of the loop generates a target artifact or processes an element in a source model, the body of a loop might be a suitable location to update the progress bar.

    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:

Procedure

  1. In the plugin.xml file of the project that contains a transformation, in the <Transformation> element, create a <Property> element for the PROGRESS_MONITOR_WORK_UNITS property, as in the following example:
    <Transformation
    	groupPath="myExampleTransformation"
    	id="myExampleTransformation.transformation"
    	name="Transformation"
    	sourceModelType="UML2"
    	targetModelType="resource"
    	version="1.0.0"/>
    	<Property
    		id="PROGRESS_MONITOR_WORK_UNITS"
    		metatype="integer"
    		name="PROGRESS_MONITOR_WORK_UNITS"
    		readonly="true"
    		value="200"
    
    	/>
    </Transformation>
  2. In the source code for the transformation, determine which transformation elements, transforms, or methods represent the completion of specific tasks in the transformation or transform within a transformation.
  3. For each location in the code that you identified in step 2, insert the code to update the progress bar. In each location, an instance of the transformation context variable must be available so that the properties that are related to the progress bar can update. The following table shows examples of how to invoke the methods that update the progress bar:
    Method of updating the progress bar Location to add the code Example of code to add
    Invoking methods from the IProgressMonitor interface In a transformation element class such as an extractor, rule, or transform This example assumes that the transformation updates the progress bar by 10 work units:
    IProgressMonitor progressMonitor = getProgressMonitor(context);
    progressMonitor.worked(10);
    In another type of class in the transformation This example assumes that the transformation updates the progress bar by 10 work units:
    IProgressMonitor progressMonitor =
    	(IProgressMonitor) context.getPropertyValue(ITransformContext.PROGRESS_MONITOR);
    progressMonitor.worked(10);
    Running an instance of the com.ibm.xtools.transform.core.UpdateProgressMonitorRule rule Typically at the end of the transform The following code fragment shows an example of a transform that runs an instance of the UpdateProgressMonitor rule at the end of the transform. The code comments are placeholders for other tasks that the transform completes:
    private AbstractTransform createClassTransform(ITransformationDescriptor desc) {
    	Transform classTransform = new Transform(desc);
    	// Add the transform elements that read the source classes.
    	// One of these elements must set the following transform
    	// context variables by invoking the setPropertyValue method in the com.ibm.xtools.transform.core.ITransformContext interface:
    	// -PROGRESS_MONITOR_INCREMENT 
    	// -PROGRESS_MONITOR_TASK_NAME
    	
    	// Add the rule to update the progress monitor.
    	classTransform.add(new UpdateProgressMonitorRule("myRuleId", "myRuleName"));
    	return classTransform;
    } 

Results

To test the updates to progress bar, complete the following steps:
  1. Start a runtime workbench.
  2. In the runtime workbench, create a transformation configuration for the transformation to run.
  3. 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.

Feedback