DataMapper Configuration Elements

Sometimes the values we use in an XML configuration file occur in more than one element. Often, there are values that change when we move the application from one server to another. To help you manage configuration values, you can specify a standard properties file (with name=value entries) as part of a DataMapper configuration. Each named value in the properties file becomes a shell variable that can be used in the DataMapper configuration file and your Data Map definition files.

<properties> attributes

The <properties> element can accept one resource attribute to specify the location of the properties file.

Attribute Description
resource Specify the properties file to be loaded from the directory relative to the current file. Example: resource="properties.config"

For example, if the "properties.config" file contains

then all elements in the DataMapper configuration can use the variable ${username} to insert the value "albert". For example:

Tip: Properties are handy during building, testing, and deployment by making it easy to reconfigure your application for multiple environments.

<property> element and attributes

You can also specify more than one properties file or add property keys and values directly into your SqlMap.config file by using <property> elements.

Attribute Description
resource Specify the properties file to be loaded from the directory relative to the current file. Example: resource="properties.config"
key Defines a property key (variable) name. Example: key="username"
value Defines a value that will be used by the DataMapper in place of the the specified property key/variable. Example: value="mydbuser"

For example:

The <typeHandler> Element

The <typeHandler> element allows for the configuration and use of a Custom Type Handler (see the Custom Type Handler section). This extends the DataMapper's capabilities in handling types that are specific to your database provider, are not handled by your database provider, or just happen to be a part of your application design.

The <typeHandler> element has three attributes:

Attribute Description
type Refers to the name of the type to handle. Example: type="date"
dbType Indicates the provider dbType to handle. Example: dbType="Varchar2"
callback The custom type handler class name. Example: callback="TDateTimeHandler"

The <provider> element and attribute

The <provider> element encloses a <datasource> that configure the database system for use by the framework.

Attribute Description
class The database provider class that extends TDatabaseProvider. Example: class="TAdodbProvider"

The <datasource> element and attributes

The <datasource> element specifies the connection string. The following example shows a <datasource> element for a MySql connection.

Attribute Description
connectionString Data Source Name (DSN) connection string. Example: connectionString="mysql://root:pwd@localhost/mydb"
driver Database driver name (mysql, sqlite, etc.). Example: driver="mysql"
host DB host name/IP (and port number) in the format host[:port]. Example: host="localhost"
username Database connection username.
password Database connection password.
database Database name to use in the connection.
Tip: Use Data Source Name (DSN) connection string or specify the necessary individual connection parameters.

The <sqlMap> Element

On a daily basis, most of your work will be with the Data Maps, which are covered in Working with Data Maps. The Data Maps define the actual SQL statements or stored procedures used by your application. The parameter and result objects are also defined as part of the Data Map. As your application grows, you may have several varieties of Data Map. To help you keep your Data Maps organized, you can create any number of Data Map definition files and incorporate them by reference in the DataMapper configuration. All of the definition files used by a DataMapper instance must be listed in the configuration file.

The following example shows <sqlMap> elements for loading a set of Data Map definitions.
Tip: Since the application root directory location differs by project type (Windows, Web, or library), it is best to use a properties variable to indicate the relative path when using the <sqlMap> resource attribute. Having a variable defined in a properties file makes it easy to change the path to all your Data Mapper configuration resources in one location (note the ${projectdir} and ${root} variables in the example above).