JBoss.orgCommunity Documentation
Once you have written and compiled the code for your connector, there are several steps to deploy your connector to Teiid:
Creating a Connector Type Definition file that defines the properties required to initialize your connector.
Identifying the Extension Modules (jars and resources) required for the Connector to run.
Creating the Connector Archive file to bundle the Connector Type Definition file and the Extension Modules.
Creating a Connector Binding using your Connector Type.
This chapter will help you perform these steps.
A Connector Type Definition file defines a connector in Teiid. The Connector Type Definition file defines some key properties that allow Teiid to use your connector as well as specifying other properties your connector might need.
A Connector Type Definition file is in XML format and typically has the extension “.cdk”. It defines a default name for the connector type, the properties expected by the connector, and other information that allows the properties to be displayed correctly in the Console when a Connector Binding is created from the Connector Type.
An example of this file can be found in Appendix A. It may be helpful to refer to this file while reading this section. The template file can also be created using the Connector Development Kit.
The Connector API has built-in mechanisms for using the properties defined in the Connector ComponentType definition in the configuration.xml located in your deploy directory. For custom connectors the following properties are of primary importance:
Table 5.1. Connector Properties
|
Property Name |
Example Value |
Description |
|---|---|---|
|
ConnectorClass |
foo.MyConnector |
Fully-qualified name of class implementing the Connector interface. |
|
ConnectorClassPath |
extensionjar:foo.jar |
Semi-colon delimited list of jars defining the classpath of this connector. Typically this includes the actual code for your connector as well as any 3rd party dependencies. |
For more information on the Connector Classpath, see the section Understanding the Connector Classpath
Most connectors require some initialization parameters to connect to the underlying enterprise information system. These properties can be defined in the Connector Type Definition file along with their default values and other property metadata. The actual property values can be changed when the connector is deployed in the Teiid Console.
Each connector property carries with it several attributes that are used by the Teiid Console to integrate the connector seamlessly into Teiid.
Table 5.2. All Attributes
|
Attribute Name |
Example Value |
Description |
|---|---|---|
|
Name |
ExampleProperty |
Property name – should only contain letters, no spaces or other punctuation. This is the name of the property as it will be passed to the connector in the ConnectorEnvironment. |
|
DisplayName |
Example property |
The property name as displayed in the Console. Typically this is a nicely formatted version of the Name attribute. |
|
ShortDescription |
The example property is used to control something. |
A short description that is displayed as a tooltip of the property in the Teiid Console. |
|
DefaultValue |
Xyz |
A default value for the property. This value will be auto-filled when a connector binding is created from the Connector Type. |
|
IsRequired |
false |
If true, then this property is required. Any required property without a value is displayed in red in the connector binding properties panel. |
|
IsModifiable |
true |
If set to “false”, the property is visible only when viewing all properties and is not modifiable in the properties panel. |
|
IsMasked |
false |
If set to “true”, the property will be masked with *’s when it is entered and saved in an encrypted form. This attribute is typically used with passwords. |
|
IsExpert |
true |
Depending on the property display, the property can be optionally displayed for advanced users. |
|
PropertyType |
String |
The short name of a built-in Java primitive wrapper Object type. Other possible values include Integer, Boolean, etc. |
A property may also be constrained to a set of allowed values by adding child AllowedValue elements, i.e. <AllowedValue>value</AllowedValue>. Adding allowed values will cause the property to be displayed with a dropdown that limits the user selection to the allowed values.
Extension Modules are used in Teiid to store code that extends Teiid in a central managed location. Extension Module JAR files are stored in the repository database and all Teiid processes access this database to obtain extension code. Custom connector code is typically deployed as extension models.
By default each connector binding is loaded using the Teiid common classloader. Any needed extension modules are automatically added to common classpath. The common classloader is also a delegating classloader, so it's possible for classes to be found from the classpath set for Teiid or it's containing application.
If class conflicts would arise from delegation or shared classloading, each connector binding can be loaded in an isolated classloader (shared only by connectors with the same classpath), by setting the connector binding property UsePostDelegation to true. This classloading mode loads classes via the Teiid Extension Modules before loading classes from higher level classloaders.
The ConnectorClasspath property of your connector defines the extension module jars that are included in your connector’s classpath. The connector classpath is defined as a semi-colon delimited list of extension modules. Extension module jar files must be prefixed with "extensionjar:"
The Connector Archive file is a bundled version of all files needed by this Connector to execute in Teiid. This file includes the Connector Type Definition file and all the Extension Modules required by the Connector to create a connector archive file (CAF)..
The archive is a standard zip file.
Start the CDK tool by executing cdk.bat
Execute “CreateArchive” command by supplying:
Path to the name of the archive file to create
Path to the Connector Type Definition file
Path to the directory where the required Extension Modules (jar files) are stored (note that only .jar files specified in the ConnectorClassPath property of the Connector Type definition file are bundled.
The file created by the CDK can be opened with any zip file utility to verify the required files are included.
The archive file can be tested in the CDK tool by loading it using the command “loadArchive”. Refer CDK chapter for more information.
To use a new connector type definition in Teiid, the Connector Archive file must be imported via the AdminAPI via the addConnectorArchive method.
To use the new connector type during the development of the VDB for testing using the SQLExplorer, Connector Archive File must be imported into the Designer tools. To perform this task, perform the following steps.
Start Designer
Open the project and in the “vdb” execute panel, click on the “Open the Configuration Manager” link. For more information consult the designer’s guide.
In the result window, click “Import a Connector Type (.cdk,.caf)” link and follow directions.
The Connector Type can now be used to create Connector Bindings.
Connector Binding properties can also be defined in the Designer for the given Connector Type, if the corresponding Connector Archive File is imported into the Designer. If you try to execute your VDB with SQLExplorer in the Designer, this tool will present you with a window to specify such Connector Bindings. The user is required specify these binding properties before they can test using the SQLExplorer. For more information on how this can be accomplished please refer to the Designer User’s Guide.
Also, note that the bindings specified in the Designer tool are automatically bundled into the VDB for deployment, so if there are any properties that needs to be changed from development environment to the production environment, those properties need to be modified when a VDB is later deployed.