Both TMTransform and TMTransformExecutor are created from the factory class TMTransformerFactory.
Both are provided with a default constructor (zero argument) and a constructor taking an arbitrary Java Object. If an arbitrary Java object is provided, this can be used by Java functions written in TM to call back to the calling program. To do this merely requires the functions to use the TMContext:getUserReferenceObject within their body.
As constructed neither object is not initialised and before it can be used to transform data must be properly initialised. Once it is initialised it is in a 'ready' state - available to take input data and transform it into output data.
Initialising TMTransform/TMTransformExecutor
All TMTransformCommon objects must be provided with three pieces data namely:
Providing project details
Where the transform project has been generated into Java the correct interface to use is:
This will cause the loading of the relevant Java classes from the class path during the completeInitialisation call.
Where the generated project is provided as XML the interface is:
You should only provide the XML data in one of the forms. See also setXMLSMLReaderVersion(int xmlLoaderVersion) & setXMLSMLReaderTransform(String xmlLoaderProject) which are used to set up the version of transformer used to read the meta data.
More than one project may be set into a given run-time interface, TMTransformer or TMTransformExecutor. Note that the first project provided is known to the system as the 'primary project'. This is treated slightly differently to other projects in both TMTransformer and TMTransform Executor.
Setting Adaptors
Once the project(s) have been set then it is necessary to set source and target adapters for each project.
There is little difference between using in-built adapter types or generic adapter types.
Once adapters are constructed they are set on the TMTransformerCommon adapter using:
You will also need to set the connection parameters for the adapters - this is done using setInstanceConnectionData for all types of adapter. This takes a Map of keys and values. Thus typical code - for example to set up the in-built read JDBC adapter could look like:
TMAdapter srcTMAdapter =
TMBuiltInAdaptorFactory.makeNewReadTMJDBCAdapter(aTMTransformer);
Map srcParams = new HashMap();
srcParams.put (TMJDBCAdapter.NAME_USER, "Scott");
srcParams.put (TMJDBCAdapter.NAME_PASSWORD, "Tiger");
srcParams.put (TMJDBCAdapter.NAME_URL, "jdbc:oracle:thin:@LOCALHOST:1521:garmon");
srcParams.put (TMJDBCAdapter.NAME_DRIVER, "oracle.jdbc.driver.OracleDriver");
srcTMAdapter.setInstanceConnectionData(srcParams);
aTMTransformer.setSource (projectName,srcTMAdapter);
Normally adapters have the same long life time as TMTransformer or TMTransformExecutor itself. However the 'session' mechanism is available should the adapter wish to divide its lifetime into a series of independent periods. What happens in each period is entirely-user defined - so an adapter may physically connect to different sources and sinks of data in each of these periods.
Running the Transforms and Getting Results
Once setSource and setTarget have been called the design patterns for TMTransformer and TMTransformExecutor differ.
Short Lived Mode
For a TMTransformer the correct pattern is simply openProjectAndResources followed by runAllTransforms. Note that where the target is Java or XML target then you may need to then ask the write adapter for the results of the transforms (i.e. the mapped data). Where the source is Java or XML target then you may need to then place data into the read write adapter before runAllTransforms.
Long Lived Mode
Completing Initialisation
Once all sources and targets have been provided then TMTransformExecutor's completeInitialisation method should be called. This loads XML or Java descriptions of the meta data. If the adapters are non-generic then the completeInitialisation method opens the primary sources and targets.
Where the adapters are generic the method setmeta-data will be called inside each user written adapter. This provides the user with access to useful meta data for the internal operation of the adapter. (Note that information that is provided depends on the setting up of setRequiresmeta-data in the loader interface.) TMTransformExecutor does not open generic adapters at this point - it is a user responsibility to open the generic adapters used with TMTransformExecutor.
Note completeInitialisation method will throw exceptions if it is called prematurely or any of these methods fail. Calling transform methods is not possible until completeInitialisation has completed.
The Main Loop
Once initialisation is complete the transformer is ready to serve and transform data. The main control loop that does this is explained in more detail later in this document.
Closing a TMTransformExecutor
The TMTransformExecutor:closeDown method should be called when no further transformations are required. This will call the finish methods inside any generic adapters and will close down any of the in-built ETL adapters.
Note that both TMTransformer and TMTransformExecutor are single threaded processes. However there is nothing to stop generic adapters from using separate threads internally- for example to send data across a network, or simply to queue data for efficiency.
In addition TMTransformExecutor may know of 'stalled' items that are necessarily waiting for further items in the input pipelines. Thus if closeDown is called at the 'wrong time 'generic adapters may wish to throw a TMException while TMTransformExecutor may throw a TMException if the pool of 'stalled' items is not empty.
The TM Test Tool
The TM Test Tool is simply an interface onto the short lived TMTransformer. In addition to testing and interactive transform development (in conjunction with the Design Tool) it can be used as a primitive deployment tool and can be run form the command line. It communicates with the run-time session itself by an executing a Java class called 'com.prismt.transform.run-time.exec.RunMaps'. It picks up the required parameters to run from a file called 'Exec.properties' in the current directory. It is possible to use this mechanism to run transforms without writing any Java code at all.