The Carbon SQL Module

Purpose

The Connection Service is designed to simplify retrieving jdbc connections for use in an application.

Connections can either be retrieved in 2 modes. The first mode creates a new connection to the database everytime the user requests. This is implemented using the Standalone Connection Factory. The second mode retrieves connection from a configured data source. This is implemented in the Named Data Source Connection Factory. More details about these factories will be covered in the subsequent sections.

Introduction

This section introduces the 2 connection factories supplied

StandaloneConnectionFactory: This connection factory creates a new connection to the database every time a user requests a connection. Since this factory uses the simplest interfaces declared in jdbc specification, any jdbc compliant driver can be used with this connection factory. Since a new connection is created on every call there is a penalty involved in using this connection factory. We recommend that this implementation be used only in the simplest applications.

NamedDataSourceConnectionFactory: JDBC 2.0 introduced the concept of datasources. "A DataSource object is a factory for Connection objects. An object that implements the DataSource interface will typically be registered with a JNDI service provider." The NamedDataSourceConnectionFactory retrieves connections from a configured data source which has been registered in a jndi tree (e.g. ldap) Since a datasource typically pool connections, it has a better performance in comparision with the StandaloneConnectionFactory, since the overhead of creating a new connection with every call isnt present.

Standalone Connection Factory Component Configuration

This section explains the configuration of a standalone connection factory. The significance of the attributes in the configuration document has been explained thouroughly in the java docs for StandaloneConnectionFactoryConfiguration

    <Configuration  ConfigurationInterface="org.sape.carbon.services.sql.connection.StandaloneConnectionFactoryConfiguration">

         <FunctionalInterface>org.sape.carbon.services.sql.connection.ConnectionFactory</FunctionalInterface>
         <FunctionalImplementationClass>org.sape.carbon.services.sql.connection.StandaloneConnectionFactory</FunctionalImplementationClass>

         <!-- DriverClass: e.g.  -->
         <DriverClass>oracle.jdbc.driver.OracleDriver</DriverClass>

         <!-- DbUrl: e.g. -->
         <DbUrl>jdbc:oracle:thin:@maggie:1521:dev</DbUrl>

         <!-- DbUserId: e.g. "scott" -->
         <DbUserId>scott</DbUserId>

         <!-- DbPassword: e.g. "tiger" -->
         <DbPassword>tiger</DbPassword>

    </Configuration>
    

Since Carbon 2.1 the standalone connection factory can also accept a additional set of properties to configure the retrieved connection. This is helpful when you need to specify additional parameters to configure the connection. Stand alone connection factory accepts a map of name, value pairs and passes it on to the DriverManager to configure the connection.

    <Configuration  ConfigurationInterface="org.sape.carbon.services.sql.connection.StandaloneConnectionFactoryConfiguration">

         <FunctionalInterface>org.sape.carbon.services.sql.connection.ConnectionFactory</FunctionalInterface>
         <FunctionalImplementationClass>org.sape.carbon.services.sql.connection.StandaloneConnectionFactory</FunctionalImplementationClass>

         <!-- DriverClass: e.g.  -->
         <DriverClass>oracle.jdbc.driver.OracleDriver</DriverClass>

         <!-- DbUrl: e.g. -->
         <DbUrl>jdbc:oracle:thin:@maggie:1521:dev</DbUrl>

         <!-- DbUserId: e.g. "scott" -->
         <DbUserId>scott</DbUserId>

         <!-- DbPassword: e.g. "tiger" -->
         <DbPassword>tiger</DbPassword>

         <!-- additional properties for the connection -->
         <ConnectionPropertiesMap>
            <ConnectionProperties Key="rowPrefetch">100</ConnectionProperties>
         </ConnectionPropertiesMap>

    </Configuration>
    

Named Data Source Connection Factory Component Configuration

This section explains the configuration of a named data source connection factory. The significance of the attributes in the configuration document has been explained thouroughly in the java docs for NamedDataSourceConnectionFactoryConfiguration To use the named data source connection factory you need to follow the following steps

1. configure the data source : This is a application server dependent steps. Information on how a data source can be configured for your application server can be located in the product documentation
2. bind the data source to a jndi tree: This again is a environment dependent step. Generally the jndi name for the data source is specified in the data source configuration step. You need to refer to the product documentation for specific details
3. Configure the carbon named data source connection factory : The configuration of a named data source connection factory is explained further in this section

    <Configuration  ConfigurationInterface="org.sape.carbon.services.sql.connection.NamedDataSourceConnectionFactoryConfiguration">

         <FunctionalInterface>org.sape.carbon.services.sql.connection.DataSourceConnectionFactory</FunctionalInterface>
         <FunctionalImplementationClass>org.sape.carbon.services.sql.connection.NamedDataSourceConnectionFactory</FunctionalImplementationClass>

         <!-- JNDI Location: e.g. "java:comp/env/jdbc/EstoreDataSource" -->
         <JndiName>java:comp/env/jdbc/MyDataSource</JndiName>

         <!-- JNDI InitialContextFactory: e.g."weblogic.jndi.WLInitialContextFactory"  -->
         <InitialContextFactory>weblogic.jndi.WLInitialContextFactory</InitialContextFactory>

         <!-- JNDI ProviderUrl: e.g. "t3://localhost:7001" -->
         <ProviderUrl>t3://localhost:7001</ProviderUrl>

         <!-- JNDI UserId  -->
         <JndiUserId>__jndiuser__</JndiUserId>

         <!-- JNDI Password -->
         <JndiPassword>__jndipassword__</JndiPassword>

         <!-- DataSource UserId  (optional) used to override the default user id configured for the data store-->
         <DataSourceUserId>__datasourceuser__</DataSourceUserId>

         <!-- DataSource Password (optional) used to override the default password configured for the data store -->
         <DataSourcePassword>__datasourcepassword__</DataSourcePassword>

    </Configuration>
    

Deployment Service

The deployment service can be used to effectively manage individual configurations of all the developers. Please refer to the deployment service documentation for more details

    e.g. instead of specifying the DbUrl as 
         <DbUrl>jdbc:oracle:thin:@maggie:1521:dev</DbUrl>
    it can be specified as 
         <DbUrl>{/deployment/CurrentDeployment$DbUrl}</DbUrl>
    

Choice of connection factory

Choose an appropriate implementation of the connection factory. We recommend use of the named data source connection factory. NamedDataSourceConnectionFactory doesnt have some of the limitations of a StandaloneConnectionFactory and better performing. Use of StandaloneConnectionFactory should be an exception.