Galileo DTP ODA API Changes Spec

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, whose source were compiled with a version earlier than these ODA 3.2 API interfaces. If an ODA extension has not implemented a new interface method, the ODA Consumer Helper framework will throw an UnsupportedOperationException on its behalf.

Adds Support of Java Object Data Type in Result Set Columns and 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 - New Interface Methods

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

   /**
    * Sets the value of the designated parameter with the given object.
    * @param parameterName     name of the parameter.
    * @param value             an {@link Object} holding the input parameter value
    * @throws OdaException     if data source error occurs
    * @since 3.2
    */
   void setObject( String parameterName, Object value ) throws OdaException;

   /**
    * Sets the value of the designated parameter with the given object.
    * @param parameterId       id of the parameter (1-based).
    * @param value             an {@link Object} holding the input parameter value
    * @throws OdaException     if data source error occurs
    * @since 3.2
    */
   void setObject(int parameterId, Object value ) throws OdaException;

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

   /**
    * Specifies the query characteristics to apply when this is prepared and executed.
    * It takes effect only if specified prior to this preparing a query text
    * at {@link #prepare(String)}.
    * An optional method.  Driver implementation that does not support this operation
    * should throw an UnsupportedOperationException.
    * @param querySpec    specification of characteristics to apply when preparing and executing this
    * @throws OdaException        if data source error occurs
    * @throws UnsupportedOperationException    if this operation is not supported
    * @since 3.2 (DTP 1.7)
    */
   void setSpecification( QuerySpecification querySpec ) 
       throws OdaException, UnsupportedOperationException;

   /**
    * Gets the current specification of characteristics to apply when preparing and executing this.
    * @return the current {@link QuerySpecification}, or null if none is available
    * @since 3.2 (DTP 1.7)
    */
   QuerySpecification getSpecification();

   /**
    * Gets the current effective query text prepared by {@link #prepare(String)}.
    * The effective query text may have been adjusted based on the
    * {@link QuerySpecification} specified, such as result set filtering or projection specifications.
    * This info may be requested by a consumer before this query is executed. 
    * An optional method.
    * @return  the current effective query text,
    *          or null if no query text is effective or available at the current query state
    * @since 3.2 (DTP 1.7)
    */
   String getEffectiveQueryText();

• Ability to Cancel a Query Execution

   /**
    * Cancels this query to abort its 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.
    * An optional method.  Driver implementation that does not support this operation
    * should throw an UnsupportedOperationException.
    * @throws OdaException     if data source error occurs or this method is called at an invalid state
    * @throws UnsupportedOperationException    if this operation is not supported at any state
    * @since 3.2 (DTP 1.7)
    */
    void cancel() throws OdaException, UnsupportedOperationException;

IAdvancedQuery

Component name: ODA Run-time Interfaces

Package name: org.eclipse.datatools.connectivity.oda

• Adds Support of Java Object Data Type in a Parameter

   /**
    * Returns the value of the designated output parameter as an {@link Object}.
    * @param parameterName     name of the parameter.
    * @return                  an {@link Object} holding the output parameter value; may be null
    * @throws OdaException     if data source error occurs.
    * @since       3.2
    */
   Object getObject( String parameterName ) throws OdaException;

   /**
    * Returns the value of the designated output parameter as an {@link Object}.
    * @param parameterId       id of the parameter (1-based).
    * @return                  an {@link Object} holding the output parameter value; may be null
    * @throws OdaException     if data source error occurs.
    * @since       3.2
    */
   Object getObject( int parameterId ) throws OdaException;

IParameterRowSet

Component name: ODA Run-time Interfaces

Package name: org.eclipse.datatools.connectivity.oda

• Adds Support of Java Object Data Type in a Parameter

   /**
    * Sets the object value at the designated column.
    * @param columnIndex   index of the column.
    * @param value         the Java object value.
    * @throws OdaException     if data source error occurs.
    * @since 3.2
    */
   public void setObject( int columnIndex, Object value ) throws OdaException;

   /**
    * Sets the object value at the designated column.
    * @param columnName    name of the column.
    * @param value         the Java object value.
    * @throws OdaException     if data source error occurs.
    * @since 3.2
    */
   public void setObject( String columnName, Object value ) throws OdaException;

IConnection

Component name: ODA Run-time Interfaces

Package name: org.eclipse.datatools.connectivity.oda

• Support of Connection-level Locale Setting

   /**
    * Specifies the locale setting for all locale-sensitive tasks in this connection.
    * An optional method.
    * This setting, if specified, overrides the driver's default locale setting.
    * @param ulocale  a com.ibm.icu.util.ULocale setting
    * @throws OdaException     if data source error occurs
    * @since 3.2 (DTP 1.7)
    */
    void setLocale( ULocale uLocale ) throws OdaException;

