Jump to: navigation, search

Galileo DTP ODA API Changes Spec

Revision as of 00:35, 4 March 2009 by Lchan.actuate.com (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Open Data Access (ODA) 3.2 API Change Specification

ODA Framework Enhancements and Runtime API Changes

The Open Data Access (ODA) framework defines Java interfaces for accessing data from any type of heterogeneous data sources. A data source provider implements such interfaces for consumption by any ODA data consumer applications. A number of enhancements are identified for the ODA interfaces to support advanced features requested by the community.

Below sections describe the enhancements and corresponding proposed Java interface changes in the org.eclipse.datatools.connectivity.oda bundle version 3.2, for release in DTP 1.7 (Galileo).

Backward Compatibility Support

The ODA framework will provide binary backward compatibility support of an ODA data source extension's implementation that were compiled with a version earlier than the ODA 3.2 API interfaces. Through the use of the ODA Consumer Helper framework, if an ODA extension has not implemented a new interface method called by an ODA consumer application, an UnsupportedOperationException will be thrown on its behalf to the caller.

Adds Support of Java Object Data Type in Result Set Columns or Parameters

Bugzilla 176396 The Java Object data type is added as a new ODA scalar data type. The new data type is supported in an ODA result set column, plus in an ODA parameter for both input/output and scalar/complex types.

The ODA framework does not require a driver implementation to provide a wrapper for such Java objects. It is up to the implementation of an ODA consumer and runtime driver to consume the object type. An ODA consumer application may impose own additional restriction on the type of Object that it can consume. For example, in order for a consumer application to sort the values of a result set column, the Object data type in an ODA result set column must implement the java.lang.Comparable interface.

See the API Changes section below for the corresponding new methods in IResultSet (for output columns), IQuery (for scalar input parameters), IAdvancedQuery (for scalar output parameters) and IParameterRowSet (for complex input/output parameters).

An ODA run-time driver may choose to add support for the Java Object data type through any of these new methods, or simply throws an UnsupportedOperationException.

The “JavaObject” data type will also be added to the list of valid values for an ODA Scalar Data Type in the ODA dataSource extension point schema and the ODA Design model.

Availability of Data Set Property and Input Parameter Values *before* Query Preparation

Bugzilla 125447

The value of a data set query property is currently passed to an ODA runtime driver only after a query is prepared (via the IQuery#setProperty(String, String) method). Similarly, a data set input parameter value is passed only after a query is prepared (via the IQuery set by data type methods). Some ODA runtime drivers may however need the properties or input parameter values to prepare a query. This enhancement allows an ODA runtime driver to have access to its data set property and parameter values in a query specification, which is set before a query is prepared.

For backward compatibility support, the existing setProperty and set parameter value API methods will continue to specify its corresponding value after a query is prepared. The availability of property and input parameter values in a QuerySpecification is thus made in addition to those set by the existing API methods.

Its handling is optional and specific to individual ODA driver implementation on whether to apply the data set property and/or input parameter values found in a QuerySpecification when preparing a query. See the API Changes section below on the new interface methods added in IQuery to assign a QuerySpecification that may contain property and input parameter values.

Ability to Cancel a Query Execution

Bugzilla 263902

An ODA consumer application may need to cancel or abort the execution of a query that it has started in an ODA runtime driver. This enhancement adds a new API method to abort a query execution if supported by the underlying data source. This method can be used by one thread to cancel a query that is being executed by another thread.

Support of this method is optional in an ODA runtime driver implementation.

See the API Changes section below on the new interface method added in IQuery to cancel its execution, if supported.

Support of Connection-level Locale Setting

Bugzilla 266967

A locale-sensitive ODA consumer application may need locale support from an underlying ODA data provider. An ODA runtime driver that has locale support may pick up the default application-level locale setting for all its operations. However, an ODA consumer application may need to specify a different locale setting for individual ODA connection instance. This enhancement adds a new API method for an ODA consumer to specify the locale setting for all the locale-sensitive operations within a connection.

Support of this method is optional in an ODA runtime driver implementation.

See the API Changes section below on the new interface method added in IConnection to specify a locale, if supported.

ODA Run-time API Changes

IResultSet

Component name = ODA Run-time Interfaces
Package name = org.eclipse.datatools.connectivity.oda
  • Adds Support of Java Object Data Type in Result Set Columns
   /**
    * Gets the value of the designated column in the current row as an {@link Object}.
    * If the column value is intended to be sortable by its consumer, the type of Object 
    * returned must implement the {@link Comparable} interface.
    * @param index column number (1-based)
    * @return      an {@link Object} value in the specific column of the current row
    * @throws OdaException     if data source error occurs
    * @since       3.2
    */
   Object getObject( int index ) throws OdaException;
   /**
    * Gets the value of the designated column in the current row as an {@link Object}.
    * If the column value is intended to be sortable by its consumer, the type of Object 
    * returned must implement the {@link Comparable} interface.
    * @param columnName    column name
    * @return  an {@link Object} value in the specific column of the current row; may be null
    * @throws OdaException     if data source error occurs
    * @since       3.2
    */
   Object getObject( String columnName ) throws OdaException;

IQuery

Component name = ODA Run-time Interfaces
Package name = org.eclipse.datatools.connectivity.oda
  • Adds Support of Java Object Data Type in a Parameter
  • Availability of Data Set Property and Input Parameter Values *before* Query Preparation
  • Ability to Cancel a Query Execution

IAdvancedQuery

Component name = ODA Run-time Interfaces
Package name = org.eclipse.datatools.connectivity.oda
  • Adds Support of Java Object Data Type in a Parameter

IParameterRowSet

Component name = ODA Run-time Interfaces
Package name = org.eclipse.datatools.connectivity.oda
  • Adds Support of Java Object Data Type in a Parameter

IConnection

Component name = ODA Run-time Interfaces
Package name = org.eclipse.datatools.connectivity.oda
  • Support of Connection-level Locale Setting

New Experimental API - QuerySpecification

Related ODA API Changes

OdaScalarDataType

Component name = ODA Design Model Interfaces
Package name = org.eclipse.datatools.connectivity.oda.design
  • Adds Support of Java Object Data Type in a Result Set Column or Parameter
Add a new data type code and literal string for the Java Object data type.
public static final int JAVA_OBJECT;
   public static final OdaScalarDataType JAVA_OBJECT_LITERAL;

datasource.exsd

Component name = ODA Plug-in Extension Point Schema Definition
Package name = org.eclipse.datatools.connectivity.oda
  • Adds Support of Java Object Data Type in a Result Set Column or Parameter
Add JavaObject data type to the list of ODA scalar data type names.
    <attribute name="odaScalarDataType" use="required" >
           <simpleType>
              <restriction base="string">
                 <enumeration value="Date">
                 </enumeration>
                 <enumeration value="Double">
                 </enumeration>
                 <enumeration value="Integer">
                 </enumeration>
                 <enumeration value="String">
                 </enumeration>
                 <enumeration value="Time">
                 </enumeration>
                 <enumeration value="Timestamp">
                 </enumeration>
                 <enumeration value="Decimal">
                 </enumeration>
                 <enumeration value="Blob">
                 </enumeration>
                 <enumeration value="Clob">
                 </enumeration>
                 <enumeration value="Boolean">
                 </enumeration>
                 <enumeration value="JavaObject">
                 </enumeration>
              </restriction>
           </simpleType>
    </attribute>