rsh-dal-config

This section deals with the rsh-dal-config components. The rsh-dal-config module was designed to make the configuration tasks for 95% of the applications that use rsh-dal extremely simple and difficult to misconfigure.

In a nutshell, rsh-dal-config is a ConfigurationSource implementation. Based on the small number of settings you set for the rsh-dal-config, the rsh-dal-config then sets up a larger number of properties to support all the components and frameworks used by rsh-dal. For more details for the settings generated by rsh-dal-config and how it works with rsh-dal, see the rsh-dal Configuration page.

Typical Setup

The rsh-dal-config is a plugin to the rsh-config package. As such, it uses the same conventions--mainly that your application is driven by a config file named "YOURAPP_config.properties" in the root of your classpath or in the local directory your app is executing from. The [YOURAPP] portion is the name of your application. It can be anything you want it to (but it shouldn't include spaces or weird formatting characters).

Say your application is called "foobar". You would then have a file named "foobar_config.properties" in the root of your classpath (either include it in a directory in the classpath or put it in the root of one of the jars on the classpath). In your "foobar_config.properties" file, you would then have the following:

config.source.1.dal.type = com.redstarhackers.dal.config.DALConfigurationSource
config.source.1.dal.datastoreid = foobar
config.source.1.dal.driver=com.mysql.jdbc.Driver
config.source.1.dal.uri=jdbc:mysql://localhost/foobar
config.source.1.dal.username=test
config.source.1.dal.password=test
config.source.1.dal.datasource=java:comp/env/jdbc/FoobarDataSource
# and, if you are using rsh-dal-hibernate3 
# with this datastore, include this ...
config.source.1.dal.usinghibernate3=true

Please note that the "config.source.1" is a part of the rsh-config's approach to defining multiple configuration sources. The "config.source." is required, and the number represents the order to load the configuration sources in (never use 0, that should be reserved for the system environment configuration source).

The "dal" portion of "config.source.1.dal.*" is a name for this ConfigurationSource. You can name this anything you want. We recommend "dal" because it makes sense and ties it to the rsh-dal components when others look at the configuration.

The "config.source.1.dal.type" is a special setting that tells the rsh-config framework what ConfigurationSource implementation to use. You will always use com.redstarhackers.dal.config.DALConfigurationSource.

The rest of the property names represent the properties supported by rsh-dal-config. Using these properties, the DALConfigurationSource generates a set of properties that properly loads and binds the rsh-dal components.

*.datastoreid=[SOMEID]
The datastoreid is how your identify this particular datastore in the framework. This setting is needed so that you can have multiple datastores within one application (most apps have only one, but that is why this setting exists).

*.driver=com.some.Driver
This is the fully-qualified JDBC Driver class name. This is needed for the DriverManager connections (that is, for making connections where no DataSource exists).

*.uri=jdbc:dbvendor://localhost/foobar
The JDBC connection URI. This is the standard JDBC DriverManager connection URI (used in the getConnection() call). Needed for making connections where no DataSource exists. The actual value for this setting depends on what database you are connecting to and with what driver. You can also add additional settings per the JDBC database URL spec.

*.username=foobar
The JDBC connection username. This is the standard JDBC DriverManager username/userid value (used in the getConnection() call). Needed for making connections where no DataSource exists.

*.password=foopass
The JDBC connection password. This is the standard JDBC DriverManager password (used in the getConnection() call). Needed for making connections where no DataSource exists.

*.datasource=java:comp/env/jdbc/FoobarDataSource
The DataSource JNDI name. This allows the rsh-dal package to connect via a DataSource (when available). The actual value of the JNDI name depends on your platform and setup.

*.usinghibernate3=true
Whether or not Hibernate3 should be used with this datastore. If you are not using Hibernate, do not include this setting or set it to false.

Using the Configuration

So, if you have something like the above setup, the important parts to remember when trying to use it are the following:

• Your application name. In the above configuration, your app was named foobar, so you put your configuration information in the "foobar_config.properties" file (which can be found in the root of your classpath).
• What strategy you want to use. Currently the rsh-dal-config supports the JDBC and Hibernate3 data access strategies. If you want to use Hibernate3, be sure you set "usinghibernate3=true".

With that information, you just need to make the call to the DAS manager:

DataAccessStrategy das = DataAccessStrategyManager.getStrategy("foobar", 
    DALConfigurationConstants.JDBC_DAS_NAME);

If you wanted to use the Hibernate3 strategy, you would make this call instead:

DataAccessStrategy das = DataAccessStrategyManager.getStrategy("foobar", 
    DALConfigurationConstants.HIBERNATE3_DAS_NAME);

The string "foobar" tells the DAS manager to use the configuration for the application "foobar" (that is, to look for the config for foobar using rsh-config, which is in the file "foobar_config.properties"). The constant tells it which strategy to use, and the values of these constants are used by the rhs-dal-config plugin. You are guaranteed to find a strategy so long as you use those constants.

It is highly recommended that you consider writing a wrapper for the DAS manager. The wrapper will help you hide configuration details and prevent typos.