JBoss.orgCommunity Documentation

Chapter 6. Connector Deployment

6.1. Overview
6.2. Connector Type Definition File
6.2.1. Required Properties
6.2.2. Connector Properties
6.3. Extension Modules
6.3.1. Extension Modules
6.3.2. Understanding the Connector Classpath
6.4. Connector Archive File
6.5. Importing the Connector Archive
6.5.1. Into Teiid Server
6.5.2. Into Enterprise or Dimension Designer
6.6. Creating a Connector Binding
6.6.1. In Console
6.6.2. In Designer

6.1. Overview

Once you have written and compiled the code for your connector, there are several steps to deploy your connector to a Teiid Server:

This chapter will help you perform these steps.  

6.2. Connector Type Definition File

A Connector Type Definition file defines a connector in the Teiid Server.  The Connector Type Definition file defines some key properties that allow the Teiid Server 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 requires the following properties for the Teiid Server to load and use your connector.

Table 6.1. Required Connector Properties

Property Attribute

Example Value

Description

ConnectorClass

com.my.connector.MyConnector

Fully-qualified name of class implementing the Connector interface.

ConnectorClassPath

extensionjar:mycode.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 will 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 the Teiid Server.

Table 6.2. All Properties

Property 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.

6.3. Extension Modules

Extension Modules are used in the Teiid Server to store code that extends the Teiid Server 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.

Each connector is started in an isolated classloader instance. This classloader loads classes via the Teiid Extension Modules before loading classes from the Teiid system classpath. Ideally, all of your connector classes should be loaded from extension modules, which are configured in the Teiid Console.  

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:”

6.4. Connector Archive File

The Connector Archive file is a bundled version of all files needed by this Connector to execute in the Teiid server. 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 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 to Chapter 4 for more information on the CDK tool

6.5. Importing the Connector Archive

To use a new connector type definition in the Teiid Server, the Connector Archive file must be imported in the Teiid Console or using the Admin API.  To perform this task, perform the following steps:

  1. Start the Teiid Console and connect to your Teiid Server.

  2. Select Connector Types from the tree at the left of the Console.  This will display a list of existing Connector Types on the right.

  3. Click the Import… button on the bottom of the Connector Type list.  This will open the Import Connector Type Wizard.

  4. Select your Connector Archive file and click the Next button.

  5. Click Finish to create the Connector Type.  At this point you will see the new Connector Type in the list of Connector Types.  

  6. Select Extension Modules from the tree at the left of the Console, and make sure all the required Extension Modules are added.

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.

  1. Start the Enterprise or Dimension designer

  2. 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.

  1. 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.  

6.6. Creating a Connector Binding

To actually use your connector in the Teiid System, you must create a Connector Binding that specifies the specific property values for an instance of the Connector Type.  To create a Connector Binding, perform the following steps:

  1. Start the Teiid Console and connect to your Teiid Server.

  2. Select Connector Bindings from the tree at the left of the Console.  This will display a list of existing Connector Bindings on the right.

  3. Click the New… button below the list of Connector Bindings.  This will launch the Create New Connector Binding Wizard.  

  4. In Step 1, you must specify a name for your connector binding and select your connector type from the Connector Type list.  Click the Next button to continue.

  5. In Step 2, the connector properties from your connector type definition file will be displayed.  Default values are used to pre-fill the value fields if they exist.  Required properties are displayed with bold text.  Required properties with no value specified are displayed in red text.  These fields must be completed before the Next button will enable.  Optional properties may be displayed by checking the Optional Properties checkbox.  When you have completed all required values, click the Next button.

  6. In Step 3, you are given the opportunity to set the enabled state of the new binding in each PSC.  Typically, no modifications need to be made.  For more information, see the Teiid Console User’s Guide.  Click the Finish button to complete the wizard and create your connector binding.  The Connector Binding list now displays your new connector binding.  

To actually start your connector binding, please consult the Teiid Console User’s Guide for detailed information.

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 Enterprise 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 deployed to the Teiid Server using the Console to correct resources.