Documentation. Source cleanup. Prepare 0.6.4 release.

docs/00_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 (100KB) with no runtime dependencies
+- small (120KB) with no runtime dependencies
 - pronounced *icicle* (although it could be French: *ici ql* - here query language)
 - a friendly fork of the H2 [JaQu][jaqu] project
 

docs/01_model_classes.mkd

@@ -105,6 +105,8 @@ The recommended approach to setup a model class is to annotate the class and fie
 You may specify default values for an @IQColumn by either:
 
 1. specifying the default value string within your annotation<br/>
+**NOTE:**<br/>
+The annotated default value always takes priority over a field default value.
 %BEGINCODE%
 // notice the single ticks!
 @IQColumn(defaultValue="'2000-01-01 00:00:00'")

docs/02_usage.mkd

@@ -113,7 +113,7 @@ The Product model class instance named **p** is an *alias* object.  An *alias* i
 
 1. *Alias* instances are **NOT** thread-safe and must not be used concurrently.
 2. *Alias* instances have no other purpose than to provide a compile-time/runtime map of your table.
-3. If you inspected an *alias* instance after using one you would find that it's fields have been assigned numeric values.<br/>These values are assigned from a static counter in `com.iciql.Utils.newObject()` during execution of the *db.from()* method.<p>For *Object* fields, these values are meaningless since objects are mapped by reference.  These values do matter for *primitive* fields where they are mapped by value.
+3. If you inspected an *alias* instance after using one you would find that it's fields have been assigned numeric values.<br/>These values are assigned from a static counter in `com.iciql.Utils.newObject()` during execution of the *db.from()* method.<p>For *Object* fields, these values are meaningless since objects are mapped by reference.<br/>For *Primitive* fields these values do matter because primitives are mapped by value.  The proper alias is selected as long as the primitive variant methods are used.  e.g. db.from(p).where(int).is(Integer).select()
 
 If your statement is a query, like in the above example, iciql will generate new instances of your *alias* model class and return them as a list where each entry of the list represents a row from the JDBC `ResultSet`.
  

docs/05_releases.mkd

@@ -8,21 +8,26 @@
 
 - api change release (API v4)
 - @IQTable.createIfRequired -> @IQTable.create
-- don't INSERT primitive autoIncrement primaryKey fields, let database assign value
+- don't INSERT primitive autoIncrement fields, let database assign value
 - full support for primitives in all clauses
 - DECIMAL(length, scale) support
 - unspecified length String fields are now CLOB instead of TEXT.  dialects can intercept this and convert to another type. e.g. MySQL dialect can change CLOB to TEXT.
-- Boolean now maps to BOOLEAN instead of BIT
+- java.lang.Boolean now maps to BOOLEAN instead of BIT
 - expressions on unmapped fields will throw an IciqlException
-- improved exception reporting
+- expressions on unsupported types will throw an IciqlException
+- improved exception reporting by including generated statement, if available 
 - moved dialects back to main package
 - improved automatic dialect determination on pooled connections
 - moved create table and create index statement generation into dialects