New Experimental API - QuerySpecification

Component name: ODA Run-time Query Specification

Package name: org.eclipse.datatools.connectivity.oda.spec

/**
 * EXPERIMENTAL.
 * Specification of the query characteristics to apply when preparing and executing 
 * a query text of an {@link IQuery}.
 * It takes effect only if assigned prior to an IQuery prepares a query text.
 * If any part of the specification is not supported by a driver, its implementation 
 * should throw an OdaException at {@link IQuery#prepare(String)}.
 * @since 3.2 (DTP 1.7)
 */
 public class QuerySpecification

Key Methods:

   /**
    * Specifies the value(s) of a data set query property.  
    * A property may have multiple values kept in a {@link Collection}.
    * The property value specified here may be the same as the value set separately
    * by {@link IQuery#setProperty(String, String)}, which is set after 
    * a query is prepared.  
    * A property value may be null, whose handling is specific to individual 
    * driver implementation.
    * An ODA consumer does not necessarily distinguish whether a property value
    * is not set or explicitly set to null.
    * @param propertyName  name of the property
    * @param value the value of the specified property; may be null
    */
   public void setProperty( String propertyName, Object value ) 
   {...}

   /**
    * Gets the value(s) of a data set query property.  
    * A property may have multiple values kept in a {@link Collection}.
    * The property value specified here may be the same as the value set separately
    * by {@link IQuery#setProperty(String, String)}, which is set after 
    * a query is prepared.  
    * Its handling is optional and specific to individual driver implementation
    * on whether to apply this property value(s) when preparing a query.
    * If a property name is not recognized by the driver,
    * it should simply ignore, and not throw an exception.
    * A property value may be null, whose handling is specific to individual 
    * driver implementation.
    * An ODA consumer does not necessarily distinguish whether a property value
    * is not set or explicitly set to null.  
    * @param propertyName  name of the property
    * @return value the value of the specified property; may be null
    */
   public Object getProperty( String propertyName )
   {...}

   /**
    * Gets the values of all data set query properties, with each property name 
    * as the key to its corresponding value(s). 
    * @return  a {@link Map} of all currently specified data set query properties 
    *          with each property name as the key to its corresponding value(s), 
    *          or null if none
    */
   public Map<String,Object> getProperties()
   {...}

   /**
    * Specifies the input value(s) of a data set query parameter, identified by its native name.  
    * A parameter may have multiple input values kept in a {@link Collection}.
    * The parameter value specified here may be the same as the value set separately
    * by a query's set by data type method, which is set after a query is prepared.
    * A value in primitive data type is specified in its corresponding object type.
    * A parameter value may be null, whose handling is specific to individual 
    * driver implementation.
    * @param parameterName native name of the parameter
    * @param value input value of the specified parameter
    * @see #setParameterValue(int, Object)
    */
   public void setParameterValue( String parameterName, Object value )
   {...}

   /**
    * Specifies the input value(s) of a data set query parameter, identified by its id.  
    * @param parameterId   id of the parameter (1-based)
    * @param value input value of the specified parameter
    * @see #setParameterValue(String, Object)
    */
   public void setParameterValue( int parameterId, Object value )
   {...}

   /**
    * Gets the input value(s) of a data set query parameter, identified by its native name.  
    * A parameter may have multiple input values kept in a {@link Collection}.
    * The parameter value specified here may be the same as the value set separately
    * by a query's set by data type method, which is set after a query is prepared.
    * Its handling is optional and specific to individual driver implementation
    * on whether to apply the parameter input value(s) when preparing a query.
    * A value in primitive data type is specified in its corresponding object type.
    * A parameter value may be null, whose handling is specific to individual 
    * driver implementation.
    * @param parameterName native name of the parameter
    * @return input value of the specified parameter
    * @see #getParameterValue(int)
    */
   public Object getParameterValue( String parameterName )
   {...}

   /**
    * Gets the input value(s) of a data set query parameter, identified by its native name.
    * @param parameterId   id of the parameter (1-based)
    * @return input value of the specified parameter
    * @see #getParameterValue(String)
    */
   public Object getParameterValue( int parameterId )
   {...}

   /**
    * Gets the values of all input parameters of the associated {@link IQuery}, with  
    * each parameter identified by name or id as the key to its corresponding input value(s).
    * @return  a {@link Map} of all currently specified data set query parameters 
    *          with each {@link ParameterIdentifier} as the key 
    *          to its corresponding input value(s)
    */
   public Map<ParameterIdentifier,Object> getParameterValues()
   {...}

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>