From a6df2de41953e10db1527e54acd734c0f0a1fa28 Mon Sep 17 00:00:00 2001
From: James Moger <james.moger@gitblit.com>
Date: Mon, 10 Nov 2014 11:59:09 -0500
Subject: Implement DAO externalized statement loading based on runtime Mode

---
 src/site/dao.mkd   | 43 +++++++++++++++++++++++++++++++++++++++++++
 src/site/index.mkd |  8 ++++++--
 2 files changed, 49 insertions(+), 2 deletions(-)

(limited to 'src/site')

diff --git a/src/site/dao.mkd b/src/site/dao.mkd
index 660c7af..491d085 100644
--- a/src/site/dao.mkd
+++ b/src/site/dao.mkd
@@ -135,3 +135,46 @@ public interface MyDao extends Dao {
 }
 ---JAVA---
 
+### Runtime Mode & External Statements
+
+Sometimes you may need to specify a slightly different SQL statement for a database engine you might be using in development but not in production.  For example, you might develop with H2 and deploy with PostgreSQL.
+
+Being able to switch the DAO statements executed based on the runtime mode would be helpful for some scenarios.  Iciql supports this use-case with a `DaoStatementProvider` and provides three mode options: `DEV`, `TEST`, and `PROD`.
+
+#### External Statement DAO Example
+---JAVA---
+public interface MyDao extends Dao {
+    @SqlQuery("some.query")
+    Product [] getProductsWithRuntimeModeDependentQuery();
+}
+
+Db db = Db.open("jdbc:h2:mem:iciql");
+// set a classpath statement resource provider
+db.setDaoStatementProvider(new DaoClasspathStatementProvider());
+
+// open the dao and retrieve the products
+MyDao dao = db.open(MyDao.class);
+Product [] products = dao.getProductsWithRuntimeModeDependentQuery();
+---JAVA---
+
+#### External Statement Resource Example
+
+---FIXED---
+some.query = select * from Products                                       # default statement
+%prod.some.query = select * from Products                                 # will be used in PROD mode
+%test.some.query = select * from Products where category = 'Beverages'    # will be used in TEST mode
+%dev.some.query = select * from Products where category = 'Condiments'    # will be used in DEV mode
+---FIXED---
+
+#### DaoClasspathStatementProvider
+
+Iciql ships with one useful implementation of a DaoStatementProvider: `DaoClasspathStatementProvider`.
+
+This provider will load a single external statement resource from the classpath, if found. It tries to locate one of the following classpath resources and loads the first one identified using the `java.util.Properties` class.
+
+1. `/iciql.properties`
+2. `/iciql.xml`
+3. `/conf/iciql.properties`
+4. `/conf/iciql.xml`
+
+Every `@SqlQuery` and `@SqlStatement` method will ask the `DaoStatementProvider` for the statement to execute based on the annotation value and the runtime mode.  For the `DaoClasspathStatementProvider`, if the annotation value is not a key in the resource file it is assumed to be a statement and is returned to the DAO object for execution.  This allows you to externalize a handful of statements - or all of them if you do not want to hard-code anything.
\ No newline at end of file
diff --git a/src/site/index.mkd b/src/site/index.mkd
index b9fc549..1c742f6 100644
--- a/src/site/index.mkd
+++ b/src/site/index.mkd
@@ -5,7 +5,7 @@ iciql **is**...
 - a model-based, database access wrapper for JDBC
 - for modest database schemas and basic statement generation
 - for those who want to write code, instead of SQL, using IDE completion and compile-time type-safety
-- small (225KB) with debug symbols and no runtime dependencies
+- small (<250KB) with debug symbols and no runtime dependencies
 - pronounced *icicle* (although it could be French: *ici ql* - here query language)
 - a friendly fork of the H2 [JaQu][jaqu] subproject
 
@@ -66,7 +66,7 @@ public interface MyDao extends Dao {
 @TypeAdapter(InvoiceAdapterImpl.class)
 public @interface InvoiceAdapter { }
 
-// Crate a DAO instance with your Db and work more clearly
+// Create a DAO instance with your Db and work more clearly
 try (Db db = Db.open("jdbc:h2:mem:iciql")) {
 
     MyDao dao = db.open(MyDao.class);
@@ -91,6 +91,10 @@ This is very useful for mapping your field domain models to SQL without having t
 
 You might use this to take advantage of the underlying database's type system.  For example, PostgreSQL ships with the compelling JSON/JSONB/XML data types.  Iciql provides String and Object adapters to facilitate use of those data types.
 
+### runtime mode support
+
+Mode support allows you to tweak the behavior of your `@TypeAdapter` and `DAO` implementations to adapt to runtime conditions such as developing on a different database than you deploy on.
+
 ### Supported Databases (Unit-Tested)
 - [H2](http://h2database.com) ${h2.version}
 - [HSQLDB](http://hsqldb.org) ${hsqldb.version}
-- 
cgit v1.2.3