-- added HSQL dialect.  HSQL fails 4 out of 49 unit tests: 2 failures are unimplemented merge, and 1 has been filed as a [bug in HSQL](https://sourceforge.net/tracker/?func=detail&aid=3390047&group_id=23316&atid=378131).
-- added MySQL dialect.  untested.
+- added HSQL dialect.  HSQL fails 4 out of 50 unit tests.
+    - 2 failures are unimplemented merge
+    - 1 has been filed and accepted as a [bug in HSQL](https://sourceforge.net/tracker/?func=detail&aid=3390047&group_id=23316&atid=378131)
+    - 1 is a concurrency issue, but the test may not be flawed
+- added untested MySQL dialect
 - renamed <b>_ iq_versions</b> table to *iq_versions* since leading _ character is troublesome for some databases.
 - @IQColumn(allowNull=true) -> @IQColumn(nullable=true)
-- All columns are assumed NULLABLE unless explicitly set *@IQColumn(nullable = false)*
+- All **Object** columns are assumed NULLABLE unless explicitly set *@IQColumn(nullable = false)*
+- All **Primitive** columns are assumed NOT NULLABLE unless explicitly set *@IQColumn(nullable = true)*
 - allow using objects to assign default values<br/>
 %BEGINCODE%
 // CREATE TABLE ... myDate DATETIME DEFAULT '2000-02-01 00:00:00'

src/com/iciql/Constants.java

@@ -25,11 +25,11 @@ public class Constants {
 
 	// The build script extracts this exact line so be careful editing it
 	// and only use A-Z a-z 0-9 .-_ in the string.
-	public static final String VERSION = "0.6.4-SNAPSHOT";
+	public static final String VERSION = "0.6.4";
 
 	// The build script extracts this exact line so be careful editing it
 	// and only use A-Z a-z 0-9 .-_ in the string.
-	public static final String VERSION_DATE = "PENDING";
+	public static final String VERSION_DATE = "2011-08-12";
 
 	// The build script extracts this exact line so be careful editing it
 	// and only use A-Z a-z 0-9 .-_ in the string.

src/com/iciql/Define.java

@@ -63,7 +63,7 @@ public class Define {
 		checkInDefine();
 		currentTableDefinition.setLength(column, length);
 	}
-	
+
 	public static void scale(Object column, int scale) {
 		checkInDefine();
 		currentTableDefinition.setScale(column, scale);
@@ -74,6 +74,7 @@ public class Define {
 		currentTableDefinition.setTableName(tableName);
 	}
 
+	@SuppressWarnings("deprecation")
 	static synchronized <T> void define(TableDefinition<T> tableDefinition, Iciql table) {
 		currentTableDefinition = tableDefinition;
 		currentTable = table;
@@ -86,7 +87,8 @@ public class Define {
 	private static void checkInDefine() {
 		if (currentTable == null) {
 			throw new IciqlException("This method may only be called "
-					+ "from within the define() method, and the define() method " + "is called by the framework.");
+					+ "from within the define() method, and the define() method "
+					+ "is called by the framework.");
 		}
 	}
 

src/com/iciql/util/JdbcUtils.java

@@ -23,6 +23,7 @@ import java.sql.ResultSet;
 import java.sql.SQLException;
 import java.sql.Statement;
 import java.util.Properties;
+
 import javax.naming.Context;
 import javax.sql.DataSource;
 import javax.sql.XAConnection;

tests/com/iciql/test/AnnotationsTest.java

@@ -38,8 +38,6 @@ import com.iciql.test.models.ProductAnnotationOnly;
 import com.iciql.test.models.ProductInheritedAnnotation;
 import com.iciql.test.models.ProductMixedAnnotation;
 import com.iciql.test.models.ProductNoCreateTable;
-import com.iciql.util.JdbcUtils;
-import com.iciql.util.Utils;
 
 /**
  * Test annotation processing.

tests/com/iciql/test/ClobTest.java

@@ -17,9 +17,9 @@
 
 package com.iciql.test;
 
-import static org.junit.Assert.assertEquals;
 import static com.iciql.Define.primaryKey;
 import static com.iciql.Define.tableName;
+import static org.junit.Assert.assertEquals;
 
 import java.text.MessageFormat;
 import java.util.Arrays;

tests/com/iciql/test/ModelsTest.java

@@ -56,10 +56,6 @@ public class ModelsTest {
 
 	private Db db;
 
-	private void log(String text) {
-		System.out.println(text);
-	}
-
 	@Before
 	public void setUp() {
 		db = IciqlSuite.openDb();

tests/com/iciql/test/models/EnumModels.java

@@ -25,6 +25,10 @@ import com.iciql.Iciql.IQColumn;
 import com.iciql.Iciql.IQEnum;
 import com.iciql.Iciql.IQTable;
 
+/**
+ * Container for reusable enum model classes which exercise the 3 supported
+ * types.
+ */
 public abstract class EnumModels {
 
 	/**

tests/com/iciql/test/models/Order.java

@@ -27,7 +27,6 @@ import java.util.Arrays;
 import java.util.Date;
 import java.util.List;
 
-
 import com.iciql.Iciql;
 
 /**