DTP Connectivity Framework

Developer’s Quick Start Guide

 

1         Implementing a Connection Profile

Connection profiles are created by developers using the org.eclipse.datatools.connectivity.connectionProfile extension point.

 

When implementing a connection profile extension, the following additional elements should be specified:

 

In addition to the above elements, the following may be specified:

 

The following base classes are provided to help implement some of the above classes:

2         Integrating with the Driver Definition Framework

For connection profiles capable of connecting to multiple vendor implementations using a common set of connection properties, but whose driver details differ, a driver definition can be used for describing these properties.  A driver definition can be referenced by each connection profile instance that connects to a specific server type.  For example, a database connection profile might reference a driver definition that defines the driver JAR files and driver class required to open a connection.  The connection profile itself would contain properties such as connection URL, user ID and password.

 

The connectivity framework provides a few utility classes for integrating the driver definition framework into your connection profile.

 

org.eclipse.datatools.connectivity.internal.ui.DriverListCombo can be used to add a control to your connection profile wizard or property page.  Filters can be applied to the control so that only driver definition meeting your requirements are displayed (e.g. only driver definitions in the “Database” category).

 

org.eclipse.datatools.connectivity.DriverConnectionBase can be used as a base class for your IConnection implementation.  This class takes care of locating the driver definition and creating a ClassLoader based on the JAR files specified in the driver definition.  This class assumes the ID for the driver definition is stored under the key, org.eclipse.datatools.connectivity.driverDefinitionID (this property key is defined in org.eclipse.datatools.connectivity.ConnectionProfileConstants.PROP_DRIVER_DEFINITION_ID).  (Note, this class also implements the IServerVersionProvider interface, which is used by the framework for collecting the server’s type name and version (e.g. Adaptive Server Enterprise, 15.0.0.0).)

3         Implementing a Connection Factory

In general, a connection factory simply returns an org.eclipse.datatools.connectivity.IConnection instance.  This interface provides consumers with methods for accessing generic capabilities common to most connection types (e.g. close() is useful for closing connections whose “raw” type is unknown to the caller).  (Note, this interface will be enhanced as new connection management features are added to the connectivity framework.)

 

IConnection objects can also implement the org.eclipse.datatools.connectivity.IServerVersionProvider interface.  This interface is used by the framework for acquiring version information related to the server (e.g. server name, “Adaptive Server Enterprise”;server version, “15.0”;technology name, “JDBC”;technology version, “3.0”).  org.eclipse.datatools.connectivity.VersionProviderConnection should be used as your base connection class if you wish to enable this functionality for your connection.  This base class takes care of updating the version properties stored with the profile.  Refer to the Javadoc for more information on using this class.

 

When implementing a connection factory, it is recommended that connection factories be identified using the object type returned by IConnection.getRawConnection() (e.g. java.sql.Connection).  If this convention is used, consumers will have a good idea what type of connection is returned by the factory.

4         Building Tooling around Connection Profiles

There are several options for integrating tooling components with connection profiles.  Most involve keying tooling components to specific properties of the profile.

4.1      Keying to Specific Connection Types

Tooling can be keyed to work with a specific type of connection.  This is accomplished by keying the tooling to a specific connection factory using the org.eclipse.datatools.connectivity.profile.property.factoryID filter property.

 

The main benefit of keying to a connection factory is that it decouples the tooling from any specific connection profile type.  This allows the tooling to work with any type of profile as long as the specified connection factory exists for the profile.

 

If some portions of the tooling need to be customized for working with specific profiles, it is recommended that the tooling provide extension points that can be keyed to a specific profile type (see below).  For example, providers can specify custom catalog loaders for that support their specific databases.  Another example would be overriding an action for a specific profile type (in this case the action is provided by the generic tooling and overridden for the specific profile by the profile provider).

 

This is the preferred method for interacting with connection profiles.

4.2      Keying to Specific Profile Types

Tooling can also be keyed for use with a specific type of connection profile.  This is accomplished by keying the tooling to specific profile type using the org.eclipse.datatools.profile.property.id filter property.

 

This option may be desirable if you know exactly which types of profiles you wish to interact with, or if you wish to provide custom tooling for a specific profile type.

4.3      Other Useful Profile Properties

org.eclipse.datatools.connectivity.IConnectionProfileActionFilter contains a full list of available properties for use in enabling tooling.

