Initial commit of iciql.

1 files changed, 170 insertions, 0 deletions

diff --git a/docs/01_model_classes.mkd b/docs/01_model_classes.mkd
new file mode 100644
index 0000000..3ca7630
--- /dev/null
+++ b/docs/01_model_classes.mkd
@@ -0,0 +1,170 @@
+## Model Classes

+A model class represents a single table within your database.  Fields within your model class represent columns in the table.  The object types of your fields are reflectively mapped to SQL types by iciql at runtime.

+

+Models can be manually written using one of two approaches: *annotation configuration* or *interface configuration*.  Both approaches can be used within a project and both can be used within a single model class, although that is discouraged.

+

+Alternatively, model classes can be automatically generated by iciql using the model generation tool.  Please see the [tools](tools.html) page for details.

+

+### Supported Data Types

+<table>

+

+<tr><td>java.lang.String</td>

+<td>VARCHAR *(maxLength > 0)* or TEXT *(maxLength == 0)*</td></tr>

+ 	

+<tr><td>java.lang.Boolean</td>

+<td>BIT</td></tr>

+	

+<tr><td>java.lang.Byte</td>

+<td>TINYINT</td></tr>

+	

+<tr><td>java.lang.Short</td>

+<td>SMALLINT</td></tr>

+	

+<tr><td>java.lang.Integer</td>

+<td>INT</td></tr>

+	

+<tr><td>java.lang.Long</td>

+<td>BIGINT</td></tr>

+	

+<tr><td>java.lang.Float</td>

+<td>REAL</td></tr>

+	

+<tr><td>java.lang.Double</td>

+<td>DOUBLE</td></tr>

+	

+<tr><td>java.math.BigDecimal</td>

+<td>DECIMAL</td></tr>

+	

+<tr><td>java.sql.Date</td>

+<td>DATE</td></tr>

+	

+<tr><td>java.sql.Time</td>

+<td>TIME</td></tr>

+	

+<tr><td>java.sql.Timestamp</td>

+<td>TIMESTAMP</td></tr>

+

+<tr><td>java.util.Date</td>

+<td>TIMESTAMP</td></tr>

+

+</table>

+

+**NOTE:**<br/>

+The reverse lookup used for model generation, SQL type -> Java type, contains more mappings.<br/>

+Please consult the `com.iciql.ModelUtils` class for details. 

+

+### Unsupported Types

+- Java primitives (use their object counterparts instead)

+- binary types (BLOB, etc)

+- array types

+- custom types

+

+### Configuration Rules

+1. field mappings must be Objects not primitives

+2. the model class must have a default public constructor

+

+### Configuration Limitations

+1. index names can not be specified

+2. triggers, views, and other advanced database features are unimplemented

+

+## Annotation Configuration

+The recommended approach to setup a model class is to annotate the class and field declarations.

+

+### advantages

+

+- annotated fields may have any scope

+- annotated models support annotated field inheritance making it possible to design a single base class that defines the fields and then create table subclasses that specify the table mappings.

+- model runtime dependency is limited to the small, portable `com.iciql.Iciql` class file which contains the annotation definitions

+

+### disadvantages

+

+- more verbose model classes

+- indexes are defined using "fragile" string column names

+- compound primary keys are defined using "fragile" string column names

+ 

+### Example Annotated Model

+%BEGINCODE%

+import com.iciql.Iciql.IQColumn;

+import com.iciql.Iciql.IQIndex;

+import com.iciql.Iciql.IQTable;

+

+@IQTable

+@IQIndex(standard = {"productName", "category"})

+public class Product {

+

+	@IQColumn(primaryKey = true)

+	public Integer productId;

+      

+	@IQColumn(maxLength = 200, trimString = true)

+	public String productName;

+      

+	@IQColumn(maxLength = 50, trimString = true)

+	public String category;

+      

+	@IQColumn

+	public Double unitPrice;

+      

+	@IQColumn(name = "units")

+	public Integer unitsInStock;

+      

+	@IQColumn

+	private Integer reorderQuantity;

+      

+	public Product() {

+		// default constructor

+	}

+}

+%ENDCODE%

+

+## Interface Configuration (deprecated)

+Alternatively, you may map your model classes using the original JaQu interface approach by implementing the `com.iciql.Iciql` interface.

+

+This is a less verbose configuration style, but it comes at the expense of introducing a compile-time dependency on the logic of the iciql library.  This might be a deterrent, for example, if you were serializing your model classes to another process that may not have the iciql library.

+

+The `com.iciql.Iciql` interface specifies a single method, *defineIQ()*.  In your implementation of *defineIQ()* you would use static method calls to set:

+

+- the table name (if it's not the class name)

+- the column name (if it's not the field name)

+- the max length of a string field

+- the primaryKey (single field or compound)

+- any indexes (single field or compound)

+

+### advantages

+

+- less verbose model class

+- compile-time index definitions

+- compile-time compound primary key definitions

+

+### disadvantages

+

+- <u>only **public** fields of the model class are reflectively mapped as columns</u>. all other scoped fields and inherited fields are ignored.

+- model runtime dependency on entire iciql library

+- *defineIQ()* is called from a static synchronized block which may be a bottleneck for highly concurrent systems

+

+### Example Interface Model

+%BEGINCODE%

+import com.iciql.Iciql;

+

+public class Product implements Iciql {

+	public Integer productId;

+	public String productName;

+	public String category;

+	public Double unitPrice;

+	public Integer unitsInStock;

+	

+	// this field is ignored because it is not public

+	Integer reorderQuantity;

+      

+	public Product() {

+	}

+      

+	@Override

+	public void defineIQ() {

+		com.iciql.Define.primaryKey(productId);

+		com.iciql.Define.columnName(unitsInStock, "units");

+		com.iciql.Define.maxLength(productName, 200);

+		com.iciql.Define.maxLength(category, 50);

+		com.iciql.Define.index(productName, category);

+	}

+}

+%ENDCODE%
\ No newline at end of file