JBoss.orgCommunity Documentation
The Connector Developer Kit (CDK) is a set of programmatic and command line utilities for testing connectors. The programmatic components of the CDK are useful for unit testing your connector and the command line utilities is useful for integration testing and regression testing (due to scripting abilities).
This chapter covers usage of both aspects of the CDK. For more detailed information about the CDK programmatic utilities also consult the Teiid JavaDocs.
All components provided by the CDK are in the package com.metamatrix.cdk.api.
Commands are sent to the Connector API in terms of the language interfaces discussed in the Command Language chapter. Typically, a connector must write logic to read and sometimes manipulate these objects. The CDK language translation utilities can be used to write unit tests for translation code or command execution.
The utilities are provided in the class TranslationUtility. This class has the following methods:
Table 4.1. Language Translation
|
Method Name |
Description |
|---|---|
|
TranslationUtility(String vdbFile) |
Constructor – takes the path to a file which is a valid metadata archive created by the Teiid Designer. These files have the suffix “.vdb”. |
|
createRuntimeMetadata() |
Creates an instance of RuntimeMetadata that can be used to test code that uses runtime metadata when translating or executing commands. |
|
parseCommand(String sql) |
Take a single-source command and return an ICommand that can be used to test translation or execution of commands. |
The primary purpose of a Connector is to execute commands against an information source. The query execution utilities allow you to test the execution of commands programmatically. This utility does not run the Teiid query engine or the connector manager although does simulate what happens when those components use a Connector to execute a command.
The command execution utilities are provided in the class ConnectorHost. This class has the following methods:
Table 4.2. Command Execution
|
Method Name |
Description |
|---|---|
|
ConnectorHost |
Constructor – takes a Connector instance, a set of connector property values, and the path to a VDB archive file |
|
setBatchSize |
Sets the batch size to use when executing commands. |
|
setExecutionContext |
Sets the security context values currently being used to execute commands. This method may be called multiple times during the use of a single instance of ConnectorHost to change the current context. |
|
getConnectorEnvironmentProperties |
Helper method to retrieve the properties passed to the ConnectorHost constructor. |
|
executeCommand |
Execute a command and return the results using this connector. |
|
executeBatchedUpdates |
Execute a set of commands as a batched update. |
|
getCommand |
Use the host metadata to get the ICommand for a SQL string. |
Here is some example code showing how to use ConnectorHost to test a connector:
// Prepare state for testing
MyConnector connector = new MyConnector();
Properties props = new Properties();
props.setProperty(“user”, “myuser”);
props.setProperty(“password”, “mypassword”);
String vdbFile = “c:/mymetadata.vdb”;
// Create host
ConnectorHost host = new ConnectorHost(connector, props, vdbFile);
// Execute query
List results = host.executeCommand(“SELECT col FROM group WHERE col = 5”);
// Compare actual results to expected results
// . . .
The executeCommand() method will return results as a List of rows. Each row is itself a List of objects in column order. So, each row should have the same number of items corresponding to the columns in the SELECT clause of the query. In the case of an INSERT, UPDATE, or DELETE, a single “row” will be returned with a single column that contains the update count.
Many parts of the Connector API require use of the Connector Environment. The EnvironmentUtility can be used to obtain and control a Connector Environment instance.
Table 4.3. Command Execution
|
Method Name |
Description |
|---|---|
|
createExecutionContext |
Creates a ExecutionContext instance. |
|
createStdoutLogger |
Creates an instance of ConnectorLogger that prints log messages to system.out( ) |
|
createEnvironment |
Creates an instance of connectorEnvironment for use in your testing environment. |
|
createExecutionContext |
Creates an ExecutionContext instance. |
In addition, some implementations of ConnectorLogger are provided which can be used as needed to build a custom logger for testing. BaseLogger is a base logger class that can be extended to create your own ConnectorLogger implementation. SysLogger is a utility implementation that logs to System.out.
The command line tester is available in the mmtools kit along with the other Teiid products in the tools directory. The tester can be executed in interactive mode by running
<unzipped folder>S\cdk\cdk.bat
Typing “help” in the command line tester provides a list of all available options. These options are listed here with some additional detail:
Table 4.4. Connector Lifecycle
|
Option |
Arguments |
Description |
|---|---|---|
|
Load Archive |
ArchiveFileName |
Load the Connector archive file, which loads the Connector type definition file and all the extension modules into the CDK shell. |
|
Load |
ConnectorClass vdbFile |
Load a connector by specifying the connector class name and the VDB metadata archive file |
|
LoadFromScript |
ScriptFile |
Load a connector from a script |
|
LoadProperties |
PropertyFile |
Load a set of properties for your connector from a file |
|
SetProperty |
PropertyName PropertyValue |
Set the value of a property |
|
GetProperties |
List all properties currently set on the connector | |
|
Start |
Start the connector | |
|
Stop |
Stop the connector |
Table 4.5. Command Execution
|
Option |
Arguments |
Description |
|---|---|---|
|
Select |
Sql |
Run a SELECT statement. This option takes multi-line input terminated with “;” |
|
Insert |
Sql |
Execute an INSERT statement. This option takes multi-line input terminated with a “;”. |
|
Update |
Sql |
Execute an UPDATE statement. This option takes multi-line input terminated with “;” |
|
Delete |
Sql |
Execute a DELETE statement. This option takes multi-line input terminated with a “;”. |
|
SetBatchSize |
BatchSize |
Set the batch size used when retrieving results |
|
SetExecutionContext |
VDBName VDBVersion UserName |
Set the properties of the current security context |
|
SetPrintStackOnError |
PrintStackOnError |
Set whether to print the stack trace when an error is received |
Table 4.6. Scripting
|
Option |
Arguments |
Description |
|---|---|---|
|
SetScriptFile |
ScriptFile |
Set the script file to use |
|
Run |
ScriptName |
Run a script with the file name |
|
Runall |
Run all scripts loaded by loadFromScript | |
|
RunScript |
ScriptFile ScriptNameWithinFile |
Run a particular script in a script file |
|
SetFailOnError |
FailOnError |
Set whether to fail a script when an error is encountered or continue on |
|
Result |
ExpectedResults |
Compares actual results from the previous command with the expected results. This command is only available when using the command line tester in script mode. |
Table 4.7. Miscellaneous
|
Option |
Arguments |
Description |
|---|---|---|
|
CreateArchive |
ArchiveFileName CDKFileName ExtensionModuleDir |
Creates a connector archive file based on the properties supplied. |
|
CreateTemplate |
TemplateFile |
Create a template connector type file at the given file name. |
|
Help |
List all options | |
|
Quit |
Quit the command line tester |
Preparing your connector to execute commands consists of the following steps:
Add your connector code to the CDK classpath. The cdk.bat script looks for this code in the CONNECTORPATH environment variable. This variable can be set with the DOS shell command “SET CONNECTORPATH=c:\path\to\connector.jar”. Alternately, you can modify the value of the CONNECTORPATH environment variable in the cdk.bat file.
Start the command line tester. You can start the tester by executing the cdk.bat file in the cdk directory of the Teiid Tools installation.
Load your connector class and the associated runtime metadata. You can load your connector by using the “load” command and specifying the fully-qualified class name of your Connector implementation and the path to a VDB file. The VDB runtime metadata archive should contain the metadata you want to use while testing.
Set any properties required by your connector. This can be accomplished with the setProperty command for individual properties or the loadProperties command to load a set of properties from either a properties file or a connector binding file. You can use the “getProperties” command to view the current property settings.
Start the connector. Use the “start” command in the command-line tester to start your connector.
Following is an example transcript of how this process might look in a DOS command window. User input is in bold.
D:\teiid\cdk> set CONNECTORPATH=D:\myconn\myconn.jar
D:\teiid\cdk> cdk.bat
========================== ENV SETTINGS ==========================
TEIID_ROOT = D:\teiid
CONNECTORPATH = D:\myconn\myconn.jar
CLASSPATH = ;D:\teiid\cdk\metamatrix-cdk.jar;D:\myconn\myconn.jar;
==================================================================
java -Xmx256m com.metamatrix.cdk.ConnectorShell
Starting
Started
>load com.metamatrix.myconn.MyConnector d:\myconn\myconn.vdb
>setproperty user joe
>start
>
Commands can be executed against your connector using the SELECT, INSERT, UPDATE, and DELETE commands. Procedure execution is not currently supported via the command line tester. Commands may span multiple lines and should be terminated with a “;”.
When a command is executed, the results are printed to the console. Following is an example session executing a SELECT command with the command line tester. User input is in bold.
>SELECT Name, Value FROM MyModel.MyGroup WHERE Name = ‘xyz’;
String Integer
xyz 5
xyz 10
>
One of the most useful capabilities of the command-line tester is the ability to capture a sequence of commands in a script and automate the execution of the script. This allows for the rapid creation of regression and acceptance tests.
A script file may contain multiple scripts, where each script is grouped together with { } and a name. Following is an example of a script file. This script file also uses the special script-only command RESULTS that will compare the results of the last execution with the specified expected results.
test {
load com.metamatrix.myconn.MyConnector d:\myconn\myconn.vdb
setproperty user joe
start
SELECT Name, Value FROM MyModel.MyGroup WHERE Name = ‘xyz’;
results [
String Integer
xyz 5
xyz 10
]
}
To execute this file, run the command line tester in scripting mode and specify the script file and the script within the file:
D:\teiid\cdk>cdk runscript d:\myconn\my.script test
========================== ENV SETTINGS ==========================
TEIID_ROOT = D:\teiid
CONNECTORPATH = D:\myconn\myconn.jar
CLASSPATH = ;D:\teiid\cdk\metamatrix-cdk.jar;D:\myconn\myconn.jar;
==================================================================
java -Xmx256m -Dmetamatrix.config.none -Dmetamatrix.log=4 com.metamatrix.cdk.ConnectorShell runscript my.script
Starting
Started
>Executing: load com.metamatrix.myconn.MyConnector d:\myconn\myconn.vdb
>Executing: setproperty user joe
>Executing: start
>Executing: select Name, Value from MyModel.MyGroup where Name = ‘xyz’;
String Integer
xyz 5
xyz 15
>Test /teiid/cdk/yahoo.script.test failed. CompareResults Error: Value mismatch at row 2 and column 2: expected = 10, actual = 15
>Finished
D:\teiid\cdk>
The script run above illustrates the output when the test result fails due to differences between expected and actual results. In this case the value was expected to be 10 in the script but was actually 15. The setFailOnError command can be used to fail the execution of the entire script if an error occurs.
Scripts can also be run in interactive mode by using the setScriptFile and run commands. This can be useful to record portions of your interactive testing to avoid re-typing later.