Commits

Shantanu Kumar committed 2174e41

bump version to 0.1

Comments (0)

Files changed (3)

 # Changes and TODO
 
 
-## 0.1 / 2011-Feb-??
+## 0.1 / 2011-Mar-06
 
 * Clojure 1.3 compatibility
 * Dynamic var for dbspec containing the following keys
   * :datasource
   * :connection
   * :dbmetadata
+  * :catalog
+  * :schema
+  * :show-sql
   * :clj-to-db
   * :db-to-clj
 * Function to build Connection from supplied parameters
 * Macro to extract Connection from DataSource and execute body in context
 * Convenience function for converting Clojure to database name
 * Convenience function for converting database to Clojure name
-* Alternative function for clojure.core/resultset-seq: alt-resultset-seq
-* [TODO] Schema/tables/columns discovery functions
+* Alternative function for clojure.core/resultset-seq: row-seq
+* Schema/tables/columns discovery functions
 -*- markdown -*-
 
-# Clj-DBSpec v0.1-SNAPSHOT
+# Clj-DBSpec v0.1
 
 Clj-DBSpec is a common configuration spec for dealing with relational databases
 e.g. data source, connection, conversion of schema/tables/columns/indices names
 
 ## License
 
-Copyright (C) 2010 Shantanu Kumar (kumar.shantanu at gmail dot com)
+Copyright (C) 2011 Shantanu Kumar (kumar.shantanu at gmail dot com)
 
-Distributed under the Apache 2 License.
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this software except in compliance with the License.
+   You may obtain a copy of the License at
 
+   [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
 
-# Tutorial
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+
+# Documentation
 
 Clj-DBSpec can be used after including the following in your
 namespace:
 Feel free to browse the documentation and source code/unit tests for details.
 
 
-## Dynamic var for java.sql.Connection object
+## Quickstart
 
-    spec/*connection*
+### Dynamic var for database configuration keys
 
+    spec/*dbspec*
 
-## Dynamic var for javax.sql.DataSource object
+This var is bound to a map containing well known keys and corresponding values.
+Those keys are:
 
-    spec/*datasource*
+    :datasource  (javax.sql.DataSource, default: nil)
+                  1. When you rebind this var with :datasource you SHOULD also
+                     include a cached :dbmetadata value.
+                  2. Everytime a connection is taken from the datasource you
+                     SHOULD re-bind this var to include the :connection object.
+    :connection  (java.sql.Connection, default: nil)
+                  1. If the connection is not taken from a datasource you SHOULD
+                     include a cached :dbmetadata value while re-binding.
+    :dbmetadata  (map, default: empty map)
+                  1. This is usually result of dbmeta function.
+    :catalog     (Clojure form - String, Keyword etc.; default nil)
+                  1. Catalog name - SHOULD be converted using db-iden
+    :schema      (Clojure form - String, Keyword etc.; default nil)
+                  1. Schema name - SHOULD be converted using db-iden
+    :show-sql    (Booleanl default true)
+                  1. If true, SQL statements should be printed.
+    :clj-to-db   (function, default: to string, replace '-' => '_')
+                  1. Dictates how are identifiers converted from Clojure to
+                     the Database.
+                  2. The default value is the least common denominator that
+                     works with most databases. Override as necessary.
+    :db-to-clj   (function, default: to lower-case keyword, replace '_' => '-')
+                  1. Dictates how are identifiers are converted from the
+                     Database to Clojure.
+                  2. The default value is the least common denominator that
+                     works with most databases. Override as necessary.
 
+  Libraries MAY expose their own API to re-bind this var to new values - they
+  MUST NOT alter the type/semantics of the well-defined keys. They MAY
+  introduce custom keys with unique prefixes e.g. :com.foo.xlib.conn-pool-name
+  (in order to prevent name collision), which may be useful to interoperate
+  with other libraries.
 
-## Create raw database connection
+The idiomatic use of this var is to write middleware to alter the values of
+certain keys. Some pre-built middleware are:
+
+    wrap-dbspec
+    wrap-datasource
+    wrap-datasource-conn
+    wrap-connection
+
+
+### Create raw database connection
 
 **Important: You must include the JDBC drivers on the classpath on your own.**
 
       "")
 
 
-## Work with a Connection obtained from a DataSource
+### Work with a DataSource
 
     ;; assuming we are using Clj-DBCP for creating data source
-    (let [ds (dbcp/h2-memory-datasource)]
-      (spec/with-datasource-connection ds conn
-        ;; notice that 'conn' is bound to the Connection object
-        (-> (.createStatement conn)
-              (.executeQuery "SELECT 1;"))))
+    (let [ds (dbcp/h2-memory-datasource)
+          g  (spec/wrap-datasource ds
+               #(with-open [conn (.getConnection (:datasource spec/*dbspec*))]
+                  (-> (.createStatement conn)
+                    (.executeQuery "SELECT 1;"))))]
+      (g))
 
 
-## Convert Clojure name to database name (name of table/column/column-type etc.)
+### Work with a Connection obtained from a DataSource
+
+    ;; assuming we are using Clj-DBCP for creating data source
+    (let [ds (dbcp/h2-memory-datasource)
+          g  (spec/wrap-datasource-conn ds
+               #(-> (.createStatement (:connection spec/*dbspec*))
+                  (.executeQuery "SELECT 1;")))]
+      (g))
+
+
+### Convert Clojure name to database name (name of table/column/column-type etc.)
 
 Let us see the default behavior:
 
-    (spec/clj-to-dbform :Emp-Name) ; returns "emp_name"
+    (spec/db-iden :Emp-Name) ; returns "emp_name"
 
 You can modify the behavior as follows:
 
-    (binding [spec/*clj-to-db* (make-dbformspec-with {"-" "xx" ; hyphen to "xx"
-                                                      } s
-                (clojure.string/upper-case s))]
-      (spec/clj-to-dbform :Emp-Name)) ; returns "EMPxxNAME"
+    (let [g (wrap-dbspec {:clj-to-db  (fn [iden]
+                                        (if (string? iden) iden
+                                          (apply str (replace {\- "xx"}
+                                                       (name iden)))))}
+              ;; returns "EMPxxNAME"
+              #(spec/db-iden :Emp-Name))]
+      (g))
 
 
-## Convert database name to Clojure name (name of table/column/column-type etc.)
+### Convert database name to Clojure name (name of table/column/column-type etc.)
 
 Let us see the default behavior:
 
-    (spec/db-to-cljform "Emp_Name") ; returns :emp-name
+    (spec/clj-iden "Emp_Name") ; returns :emp-name
 
-You can modify the behavior as follows:
+You can modify the behavior by reassigning a convertor function to the key
+:db-to-clj (as shown in Clojure-to-database name example above.)
 
-    (binding [spec/*clj-to-db* (make-dbformspec-with {"_" "3" ; underscore to "3"
-                                         } s
-                    (keyword (clojure.string/upper-case s)))]
-      (spec/clj-to-dbform "Emp_Name")) ; returns :EMP3NAME
+
+## Reference
+
+Please check The Bitumen Framework Handbook [https://bitbucket.org/kumarshantanu/bituf-handbook/src](https://bitbucket.org/kumarshantanu/bituf-handbook/src)
   <groupId>org.bituf</groupId>
   <artifactId>clj-dbspec</artifactId>
   <packaging>jar</packaging>
-  <version>0.1-SNAPSHOT</version>
+  <version>0.1</version>
   <name>Clj-DBSpec</name>
   <description>
 Clj-DBSpec is a common configuration spec for dealing with relational databases