4.4      Accessing Connection Profiles

org.eclipse.datatools.connectivity.ProfileManager is provided for programmatically working with profile instances within the workspace (e.g. createProfile(), deleteProfile(), getProfilesByCategory(), etc.).

5         Implementing a Content Extension for the DSE

You can display custom content for a connection profile in the DSE using the common navigator extension, org.eclipse.ui.navigator.navigatorContent (the common navigator framework is part of the Eclipse platform).

 

Ideally, content extensions should be keyed toward using a particular connection type.  This will enable your contribution for any connection profile type, provided the required connection factory type is implemented for that profile.

 

TODO: update helper classes once we’ve migrated them to the platform navigator framework (ProfileNavigatorContentExtensionBase and ContentExtensionFactoryBase)

6         Data Tools Connectivity Integration

The following sections detail how DTP is using the connectivity framework for database connections.  The org.eclipse.datatools.connectivity.db.generic plug-in contains base implementations for creating wizard pages, property pages, and connections specific to DB servers that can be connected to using JDBC.

6.1      Driver Definition Integration

The generic DB connection factory, wizard and property page implementations are designed to work with driver definitions containing the following properties:

 

All of the above property keys are defined in org.eclipse.datatools.connectivity.db.generic.IDBDriverDefinitionConstants.

6.2      Connection Profile Implementations

The generic DB connection factory, wizard and property page implementations are designed to work with connection profiles containing the following properties:

 

The first two property keys are defined in org.eclipse.datatools.connectivity.db.generic.IDBConnectionProfileConstants.  The remaining property keys are defined in org.eclipse.datatools.connectivity.ConnectionProfileConstants.

6.3      Connection Factory Implementations

The following connection factory implementations are provided:

 

Ideally these IDs should be obtained programmatically using the class name (e.g. java.sql.Connection.class.getName()).

7         Implementing an Open Data Access (ODA) Extension

The Open Data Access (ODA) component is an open and flexible data access framework that provides a common way for a consumer application to access data from heterogeneous data sources.  The DTP ODA framework is actively consumed by the Eclipse BIRT project.

See this link for an overview of the ODA framework and its scope of functionalities:

http://www.eclipse.org/datatools/project_connectivity/connectivity_doc/OdaOverview.htm

 

The following ODA plug-ins are included in the current DTP Milestone 1 build:

Additional DTP ODA data source plug-ins can be found in the Eclipse BIRT project source tree in CVS, and are available in the BIRT download builds: http://download.eclipse.org/birt/downloads/ .

 

The ODA framework will be integrated with the Connection Profiles in Milestone 2.  More details will be provided then.

 

When implementing a custom ODA data source provider, the plug-in extension must implement the org.eclipse.datatools.connectivity.oda.dataSource extension point. 

See the schema and documentation defined in datasource.exsd.

 

The ODA extension point defines a driverClass attribute in the dataSource element.  It serves as the entry point to an ODA driver that implements the ODA run-time interfaces.  A custom ODA implementation has a high degree of flexibility on the scope of functionalities it wants to provide.  A good number of the interface methods are optional, and can simply throw an UnsupportedOperationException. 

Below are the required ODA run-time interfaces, defined in the org.eclipse.datatools.connectivity.oda package.  See the package's Javadoc documentation for more information.

 

·         IDriver – The entry point to a custom ODA run-time driver’s implementation

·         IConnection Establishes a live connection to the underlying data provider

·         IQuery – Prepares and executes a query text to return data in an IResultSet

·         IResultSet – Used to access a set of data rows retrieved by an IQuery instance

·         IResultSetMetaData – Represents the meta-data of an IResultSet instance

·         IDataSetMetaData – Provides comprehensive information on the driver’s capabilities for each type of data set query

·         IParameterMetaData – Represents the meta-data of input/output parameters defined in a prepared query; required only if the driver supports query parameters

 

To aid in the development of a custom ODA driver, a set of default implementation of the main ODA runtime interfaces is provided in the org.eclipse.datatools.connectivity.oda.impl package. These classes assume the behavior of a simple ODA driver, and have labeled TODO tasks for a driver developer to add on data source-specific behavior.  These concrete classes are provided as an aid only, for use as templates or base classes; their use is purely optional.