Implement DAO externalized statement loading based on runtime Mode

2 files changed, 49 insertions, 2 deletions

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}