If you need access to more than one database from the same application, create a DataMapper configuration file for that database and another Mapper class to go with it. In the new Mapper class, change the call to ConfigureAndWatch to

[C#]
ISqlMapper mapper = builder.ConfigureAndWatch("anotherSqlMapConfig.config", handler);

and substitute the name of your configuration file. Each database then has their own singleton you can call from your application:

[C#]
ISqlMapper sqlServer = SqlServerMapper.Get();
ISqlMapper access = AccessMapper.Get();

iBATIS offers you a plethora of other options for loading your SqlMap.config file such as loading it through a Stream, Uri, FileInfo, or XmlDocument instance. All of these methods are available through the DomSqlMapBuilder API for creating a SqlMapper instance.

As seen in the prior section, the basic DomSqlMapBuilder.Configure() call will look for a file named SqlMap.config in your application's root directory. This directory's location differs by project type but is normally the directory where you place your web.config or app.config file.

ISqlMapper mapper = builder.Configure();

If you have named your configuration file something other than SqlMap.config or if you have located your configuration file in a directory other than the application root directory, you can also pass in a relative or absolute file path to the Configure method.

/* Configure a SqlMapper from a file path.
   Uses a relative resource path from your application root 
   or an absolute file path such as "file:\\c:\dir\a.config" */
ISqlMapper mapper = builder.Configure(strPath);

	Tip
	Since the application root directory location differs by project type (Windows, Web, or library), you can use an AppSettings key for defining a relative path to your SqlMap.config file. Having this key defined makes it easy to change the path without having to recompile your code: mapper = builder.Configure( ConfigurationSettings.AppSettings["rootPath"]+"SqlMap.config");

Aside from using a simple string filepath, you can also pass in a FileInfo or Uri instance for the DomSqlMapBuilder to use in locating your SqlMap.config file.

/* Configure a SqlMapper with FileInfo. */
FileInfo aFileInfo = someSupportClass.GetDynamicFileInfo();
ISqlMapper mapper = builder.Configure(aFileInfo);

/* Configure a SqlMapper through a Uri. */
Uri aUri = someSupportClass.GetDynamicUri();
ISqlMapper anotherMapper = builder.Configure(aUri);

If you find that you already have loaded your DataMapper configuration information as an XmlDocument or Stream instance within your application, the DomSqlMapBuilder provides Configure overloads for those types as well.

/* Configure a SqlMapper with an XmlDocument */
XmlDocument anXmlDoc = someSupportClass.GetDynamicXmlDocument();
ISqlMapper mapper = builder.Configure(anXmlDoc);

/* Configure a SqlMapper from a stream. */
Stream aStream = someSupportClass.GetDynamicStream();
ISqlMapper anotherMapper = builder.Configure(aStream);

The DomSqlMapBuilder API provides ConfigureAndWatch methods that can be used to monitor changes to the configuration files. This is particularly useful when using a singleton such as the Mapper class shown in the prior section. The example Mapper singleton allows a reconfigured SqlMapper instance to be reloaded on the fly.

...
  protected static void Configure (object obj)
  {
   _mapper = null;
  }

  protected static void InitMapper()
  {
   ConfigureHandler handler = new ConfigureHandler(Configure);
   DomSqlMapBuilder builder = new DomSqlMapBuilder();
   _mapper = builder.ConfigureAndWatch(handler);
  }
...

If you use a custom singleton, you will need to pass a ConfigureHandler (callback delegate) to the DomSqlMapBuilder so that it knows the method for resetting your application's SqlMapper instance. In the Mapper's case, its Configure method is used as the callback delegate.

Since the configuration files need to be watched for changes, your SqlMap.config file must be accessible through the file system. This means that configuration is limited to the three methods shown below.

/* Configure and monitor the configuration file for modifications 
   and automatically reconfigure the SqlMapper. 
   This basic ConfigureAndWatch method looks for a file with the 
   default name of SqlMap.config in the application root directory. */
public ISqlMapper ConfigureAndWatch(ConfigureHandler configureDelegate)

/* Configure and monitor the configuration file for modifications 
   and automatically reconfigure the SqlMapper. 
   Uses a relative path from your application root 
   or an absolute file path such as "file:\\c:\dir\a.config" */
public ISqlMapper ConfigureAndWatch( string resource, ConfigureHandler configureDelegate )

/* Configure and monitor the configuration file for modifications 
   and automatically reconfigure the SqlMapper. 
   Uses a FileInfo instance for your config file. */
public ISqlMapper ConfigureAndWatch( FileInfo resource, ConfigureHandler configureDelegate )

Before launching the 'Configure' method to build the ISqlMapper instance, you can set those porperties.

NameValueCollection properties = new NameValueCollection();
properties.Add("connectionString", "...");
builder.Properties = properties;

ISqlMapper mapper = builder.Configure("sqlMap.config");

public object Insert(string statementName,
                     object parameterObject);
public int Update(string statementName,
                  object parameterObject);
public int Delete(string statementName,
                  object parameterObject);

If a Mapped Statement uses one of the <insert>, <update>, or <delete> statement-types, then it should use the corresponding API method. The <insert> element supports a nested <selectKey> element for generating primary keys (see Section 3.3.3). If the <selectKey> stanza is used, then Insert returns the generated key; otherwise a null object is returned. Both the Update and Delete methods return the number of rows affected by the statement.

public object QueryForObject(string statementName,
                             object parameterObject);
public object QueryForObject(string statementName, 
                             object parameterObject,
                             object resultObject);

public T QueryForObject<T>(string statementName, object parameterObject);
public T QueryForObject<T>(string statementName, object parameterObject, T resultObject);

If a Mapped Statement is expected to select a single row, then call it using QueryForObject. Since the Mapped Statement definition specifies the result class expected, the framework can both create and populate the result class for you. Alternatively, if you need to manage the result object yourself, say because it is being populated by more than one statement, you can use the alternate form and pass your resultObject as the third parameter.

public IList QueryForList(string statementName,
                          object parameterObject);
public void QueryForList(string statementName,
                         object parameterObject,
                         IList resultObject);
public IList QueryForList(string statementName,
                          object parameterObject,
                          int skipResults,
                          int maxResults);

public IList<T> QueryForList<T>(string statementName, object parameterObject);
public void QueryForList<T>(string statementName, 
                                  object parameterObject, 
								  IList<T> resultObject);
public IList<T> QueryForList<T>(string statementName, 
                                            object parameterObject,
                                            int skipResults, int maxResults);						  
						  

If a Mapped Statement is expected to select multiple rows, then call it using QueryForList . Each entry in the list will be an result object populated from the corresponding row of the query result. If you need to manage the resultObject yourself, then it can be passed as the third parameter.

If you need to obtain a partial result, the third form takes the number of records to skip (the starting point) and the maximum number to return, as the skipResults and maxResults parameters. The PaginatedList method provides the same functionality but in a more convenient wrapper.

The QueryWithRowDelegate method also works with multiple rows, but provides a post-processing feature.

public delegate void RowDelegate(object obj,
                                 IList list);

public IList QueryWithRowDelegate(string statementName,
                                  object parameterObject, 
                                  RowDelegate rowDelegate);

public IList<T> QueryWithRowDelegate<T>(string statementName, object parameterObject, 
                                SqlMapper.RowDelegate<T> rowDelegate);								  
								  

No matter how well our database is designed or how cleverly we describe our maps, the result objects we get back may not be ideal. You may need to perform some post-processing task on the result objects. You might even want to omit an entry omitted from the list. Or, you might want to use the result object to create some other, more useful object. To save filtering the result objects from to one list to another, you can pass a RowDelegate to the method to do the dirty work. The SqlMapper will go through each of the result objects and give the delegate a chance to modify the object and determine if the object should be added to the IList that will be returned.

	Important
	It is your responsibility to add the objects you want returned to the list. If an object is not added, it is not returned.

public delegate void DictionaryRowDelegate(object key, 
                                           object value, 
                                           object parameterObject, 
                                           IDictionary dictionary);

public IDictionary QueryForMapWithRowDelegate(string statementName,
                                              object parameterObject, 
                                              string keyProperty, 
                                              string valueProperty, 
                                              DictionaryRowDelegate rowDelegate);

No matter how well our database is designed or how cleverly we describe our maps, the result objects we get back may not be ideal. You may need to perform some post-processing task on the result objects. You might even want to omit an entry omitted from the dictionary. Or, you might want to use the result object to create some other, more useful object. To save filtering the result objects from to one dictionary to another, you can pass a DictionaryRowDelegate to the method to do the dirty work. The SqlMapper will go through each of the result objects and give the delegate a chance to modify the object and determine if the object should be added to the IDictionary that will be returned.

	Important
	It is your responsibility to add the objects you want returned to the dictionary. If an object is not added, it is not returned.

	Note
	The method PaginatedList has been made as obsolete and will not be supported in future version.

public PaginatedList QueryForPaginatedList(string statementName,
                                           object parameterObject,
                                           int pageSize);

We live in an age of information overflow. A database query often returns more hits than users want to see at once, and our requirements may say that we need to offer a long list of results a "page" at a time. If the query returns 1000 hits, we might need to present the hits to the user in sets of fifty, and let them move back and forth between the sets. Since this is such a common requirement, the framework provides a convenience method.

The PaginatedList interface includes methods for navigating through pages (nextPage(), previousPage(), gotoPage()) and also checking the status of the page (isFirstPage(), isMiddlePage(), isLastPage(), isNextPageAvailable(), isPreviousPageAvailable(), getPageIndex(), getPageSize()). Although the total number of records available is not accessible from the PaginatedList interface, this should be easily accomplished by simply executing a second statement that counts the expected results. Too much overhead would be associated with the PaginatedList otherwise.

Tip

The PaginatedList method is convenient, but note that a larger set will first be returned by the database provider and the smaller set extracted by the framework. The higher the page, the larger set that will be returned and thrown away. For very large sets, you may want to use a stored procedure or your own query that uses skipResults and maxResults as parameters. Unfortunately, the semantics for the returning partial data sets is not standardized, so PaginatedList is the best we can do within the scope of a framework.

public IDictionary QueryForDictionary(string statementName,
                                      object parameterObject,
                                      string keyProperty)
public IDictionary<K, V> QueryForDictionary<K, V>(string statementName, 
                                      object parameterObject, 
                                      string keyProperty);
public IDictionary QueryForDictionary(string statementName,
                                      object parameterObject,
                                      string keyProperty,
                                      string valueProperty)
public IDictionary<K, V> QueryForDictionary<K, V>(string statementName, 
                                     object parameterObject, 
                                      string keyProperty, 
									  string valueProperty);

public IDictionary QueryForMap(string statementName,
                               object parameterObject, 
                               string keyProperty)
public IDictionary QueryForMap(string statementName, 
                               object parameterObject, 
                               string keyProperty, 
                               string valueProperty)

The QueryForList methods return the result objects within a IList instance. Alternatively, the QueryForDictionary returns a IDictionary instance. The value of each entry is one of the result objects. The key to each entry is indicated by the keyProperty parameter. This is the name of the one of the properties of the result object, the value of which is used as the key for each entry. For example, If you needed a set of Employee objects, you might want them returned as a IDictionary keyed by each object's EmployeeNumber property.

If you don't need the entire result object in your Dictionary, you can add the valueProperty parameter to indicate which result object property should be the value of an entry. For example, you might just want the EmployeeName keyed by EmployeeNumber.

Important

You do not need to use this method just to obtain an IDictionary result object. As explained in Section 3.5, the result object for any query can be a property object or a IDictionary instance. This method is used to generate a new IDictionary result object from a property object or (another) IDictionary object. In this case, the key is a property you specify, and the value is the row from the result set.

The QueryforMap methods provide the same functionality but under a different name, for the sake of consistency with the Java implementation. (The .NET IDictionary interface is equivalent to the Java Map interface.)