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
<?xml version="1.0" encoding="utf-8" ?>
<settings>
<add key="username" value="albert" />
</settings>
then all elements in the DataMapper configuration can use the variable
${username} to insert the value "albert". For example:
<provider ConnectionString="mysql://${username}:..." ... />
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:
<properties>
<property resource="myProperties.config"/>
<property resource="anotherProperties.config"/>
<property key="host" value="ibatis.com" />
</properties>
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.
<typeHandler type="date" callback="TDateTimeHandler"/>
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.
<!-- The ${properties} are defined in an external file, -->
<!-- but the values could also be coded inline. -->
<!-- Connecting to a MySQL database -->
<provider class="TAdodbProvider" >
<datasource
ConnectionString="mysql://${username}:${password}@${host}/${database}" />
</provider>
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.
<!-- Relative path from the directory of the
current file using a property variable -->
<sqlMap resource="${root}/Maps/Account.xml"/>
<sqlMap resource="${root}/Maps/Category.xml"/>
<sqlMap resource="${root}/Maps/Product.xml"/>
<!-- Full file path with a property variable -->
<sqlMap resource="/${projectdir}/MyApp/Maps/Account.xml"/>
<sqlMap resource="/${projectdir}/MyApp/Maps/Category.xml"/>
<sqlMap resource="/${projectdir}/MyApp/Maps/Product.xml"/>
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).