View source for Use Case - Extending an ODA Runtime Driver

== Purpose ==

[http://www.eclipse.org/datatools DTP] and [http://www.eclipse.org/birt BIRT] deliver out-of-the-box Open Data Access (ODA) drivers to access common data sources, such as XML, CSV files, and JDBC. 
<br>The user community often wants to further extend these drivers to customize them for their specific data source environment.  

One use case is to customize the collection of connection property values at runtime to suit one's own security environment.  The ODA consumer ''propertyProvider'' extension point supports this.

Another use case is to pass in an application-specific context object to an ODA driver at runtime.  For example, a J2EE application would obtain a data input stream or a supplied connection for use by an out-of-the-box ODA driver.  One would thus need to extend the ODA runtime driver to process the specialized context object, by overriding just a few methods in its corresponding implementation class.  
<br>To deploy the extending class, instead of implementing a new full-blown ODA driver with both runtime and design-time extensions, a simpler approach is to deploy it using the ''driverBridge'' extension point.  An ODA driver bridge extension serves as an intermediate layer that intercepts the ODA interface methods called by an ODA consumer to an ODA runtime driver.  Using this approach, there is no need to change the reference of the original ODA data source id to your extended one.   Furthermore, it would be able to simply use the original ODA designer as its own.

== Extension Points Involved ==

Each extension point may be used independently, as appropriate.
* propertyProvider
** org.eclipse.datatools.connectivity.oda.consumer.propertyProvider

* driverBridge
** org.eclipse.datatools.connectivity.oda.consumer.driverBridge

== Java API Interfaces/Classes ==

* propertyProvider
** org.eclipse.datatools.connectivity.oda.consumer.services.IPropertyProvider

* driverBridge
** org.eclipse.datatools.connectivity.oda package (same Java interfaces as an ODA runtime driver)

== Exemplary Clients ==

* propertyProvider
** org.eclipse.datatools.connectivity.oda.consumer.services.impl.PropertyProviderImpl

* driverBridge
: See the sample driver bridge implementation attached in [https://bugs.eclipse.org/bugs/show_bug.cgi?id=135246#c4 Bugzilla 135246].  It extends the BIRT oda.jdbc runtime driver to use an externally supplied JDBC connection.