Revise built-in type adapter class names again, add Yaml type adapter

11 files changed, 179 insertions, 91 deletions

diff --git a/src/main/java/com/iciql/adapter/GsonTypeAdapter.java b/src/main/java/com/iciql/adapter/GsonTypeAdapter.java
index a85f15e..b07b7b5 100644
--- a/src/main/java/com/iciql/adapter/GsonTypeAdapter.java
+++ b/src/main/java/com/iciql/adapter/GsonTypeAdapter.java
@@ -20,16 +20,21 @@ import com.google.gson.GsonBuilder;
 import com.iciql.Iciql.DataTypeAdapter;
 
 /**
- * Base class for inserting/retrieving a Java Object (de)serialized as JSON using Google GSON.
- * <p>You use this by creating a subclass which defines your object class.</p>
+ * Base class for inserting/retrieving a Java Object (de)serialized as JSON
+ * using Google GSON.
+ * <p>
+ * You use this by creating a subclass which defines your object class.
+ * </p>
+ *
  * <pre>
  * public class CustomObjectAdapter extends GsonTypeAdapter&lt;CustomObject&gt; {
  *
- *    public Class&lt;CustomObject&gt; getJavaType() {
- *        return CustomObject.class;
- *    }
+ * 	public Class&lt;CustomObject&gt; getJavaType() {
+ * 		return CustomObject.class;
+ * 	}
  * }
  * </pre>
+ *
  * @param <T>
  */
 public abstract class GsonTypeAdapter<T> implements DataTypeAdapter<T> {
diff --git a/src/main/java/com/iciql/adapter/SnakeYamlTypeAdapter.java b/src/main/java/com/iciql/adapter/SnakeYamlTypeAdapter.java
new file mode 100644
index 0000000..fe4541c
--- /dev/null
+++ b/src/main/java/com/iciql/adapter/SnakeYamlTypeAdapter.java
@@ -0,0 +1,55 @@
+/*
+ * Copyright 2014 James Moger.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 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.
+ */
+
+package com.iciql.adapter;
+
+import org.yaml.snakeyaml.DumperOptions.FlowStyle;
+import org.yaml.snakeyaml.Yaml;
+import org.yaml.snakeyaml.nodes.Tag;
+
+import com.iciql.Iciql.DataTypeAdapter;
+
+/**
+ * Base class for inserting/retrieving a Java Object (de)serialized as YAML using SnakeYaml.
+ */
+public abstract class SnakeYamlTypeAdapter<T> implements DataTypeAdapter<T> {
+
+	protected Yaml yaml() {
+		return new Yaml();
+	}
+
+	@Override
+	public String getDataType() {
+		return "TEXT";
+	}
+
+	@Override
+	public abstract Class<T> getJavaType();
+
+	@Override
+	public Object serialize(Object value) {
+		return yaml().dumpAs(value, Tag.MAP, FlowStyle.BLOCK);
+	}
+
+	@Override
+	public T deserialize(Object value) {
+		String yaml = value.toString();
+		Yaml processor = yaml();
+		T t = processor.loadAs(yaml, getJavaType());
+		return t;
+	}
+
+}
diff --git a/src/main/java/com/iciql/adapter/XStreamTypeAdapter.java b/src/main/java/com/iciql/adapter/XStreamTypeAdapter.java
index 3d1a9ce..5e152df 100644
--- a/src/main/java/com/iciql/adapter/XStreamTypeAdapter.java
+++ b/src/main/java/com/iciql/adapter/XStreamTypeAdapter.java
@@ -21,18 +21,8 @@ import com.thoughtworks.xstream.XStream;
 
 /**
  * Base class for inserting/retrieving a Java Object (de)serialized as XML using XStream.
- * <p>You use this by creating a subclass which defines your object class.</p>
- * <pre>
- * public class CustomObjectAdapter extends XStreamTypeAdapter&lt;CustomObject&gt; {
- *
- *    public Class&lt;CustomObject&gt; getJavaType() {
- *        return CustomObject.class;
- *    }
- * }
- * </pre>
- * @param <T>
  */
-public abstract class XStreamTypeAdapter<T> implements DataTypeAdapter<T> {
+public class XStreamTypeAdapter implements DataTypeAdapter<Object> {
 
 	protected XStream xstream() {
 		return new XStream();
@@ -44,15 +34,21 @@ public abstract class XStreamTypeAdapter<T> implements DataTypeAdapter<T> {
 	}
 
 	@Override
-	public Object serialize(T value) {
+	public Class<Object> getJavaType() {
+		return Object.class;
+	}
+
+	@Override
+	public Object serialize(Object value) {
 		return xstream().toXML(value);
 	}
 
 	@Override
-	public T deserialize(Object value) {
+	public Object deserialize(Object value) {
 		String xml = value.toString();
 		XStream xstream = xstream();
-		T t = (T) xstream.fromXML(xml);
+		Object t = xstream.fromXML(xml);
 		return t;
 	}
+
 }
diff --git a/src/main/java/com/iciql/adapter/postgres/GsonTypeAdapter.java b/src/main/java/com/iciql/adapter/postgresql/JsonObjectAdapter.java
index 64481bd..118cfc1 100644
--- a/src/main/java/com/iciql/adapter/postgres/GsonTypeAdapter.java
+++ b/src/main/java/com/iciql/adapter/postgresql/JsonObjectAdapter.java
@@ -13,20 +13,23 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.iciql.adapter.postgres;
+package com.iciql.adapter.postgresql;
 
 import java.sql.SQLException;
 
 import org.postgresql.util.PGobject;
 
+import com.iciql.adapter.GsonTypeAdapter;
+
 /**
- * Postgres JSON data type adapter maps a JSON column to a domain object using Google GSON.
+ * Postgres JSON data type adapter maps a JSON column to a domain object using
+ * Google GSON.
  *
  * @author James Moger
  *
  * @param <T>
  */
-public abstract class GsonTypeAdapter<T> extends com.iciql.adapter.GsonTypeAdapter<T> {
+public abstract class JsonObjectAdapter<T> extends GsonTypeAdapter<T> {
 
 	@Override
 	public String getDataType() {
diff --git a/src/main/java/com/iciql/adapter/postgres/JsonStringAdapter.java b/src/main/java/com/iciql/adapter/postgresql/JsonStringAdapter.java
index 64ad073..c4fbd6a 100644
--- a/src/main/java/com/iciql/adapter/postgres/JsonStringAdapter.java
+++ b/src/main/java/com/iciql/adapter/postgresql/JsonStringAdapter.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.iciql.adapter.postgres;
+package com.iciql.adapter.postgresql;
 
 import java.sql.SQLException;
 
@@ -22,34 +22,34 @@ import org.postgresql.util.PGobject;
 import com.iciql.Iciql.DataTypeAdapter;
 
 /**
-	 * Handles transforming raw strings to/from the Postgres JSON data type.
-	 */
-	public class JsonStringAdapter implements DataTypeAdapter<String> {
-
-		@Override
-		public String getDataType() {
-			return "json";
-		}
-
-		@Override
-		public Class<String> getJavaType() {
-			return String.class;
-		}
-
-		@Override
-		public Object serialize(String value) {
-			PGobject pg = new PGobject();
-			pg.setType(getDataType());
-			try {
-				pg.setValue(value);
-			} catch (SQLException e) {
-				// not thrown on base PGobject
-			}
-			return pg;
-		}
-
-		@Override
-		public String deserialize(Object value) {
-			return value.toString();
+ * Handles transforming raw strings to/from the Postgres JSON data type.
+ */
+public class JsonStringAdapter implements DataTypeAdapter<String> {
+
+	@Override
+	public String getDataType() {
+		return "json";
+	}
+
+	@Override
+	public Class<String> getJavaType() {
+		return String.class;
+	}
+
+	@Override
+	public Object serialize(String value) {
+		PGobject pg = new PGobject();
+		pg.setType(getDataType());
+		try {
+			pg.setValue(value);
+		} catch (SQLException e) {
+			// not thrown on base PGobject
 		}
-	}
\ No newline at end of file
+		return pg;
+	}
+
+	@Override
+	public String deserialize(Object value) {
+		return value.toString();
+	}
+}
\ No newline at end of file
diff --git a/src/main/java/com/iciql/adapter/postgres/GsonBTypeAdapter.java b/src/main/java/com/iciql/adapter/postgresql/JsonbObjectAdapter.java
index 6332742..6d8ad2c 100644
--- a/src/main/java/com/iciql/adapter/postgres/GsonBTypeAdapter.java
+++ b/src/main/java/com/iciql/adapter/postgresql/JsonbObjectAdapter.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.iciql.adapter.postgres;
+package com.iciql.adapter.postgresql;
 
 import java.sql.SQLException;
 
@@ -22,13 +22,14 @@ import org.postgresql.util.PGobject;
 import com.iciql.adapter.GsonTypeAdapter;
 
 /**
- * Postgres JSONB data type adapter maps a JSONB column to a domain object using Google GSON.
+ * Postgres JSONB data type adapter maps a JSONB column to a domain object using
+ * Google GSON.
  *
  * @author James Moger
  *
  * @param <T>
  */
-public abstract class GsonBTypeAdapter<T> extends GsonTypeAdapter<T> {
+public abstract class JsonbObjectAdapter<T> extends GsonTypeAdapter<T> {
 
 	@Override
 	public String getDataType() {
diff --git a/src/main/java/com/iciql/adapter/postgres/JsonbStringAdapter.java b/src/main/java/com/iciql/adapter/postgresql/JsonbStringAdapter.java
index 1619811..cc2d9c4 100644
--- a/src/main/java/com/iciql/adapter/postgres/JsonbStringAdapter.java
+++ b/src/main/java/com/iciql/adapter/postgresql/JsonbStringAdapter.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.iciql.adapter.postgres;
+package com.iciql.adapter.postgresql;
 
 import java.sql.SQLException;
 
diff --git a/src/main/java/com/iciql/adapter/postgres/XStreamTypeAdapter.java b/src/main/java/com/iciql/adapter/postgresql/XmlObjectAdapter.java
index 1bf6fc2..eba7c06 100644
--- a/src/main/java/com/iciql/adapter/postgres/XStreamTypeAdapter.java
+++ b/src/main/java/com/iciql/adapter/postgresql/XmlObjectAdapter.java
@@ -14,18 +14,18 @@
  * limitations under the License.
  */
 
-package com.iciql.adapter.postgres;
-
+package com.iciql.adapter.postgresql;
 
+import com.iciql.adapter.XStreamTypeAdapter;
 
 /**
- * Postgres XML data type adapter maps an XML column to a domain object using XStream.
+ * Postgres XML data type adapter maps an XML column to a domain object using
+ * XStream.
  *
  * @author James Moger
  *
- * @param <T>
  */
-public abstract class XStreamTypeAdapter<T> extends com.iciql.adapter.XStreamTypeAdapter<T> {
+public abstract class XmlObjectAdapter extends XStreamTypeAdapter {
 
 	@Override
 	public String getDataType() {
diff --git a/src/main/java/com/iciql/adapter/postgres/XmlStringAdapter.java b/src/main/java/com/iciql/adapter/postgresql/XmlStringAdapter.java
index ded517e..defe9f9 100644
--- a/src/main/java/com/iciql/adapter/postgres/XmlStringAdapter.java
+++ b/src/main/java/com/iciql/adapter/postgresql/XmlStringAdapter.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.iciql.adapter.postgres;
+package com.iciql.adapter.postgresql;
 
 import java.sql.SQLException;
 
diff --git a/src/site/dta.mkd b/src/site/dta.mkd
index 6795a0f..70fc25e 100644
--- a/src/site/dta.mkd
+++ b/src/site/dta.mkd
@@ -50,7 +50,7 @@ public class InvoiceAdapterImpl implements DataTypeAdapter<Invoice> {
     }

 

     @Override

-    public Object serialize(DcKey value) {

+    public Object serialize(Invoice value) {

         String json = gson().toJson(value);

         PGobject pg = new PGobject();

         pg.setType(getDataType());

@@ -70,7 +70,8 @@ public class InvoiceAdapterImpl implements DataTypeAdapter<Invoice> {
         final Invoice invoice = gson().fromJson(json, getJavaType());

 

         return invoice;

-  }

+    }

+}

 ---JAVA---

 

 Here you can see how the *InvoiceTypeAdapter* defines a [Postgres JSONB data type](http://www.postgresql.org/docs/9.4/static/datatype-json.html) and automatically handles JSON (de)serialization with [Google Gson](https://code.google.com/p/google-gson) so that the database gets the content in a form that it requires but we can continue to work with objects in Java.

@@ -88,27 +89,46 @@ To simplify this, you can implement your own annotation which specifies your typ
 public @interface InvoiceAdapter { }

 ---JAVA---

 

-### Included DataTypeAdapters

-

-Not every DataTypeAdapter has to be a custom implementation.

-The following adapters are included in Iciql for general purpose use.

-

-- `com.iciql.adapter.JavaSerializationTypeAdapter`

-Uses Java serialization to store/retrieve your objects as BLOBs.

-- `com.iciql.adapter.GsonTypeAdapter`

-Uses Google Gson to store/retrieve your objects as TEXT.

-- `com.iciql.adapter.XmlTypeAdapter`

-Uses XStream to store/retrieve your objects as TEXT.

-- `com.iciql.adapter.postgres.GsonTypeAdapter`

-Uses Google Gson to store/retrieve your objects as JSON for Postgres.

-- `com.iciql.adapter.postgres.GsonBTypeAdapter`

-Uses Google Gson to store/retrieve your objects as JSONB for Postgres.

-- `com.iciql.adapter.postgres.XStreamTypeAdapter`

-Uses XStream to store/retrieve your objects as XML for Postgres.

-- `com.iciql.adapter.postgres.JsonStringAdapter`

-Allows you to use the Postgres JSON data type with a standard String.

-- `com.iciql.adapter.postgres.JsonbStringAdapter`

-Allows you to use the Postgres JSONB data type with a standard String.

-- `com.iciql.adapter.postgres.XmlStringAdapter`

-Allows you to use the Postgres XML data type with a standard String.

+### Included Data Type Adapters

+

+The following adapters are included in Iciql.  They may require an optional dependency such as Gson, XStream, or SnakeYaml.

+

+<table class="table">

+<tr><td colspan="4"><b>Common Type Adapters</b></tr>

+<tr><td><i>Adapter</i></td><td><i>Java</i></td><td><i>SQL</i></td><td><i>Description</i></td></tr>

+

+<tr><td>com.iciql.adapter.JavaSerializationTypeAdapter</td><td>Object</td><td>BLOB</td><td>Uses Java serialization to (de)serialize your object</td></tr>

+

+<tr><td>com.iciql.adapter.GsonTypeAdapter&lt;T&gt;</td><td>&lt;T&gt;</td><td>TEXT</td><td>

+Uses Google Gson to (de)serialize your object as JSON</td></tr>

+

+<tr><td>com.iciql.adapter.XStreamTypeAdapter</td><td>Object</td><td>TEXT</td><td>

+Uses XStream to (de)serialize your object as XML</td></tr>

+

+<tr><td>com.iciql.adapter.SnakeYamlTypeAdapter&lt;T&gt;</td><td>&lt;T&gt;</td><td>TEXT</td><td>

+Uses SnakeYaml to (de)serialize your object as YAML</td></tr>

+

+<tr><td colspan="4"><b>PostgreSQL Type Adapters</b></tr>

+<tr><td><i>Object Adapters</i></td><td><i>Java</i></td><td><i>SQL</i></td><td><i>Description</i></td></tr>

+

+<tr><td>com.iciql.adapter.postgresql.JsonObjectAdapter&lt;T&gt;</td><td>&lt;T&gt;</td><td>JSON</td><td>

+Uses Google Gson to (de)serialize your object as JSON</td></tr>

+

+<tr><td>com.iciql.adapter.postgresql.JsonbObjectAdapter&lt;T&gt;</td><td>&lt;T&gt;</td><td>JSONB</td><td>

+Uses Google Gson to (de)serialize your object as JSONB</td></tr>

+

+<tr><td>com.iciql.adapter.postgresql.XmlObjectAdapter</td><td>Object</td><td>XML</td><td>

+Uses XStream to (de)serialize your object as XML</td></tr>

+

+<tr><td colspan="4"><i>String Adapters</i></td></tr>

+

+<tr><td>com.iciql.adapter.postgresql.JsonStringAdapter</td><td>String</td><td>JSON</td><td>

+Maps the JSON data type to a java.lang.String</td></tr>

+

+<tr><td>com.iciql.adapter.postgresql.JsonbStringAdapter</td><td>String</td><td>JSONB</td><td>

+Maps the JSONB data type to a java.lang.String</td></tr>

+

+<tr><td>com.iciql.adapter.postgresql.XmlStringAdapter</td><td>String</td><td>XML</td><td>

+Maps the XML data type to a java.lang.String</td></tr>

 

+</table>

diff --git a/src/site/index.mkd b/src/site/index.mkd
index a79233c..b9fc549 100644
--- a/src/site/index.mkd
+++ b/src/site/index.mkd
@@ -17,7 +17,7 @@ iciql **is not**...
 

 ### fluent, type-safe SQL DSL with rich object mapping

 

-Born from the unfinished [JaQu][jaqu] subproject of H2 in August 2011, Iciql has advanced the codebase & DSL greatly.  It supports more SQL syntax, more SQL data types, and all standard JDBC object types.

+Born from the unfinished [JaQu][jaqu] subproject of H2 in August 2011, Iciql has [advanced the codebase](jaqu_comparison.html) & DSL greatly.  It supports more SQL syntax, more SQL data types, and all standard JDBC object types.

 

 ---JAVA---

 try (Db db = Db.open("jdbc:h2:mem:iciql")) {

@@ -32,7 +32,7 @@ try (Db db = Db.open("jdbc:h2:mem:iciql")) {
 

 ### dynamic, annotated DAO with standard crud operations

 

-Inspired by [JDBI](http://jdbi.org), Iciql offers a similar Dao feature.  There are some clear benefits to using SQL directly rather than SQL-through-a-DSL so use them both where it makes the most sense for your need.

+Inspired by JDBI, Iciql offers a similar [DAO feature](dao.html).  There are some clear benefits to using SQL directly rather than SQL-through-a-DSL so use each one where it makes the mose sense.

 

 ---JAVA---

 // Define your DAO with SQL annotations and optional type adapters

@@ -83,6 +83,14 @@ try (Db db = Db.open("jdbc:h2:mem:iciql")) {
 }

 ---JAVA---

 

+### flexible field data types

+

+The [Data Type Adapter feature](dta.html) allows you to customize how your SQL column data types map to/from Java objects.

+

+This is very useful for mapping your field domain models to SQL without having to flatten them out to additional columns within your table.  In other words, you can use your database as an object store at the column level by implementing a `@TypeAdapter` (de)serialization step.

+

+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.

+

 ### Supported Databases (Unit-Tested)

 - [H2](http://h2database.com) ${h2.version}

 - [HSQLDB](http://hsqldb.org) ${hsqldb.version}

@@ -103,7 +111,7 @@ iciql is distributed under the terms of the [Apache Software Foundation license,
 [jaqu]: http://h2database.com/html/jaqu.html "H2 JaQu project"

 [orm]: http://en.wikipedia.org/wiki/Object-relational_mapping "Object Relational Mapping"

 [jooq]: http://jooq.sourceforge.net "jOOQ"

-[querydsl]: http://source.mysema.com/display/querydsl/Querydsl "Querydsl"

+[querydsl]: http://source.mysema.com/display/querydsl/Querydsl "QueryDSL"

 [hibernate]: http://www.hibernate.org "Hibernate"

 [mybatis]: http://www.mybatis.org "mybatis"

 [github]: http://github.com/gitblit/iciql "iciql git repository"