JBoss.orgCommunity Documentation

Chapter 5. Using the Connector Development Kit

5.1. Overview
5.2. Programmatic Utilities
5.2.1. Language Translation
5.2.2. Command Execution
5.3. Connector Environment
5.4. Command Line Tester
5.4.1. Using the Command Line Tester
5.4.2. Loading Your Connector
5.4.3. Executing Commands
5.4.4. Scripting

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, please see the Connector API Javadoc, which include the CDK Javadoc.

All components provided by the CDK are in the package com.metamatrix.cdk.api.  

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:

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.

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:

Preparing your connector to execute commands consists of the following steps:

Following is an example transcript of how this process might look in a DOS command window.  User input is in bold.

D:\metamatrix\console\cdk> set CONNECTORPATH=D:\myconn\myconn.jar
D:\metamatrix\console\cdk> cdk
========================== ENV SETTINGS ==========================
MM_ROOT        = D:\metamatrix\console
MM_JAVA        = D:\metamatrix\console\jre
CONNECTORPATH  = D:\myconn\myconn.jar
CLASSPATH      = ;D:\metamatrix\console\cdk\metamatrix-cdk.jar;D:\myconn\myconn.jar;

D:\metamatrix\console>D:\metamatrix\tools400wl7\console\jre\bin\java -Xmx256m -Dmetamatrix.config.none -Dmetamatrix.log=4 com.metamatrix.cdk.ConnectorShell
>load com.metamatrix.myconn.MyConnector d:\myconn\myconn.vdb
>setproperty user joe

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
  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:\metamatrix\console\cdk>cdk runscript d:\myconn\my.script test
========================== ENV SETTINGS ==========================
MM_ROOT        = D:\metamatrix\console
MM_JAVA        = D:\metamatrix\console\jre
CONNECTORPATH  = D:\myconn\myconn.jar
CLASSPATH      = ;D:\metamatrix\console\cdk\metamatrix-cdk.jar;D:\myconn\myconn.jar;

D:\metamatrix\console>D:\metamatrix\tools400wl7\console\jre\bin\java -Xmx256m -Dmetamatrix.config.none -Dmetamatrix.log=4 com.metamatrix.cdk.ConnectorShell runscript my.script 
>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 /metamatrix/tools400wl7/console/cdk/yahoo.script.test failed.  CompareResults Error: Value mismatch at row 2 and column 2: expected = 10, actual = 15


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.