Understanding the tool lifecycle

1. Construct

During the construction phase, Data Management creates a new instance of the Tool. This happens once for each tool dropped on the project canvas. When that project is saved and later re-opened, the construction phase will create a new tool instance for each tool on the canvas.

Additionally, tool instances may be created incidentally when Data Management assembles the tool palette (see Building and installing your tool), so it is important not to assume that all Tool instances belong to a valid project.

2. Configure

During the configuration phase, Data Management builds the Tool's user interface and validates that its properties have been properly set.

The configure method will be called multiple times during the tool's lifespan:

• When the tool is dropped on the canvas of a new or existing project.

• When an existing project is opened.

• When changes to the tool's property panel are committed.

Tools must override the configure method in net.redpoint.dataflow.transform.Tool to perform configuration routines. The configure method typically performs the following:

• Validate user-settable properties.

• Test availability of resources (e.g. does the input file exist?).

• Process any Schemas provided by "upstream" connected Tools.

• Create Schemas for presentation to "downstream" connected Tools.

3. Pre-prepare

This is an advanced topic, and you probably won't need it.

The prepare() method is normally where your SDK tool will allocate resources, open files, etc. However, if you are writing sophisticated tools that cooperate on shared data or a shared resource connection, you may find that the timing of prepare is not exactly right for you. Specifically, prepare is called before your tool runs, but prePrepare is called before any tool's prepare is called.  Use this in conjunction with the postCleanup method to initialize, coordinate, and finalize resources that are shared between tools.

• It only makes sense for groups of tools that share data (usually a connection or some other resource) and need to set up the shared resource or shared transaction.

• Your shared resource will usually be stored in static data members or your class, which should be properly protected using synchronized methods or blocks.

• The prePrepare method of your class should create the shared resource if it doesn't yet exist, and the remaining tools in the group will not create the resource (but may add information to it).

• prePrepare is not called before each web-service execution

4. Prepare

During the prepare phase, Data Management sets up any resources required by the tool to support its execution. Examples include instantiating readers, writers, and database connections. Tools can override the prepare method in net.redpoint.dataflow.transform.Tool to perform preparation routines. The prepare method is guaranteed to be called once per tool per project execution—unless the prepare method of an upstream tool fails, in which case no downstream tools' prepare method will be called.

5. Execute

During the execute phase, Data Management actually runs the tool. The semantics of running a tool vary for the different tool types supported by Data Management:

• When an InputTool is run, Data Management calls the tool's nextRecord method until it returns false indicating that no additional records are available.

• When an OutputTool is run, Data Management calls the tool's nextRecord method until no additional records are available on the tool's input connector.

• When a TransformTool is run, Data Management calls the tool's nextRecord method until no additional records are available on the tool's input connector.

• When a GeneralTool is run, Data Management calls the Tool's run method once. The run method reads input Records and writes output Records until the tool determines it is finished.

6. Cleanup

During the cleanup phase, Data Management invokes the cleanup method to provide tools with an opportunity to free any resources that were used during execution and are no longer needed. Examples include disposing of readers, writers, and database connections. Tools can override the cleanup method in net.redpoint.dataflow.transform.Tool to specify their own cleanup routines. The cleanup method is guaranteed to be called at least once per project execution. The cleanup method may be called without a corresponding call to prepare, if the prepare method of another upstream tool has failed.

It is vital to close open files and database connections in the cleanup method—failing to do so may result in locked files and resource leaks that degrade the performance and stability of your projects.

7. Post-cleanup

This is an advanced topic, and you probably won't need it.

The cleanup method is normally where your SDK tool will release resources, close files, etc. However, if you are writing sophisticated tools that cooperate on shared data or a shared resource connection, you may find that the timing of cleanup is not exactly right for you. Specifically, cleanup is called when your tool is done, but perhaps while other tools are still executing. This timing makes it harder to implement "last tool finished should do the final thing," such as committing a set of changes or closing a shared resource. In such a case, your tool should implement the postCleanup(boolean success) method. postCleanup will be called after all tools have completed execution, and will be passed a parameter indicating whether the overall project execution was successful. Some tips for implementing postCleanup:

• It only makes sense for groups of tools that share data (usually a connection or some other resource) and need to clean up the shared resource or commit a shared transaction.

• Your shared resource will usually be stored in static data members or your class, which should be properly protected using synchronized methods or blocks.

• The prePrepare method of your class should create the shared resource if it doesn't yet exist, and the remaining tools in the group will not create the resource (but may add information to it).

• The first tool of a group in the project whose postCleanup method is called should perform the finalization steps, and the remainder will ignore the call. The first such tool should indicate to the rest that finalization is complete by setting the shared resource to null. This ensures a single finalization action will be taken for the entire group.

• postCleanup is not called at the end of a web-service execution