Context

• To allow for Teiid Server communication, Designer must incorporate a Teiid Server Client Runtime (client-runtime);
• A client-runtime's version must be compatible with the Teiid Server it is attempting to connect with;
• Designer makes use of internal Teiid APIs for use in its transformations. Such APIs are subject to change with each Teiid Server release.

Problem

• Since Teiid Server versions can (and do) change their internal APIs, Designer upgrades its client-runtime to conform with the latest release;
• Upgrade of client-runtimes is done at the expense of backward compatibility, ie. a Teiid Server should be upgraded at the same time as Designer;
• Upgrading of both the Teiid Server and Designer is not always appropriate, eg. Designer users lose out on functionality improvements since the Teiid Server cannot be immediately upgraded.

Solution

Summary

• Inclusion of multiple client-runtimes in Designer;
• Client-runtimes registered by a single or set of Teiid Server versions;
• Designer detects the version of the Teiid Server upon connection and uses the most appropriate client-runtime for the connection;
• Any function of Designer that is Teiid Server version-specific should be handed off to the client-runtime by the core application.

Design

Interfaces

The plugin org.teiid.designer.spi provides a set of interfaces that are required to be implemented by client-runtimes. Designer does and should only ever access client-runtimes through these interfaces. Core Designer plugins should never depend directly on any client-runtime implementation plugin.

org.teiid.designer.runtime.spi

• ITeiidServer - the core Designer server interface, which is generic to all cient-runtimes. When a teiid server connection is established, the server implementation is initialised with a client-runtime specific version of the IExecutionAdmin interface;
• IExecutionAdmin - each client-runtime plugin is required to implement this interface for direct communication with the teiid server;
• IQueryService - provides access to query syntax objects, visitors and validators;
• IExecutionAdminFactory - root factory that provides access to the client-runtime's ExecutionAdmin and QueryService implementations.

org.teiid.designer.runtime.version.spi

• ITeiidServerVersion - java pojo that encapsulates the major, minor and micro versions of a teiid server. Wildcards are allowed for the minor and micro elements to allow support across multiple teiid server versions.

org.teiid.designer.runtime.registry.TeiidRuntimeRegistry class

• Central registry of all available client-runtime plugins. The registry is a singleton instance and returns a client-runtime's ExecutionAdmin and QueryService based on a provided TeiidServer or TeiidServerVersion respectively. It should not normally be necessary to get the ExecutionAdmin explicitly since all functionality should be accessed through the ITeiidServer. However, the QueryService is something that can be accessed fairly frequently using the following syntax:

   

  TeiidRuntimeRegistry.getInstance().getQueryService( server.getTeiidServerVersion() );
  

Extension Point

Registration of client-runtime plugins is performed through the Eclipse extension point org.teiid.designer.spi.teiidRuntimeClient. The extension requires the specifying of an implementation of the IExecutionAdminFactory interface and the teiid server versions that the client-runtime supports. Upon initialisation of Designer, this extension point is read by the TeiidRuntimeRegistry singleton, registering all client-runtimes. Since wildcards are supported, it is important to take care in avoiding overlapping client-runtime versions as previous registrations will be overwritten by those client-runtimes registered later. The extension implementation for the teiid 8.2 client-runtime plugin is shown below.

Client Runtime Implementation

The client-runtime plugin is required to implement the Designer spi interfaces, including all the query syntax language symbols. The original implementation sought to construct delegate classes that implemented the spi interfaces, wrapping the Teiid classes. However, this design has been superceded with the teiid client runtime code being directly forked and the spi interfaces implemented directly. This removed a significant amount of boiler-plate code and removed a needless source of bugs. Since the client runtime plugins still track the teiid code repository, any future teiid commits can be merged in, ensuring the code keeps apace with current teiid work.

It should be noted that only when a teiid version is officially branched will a client runtime plugin be created. This ensures that the latter is based on a stable codebase that can be successfully forked.

The final client-runtime plugin will implement a significant number of interfaces and will require a unit test fragment of its own to ensure that it is operating as expected by the application. The unit test fragment is the only bundle project that is allowed to directly depend on a client-runtime implement plugin!

A client-runtime plugin should look similar to the 8.2 project shown below.

Designer at Runtime

When Designer is initialised, all available client-runtimes are registered and can be matched to Teiid Server connections. Previously, the default teiid server had to be selected prior to deploying a vdb. However, in order for the transformation models to be created with the correct query syntax, it is now paramount that the default server should be selected prior to model creation. Setting the default server is performed using the Servers View, as shown below. Once the default server has been selected, its ITeiidServer instance and ITeiidServerVersion is advertised all functionaliy requiring a specific client-runtime implementation.