Connecting to a Data Source Using an IDD

Step 3: Processing native-mode queries

Queries can be sent to an IDD in one of two forms, either as a string containing a fully-formed query in the native language of the data source, or as a K2 data structure in the form of an abstract syntax tree. To handle native queries, your connection class must implement its executeNativeQuery and getNativeQueryResultType methods.

executeNativeQuery is called by K2 whenever your driver's native query function is called. The string argument of the function is passed to the method, along with an environment in which to evaluate the query. The environment is rarely applicable to the evaluation of the query. Your driver should be able to send the query string, untouched, to the data source.

K2 might also send the query string to getNativeQueryResultType, which should return the K2 type of the result that would be returned by executeNativeQuery, without actually executing the query. This feature is primarily a future enhancement of the execution engine, though getNativeQueryResultType will always be called with an empty string to get the overall return type of the driver, as described earlier.

The type of the result returned by executeNativeQuery must match the type reported by getNativeQueryResultType when it is called with an empty string. That is, it must be an object whose class extends K2.absyn.expns.absynExpA. When you receive the query results from the data source, you need to create K2 objects that represent the result. This usually entails traversing the results (in whatever form the data source returned them), and building the result, bottom-up. The details of how you traverse and build depend on the data source. For example, PipeDriver requires the external process it runs to return results in a predefined data exchange format. It gets the results as a string, and uses a LALR parser to convert the string into K2 objects. JConnectDriver simply iterates over the resulting bag and creates a K2.abysn.expns.absynRecord to hold each row of the result. You should do whatever is appropriate for your data source.

Since executeNativeQuery and getNativeQueryResultType are abstract in DriverConnectionA, you must provide some implementation for them, even if you do not intend to support your driver's native query function. Typically these methods are implemented to throw a new K2.driver.UnsupportedQueryException, constructed from your connection object, the incoming query string (wrapped in a K2.absyn.expns.absynString), and a meaningful error message.

K2 can also send queries to your IDD in K2-mode.

[Tech Docs Index]