Creating a Logical Data Source

As part of the database access configuration information to be provided to Canvas framework, following key information is sought –

Config Key	M / O	Type	Purpose
Category: Data Source Configurations
PROVIDER_URL	M	HOST:PORT	This is the provider URL that should be used for JNDI lookup for DataSource. This is for backward compatibility for scenarios where Connection is still retrieved using Data Source lookup.
JNDI_FACTORY	M	Class Name	This is the JNDI factory that should be used for JNDI Lookup. This value is specific to the Application or Web container within which the application is loaded.
CT_FW_IBATIS_DATASOURCE_KEY	M	String	This is the alias name for the logical data source as defined by CT Database library for the Framework itself. This is useful to ensure that there is no conflict between the Framework's internal query model with that of the model defined by the end application.
CT_FW_DATASOURCE	M	String	This is the JNDI name of the data source that is configured for the Canvas Framework. This could be same or different from the one targeted for the application.
CT_FW_DATABASE_VENDOR	M	String	One of the following values: oracle mssql This is used for switching the underlying database for Oracle or Microsoft SQL Server where the users and objects related to Canvas framework are created.
CT_IBATIS_DATASOURCE_KEYS	M	Comma separated String	This key provides the list of Logical data sources that the application wishes to use. Care should be taken that this list does not include the Data Source name provided under the key CT_FW_IBATIS_DATASOURCE_KEY.
<Data Source>_DSXML	M	Resource Path	For every data source configured under CT_IBATIS_DATASOURCE_KEYS, it is expected that the iBatis configuration XML that corresponds to this Logical data source is pointed out here.
CT_DEFAULT_IBATIS_DATASOURCE_KEY	M	String	This is the Logical data source that should be taken as the default by the framework whenever a developer tries to execute a Database request without explicitly providing the Logical Data Source. This should be one of the data sources defined under the key CT_IBATIS_DATASOURCE_KEYS.

The typical structure of the Logical Data Source configuration XML is as follows. More detailed configuration options for the Logical Data Source can be found in the iBatis documentation references provided earlier.

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE sqlMapConfig      
    PUBLIC "-//ibatis.apache.org//DTD SQL Map Config 2.0//EN"      
    "http://ibatis.apache.org/dtd/sql-map-config-2.dtd">

<sqlMapConfig>
	<properties resource="myenvironment.properties" />
	<transactionManager type="EXTERNAL">
		<property name="SetAutoCommitAllowed" value="false"/>
		<dataSource type="JNDI">
			<property name="DataSource" value="${MY_DATASOURCE}"/>
		</dataSource>
	</transactionManager>
	<!-- Default_SqlMap.xml file import should be at the top of all xmls, because this file will handle the app's filtering and pagination -->
	<sqlMap resource="com/intellectdesign/canvas/database/ibatis/${CT_DATABASE_VENDOR}/maps/viewdefn/Default_SqlMap.xml"/>
	<sqlMap resource="maps/grid/myWidgetView_SqlMap.xml"/>
	<sqlMap resource="maps/calendar/myCalendarView_SqlMap.xml"/>
</sqlMapConfig>

A few key items are yellow highlighted in the sample configuration:

It is possible to dynamically inject values into the configuration XML based on a property file. In this example, myenvironment.properties is a property file that belongs to the end application having 2 keys MY_DATASOURCE and MH_VENDOR that corresponds to the JNDI name and the Database vendor configured for the framework.
iBatis uses ANT style place holders for placing dynamic content referenced from the property file attached. The typical construct is ${place holder}. Hence to use MY_DATASOURCE as a placeholder, refer it as ${MY_DATASOURCE}.
The key expectation from a Logical Data Source configuration is to include the Framework provided SQL Map as the first map. This SQL map provides standard placeholders, conventions or patterns that need to be used for functionality like runtime filtering, sorting, paging, etc. This is typically in the resource path -

com/intellectdesign/canvas/database/ibatis/${CT_DATABASE_VENDOR}/maps/viewdefn/Default_SqlMap.xml

The placeholder CT_DATABASE_VENDOR is a default placeholder that is made available for the Logical Data Source to be use. This corresponds to the configuration provided under the CT_FW_DATABASE_VENDOR key as part of the Canvas Initialization configuration.

View the following pages