An IDD can export entry points to K2 as one or more variables. Each variable is used to represent some well-defined chunk of data at the source. For example, the JDBC driver represents the tables in a database as variables, one variable for each table. Each variable is of type "bag of records", where the labels in the records correspond to the column names in the table. This way, if you want to write a query to select from a particular table, you simply refer to the corresponding variable in your query, treating it as a bag of records.
If you want to provide entry point variables, you need to implement the getSourceMetaData method in your connection class, to return an object that implements the K2.driver.DataSourceMetaDataI interface. (If you don't want to provide entry point variables, implement getSourceMetaData to simply return null.) K2 has a built-in class called K2.driver.DataSourceMetaData that implements this interface, which should be sufficient for most needs. The DataSourceMetaData constructor takes four parameters:
An array of the names of the variables, which will be available for use in incoming queries. Each should uniquely identify the portion of the data source to which the variable will be mapped. That is, no variable name in this array should be exported by any other IDD to which the K2 server is connected.
An array (parallel to the previous parameter) of the variables themselves, each of which is a K2.absyn.expns.absynVar. These should be generated by a call to absynVar.freshVar, passing it the corresponding name from above, and the value absynVar.EXTENT. The latter is the kind of variable that represents an entry point.
An array of the types of the variables, which must parallel the previous parameters. Each element is itself an array of the possible types of the data represented by the variable, each of which is one of the types in K2.absyn.types. These types, like all data types in K2, may be arbitrarily deeply nested, and can be as complex as you need them to be. You build up these type objects starting with the base types (objects of type type0), and pass these to the constructors of the more complex types, like typeRecord and typeCollection. We provide the ability to specify multiple types for each variable as a future extension of the execution engine. As of now, it is assumed that there will be only one type each (that is, each inner array will have length 1).
An array of the indexes available for the variables, parallel to the previous parameters. Each element is itself an array of objects that implement the interface K2.driver.IndexSetI, to allow for multiple sets of indexes for each variable. These indexes are intended to provide additional information to the optimizer, though their use is still a future enhancement.
K2 makes the entry point variables available to incoming queries by adding them to the default environment that each client inherits when it connects. K2 also provides another "entry point" for each IDD, in the form of a "native query function". The function takes a string as its parameter, and can return any type of result. The intent of this function is to allow the user to pass the IDD a string containing a query in the native language of the underlying data source. For example, the JDBC driver's native query function expects its string parameter to contain an SQL query. The name that K2 uses for this function in the query environment is determined by the contents of the driver properties file.
The communication between the execution engine and the IDD is handled through DriverConnectionA's default implementation of its getNativeDriverFn method, which returns a K2.absyn.expns.absynNativeA object that, when applied, returns an K2.absyn.expns.absynDriverQuery that points back to your connection class. You don't need to be concerned with these details, unless you plan to override the default implementation of getNativeDriverFn. For most purposes, this is not necessary.
When constructing the absynNativeA, the return type of the function is determined by calling the getNativeQueryResultType method in your connection class with an empty string. To support its native query function, your connection class must implement both this method and the executeNativeQuery method. More details on this are provided later.
Once you've decided what kinds of entry points you want to support, you must make your IDD connect to the data source.
[Tech Docs Index]