</target>
-
- <!--
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Build the iciql website
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- -->
- <target name="buildSite" description="Build the iciql website">
- <!-- ensure we have performance data -->
- <mx:if>
- <not>
- <available file="${project.outputDirectory}/performance_db.txt" />
- </not>
- <then>
- <fail message="Please run the "testsuite" target!"/>
- </then>
- </mx:if>
-
- <!-- Download links -->
- <property name="gc.url" value="http://gitblit.github.io/iciql/maven/com/iciql/${project.artifactId}/${project.releaseVersion}/" />
- <property name="releaselog" value="${basedir}/releases.moxie" />
-
- <mx:doc googleplusone="true" prettifyTheme="googlecode" minify="true"
- templateDir="${project.siteSourceDirectory}/templates"
- customless="custom.less" rssFeed="rss.xml" atomFeed="atom.xml">
-
- <logo file="iciql_white.png" />
- <favicon file="iciql-favicon.png" />
-
- <load token="%DBPERFORMANCE%" file="${project.outputDirectory}/performance_db.txt" />
- <regex searchPattern="\b(issue)(\s*[#]?|-){0,1}(\d+)\b"
- replacePattern="<a href='${project.issuesUrl}/detail?id=$3'>issue $3</a>" />
-
- <structure>
-
- <menu name="about" pager="true" pagerPlacement="bottom" pagerLayout="justified">
- <page name="overview" src="index.mkd" out="index.html" />
- <page name="performance" src="performance.mkd" out="performance.html" />
- <page name="jaqu comparison" src="jaqu_comparison.mkd" out="jaqu_comparison.html" />
- </menu>
-
- <menu name="getting started" pager="true" pagerPlacement="bottom" pagerLayout="justified">
- <page name="table model classes" src="model_classes.mkd" out="model_classes.html" headerLinks="true" />
- <page name="data type adapters (DTA)" src="dta.mkd" out="dta.html" headerLinks="true" />
- <page name="data access object (DAO) usage" src="dao.mkd" out="dao.html" headerLinks="true" />
- <page name="database and table versioning" src="table_versioning.mkd" out="table_versioning.html" headerLinks="true" />
- <divider />
- <page name="SQL DSL usage" src="usage.mkd" out="usage.html" headerLinks="true" />
- <page name="SQL DSL examples" src="examples.mkd" out="examples.html" headerLinks="true" />
- <page name="tools" src="tools.mkd" out="tools.html" headerLinks="true" />
- </menu>
-
- <page name="building" src="building.mkd" out="building.html" />
-
- <page name="release notes" out="releasenotes.html">
- <template src="releasecurrent.ftl" data="${releaselog}" />
- </page>
- <page out="releases.html" navbarlink="false">
- <template src="releasehistory.ftl" data="${releaselog}" />
- </page>
-
- <menu name="downloads">
- <link name="Maven Central (2.0.0+)"
- src="http://search.maven.org/#search|ga|1|com.gitblit.iciql" />
- <divider />
- <link name="Iciql Maven Repository (pre-2.0.0)" src="${project.mavenUrl}" />
- </menu>
-
- <menu name="links">
- <link name="Github" src="${project.scmUrl}" />
- <link name="Issues" src="${project.issuesUrl}" />
- </menu>
- <divider />
- </structure>
-
- <!-- Generate RSS and Atom feeds from the release history -->
- <page as="atom.xml">
- <template src="atom.ftl" data="${releaselog}" />
- </page>
- <page as="rss.xml">
- <template src="rss.ftl" data="${releaselog}" />
- </page>
-
- </mx:doc>
-
- <!-- Copy standard javadoc -->
- <mkdir dir="${project.siteTargetDirectory}/javadoc" />
- <copy todir="${project.siteTargetDirectory}/javadoc">
- <fileset dir="${project.javadocTargetDirectory}" />
- </copy>
- </target>
-
-
- <!--
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Copy the built site to the gh-pages branch
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- -->
- <target name="updateGhpages" depends="buildSite">
- <mx:ghpages obliterate="false" />
- </target>
-
-
- <!--
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Publish site to hosting service
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- -->
- <target name="publishSite" depends="updateGhpages" description="Publish the iciql site to a webserver" >
-
- <echo>Uploading ${project.artifactId} ${project.version} website</echo>
-
- <mx:ftp server="${ftp.server}"
- userid="${ftp.user}"
- password="${ftp.password}"
- remotedir="${ftp.site.dir}"
- passive="true"
- verbose="yes">
- <fileset dir="${project.siteTargetDirectory}" />
- </mx:ftp>
- </target>
-
-
- <!--
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Tag a new version and prepare for the next development cycle.
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- -->
- <target name="tagRelease" depends="prepare" description="Tags a release">
- <!-- release -->
- <property name="dryrun" value="false" />
- <mx:version stage="release" dryrun="${dryrun}" />
- <property name="project.tag" value="v${project.version}" />
- <!-- commit build.moxie & releases.moxie (automatic) -->
- <mx:commit showtitle="no">
- <message>Prepare ${project.version} release</message>
- <tag name="${project.tag}">
- <message>${project.name} ${project.version} release</message>
- </tag>
- </mx:commit>
-
- <!-- create the release process script -->
- <mx:if>
- <os family="windows" />
- <then>
- <!-- Windows PowerShell script -->
- <!-- set-executionpolicy remotesigned -->
- <property name="recipe" value="release_${project.version}.ps1" />
- </then>
- <else>
- <!-- Bash script -->
- <property name="recipe" value="release_${project.version}.sh" />
- </else>
- </mx:if>
- <delete file="${recipe}" failonerror="false" quiet="true" verbose="false" />
- <!-- Work-around for lack of proper ant property substitution in copy -->
- <property name="dollar" value="$"/>
- <copy file="release.template" tofile="${recipe}">
- <filterset begintoken="${dollar}{" endtoken="}">
- <filter token="project.version" value="${project.version}" />
- <filter token="project.commitId" value="${project.commitId}" />
- <filter token="project.tag" value="${project.tag}" />
- </filterset>
- </copy>
- <chmod file="${recipe}" perm="ugo+rx" />
-
- <!-- next cycle -->
- <mx:version stage="snapshot" incrementNumber="minor" dryrun="${dryrun}" />
- <mx:commit showtitle="no">
- <message>Reset build identifiers for next development cycle</message>
- </mx:commit>
- </target>
-
-
</project>
+++ /dev/null
-## Building from Source\r
-\r
-### Maven\r
-\r
-You may use Maven to build the project:\r
-\r
- mvn clean package\r
- \r
-You may use Maven to run the test suite on the default database:\r
-\r
- mvn clean test\r
-\r
-### Ant\r
-\r
-You may use Ant to build this project:\r
-\r
- ant clean build\r
- \r
-You may execute the full test suite against all tested databases:\r
- \r
- ant testsuite\r
-\r
-## Contributing\r
-Patches welcome in any form.\r
-\r
-Contributions must be your own original work and must licensed under the [Apache License, Version 2.0][apachelicense], the same license used by iciql.\r
-\r
-[apachelicense]: http://www.apache.org/licenses/LICENSE-2.0 "Apache License, Version 2.0"
\ No newline at end of file
+++ /dev/null
-\r
-// GLOBAL VALUES\r
-// --------------------------------------------------\r
-@standardGray: #ccc;\r
-@iciql: #95C7F9;\r
-@white: #fff;\r
-\r
-// Dropdown\r
-// -------------------------\r
-@dropdownLinkBackgroundHover: @iciql;\r
-\r
-// Navbar\r
-// -------------------------\r
-@navbarHeight: 50px;\r
-@navbarBackground: @iciql;\r
-@navbarBackgroundHighlight: @iciql;\r
-@navbarText: @white;\r
-@navbarLinkColor: @white;\r
-@navbarLinkColorHover: @white;\r
-@navbarLinkColorActive: @white;\r
-@navbarLinkBackgroundHover: transparent;\r
-@navbarLinkBackgroundActive: transparent;\r
-\r
-.navbar {\r
- .brand {\r
- @elementHeight: 48px;\r
- padding: 5px;\r
- }\r
-}\r
-\r
-.navbar .nav > li > a {\r
- font-size: @baseFontSize + 1; \r
- text-shadow: 0 1px 0 #6b94df;\r
-}\r
-\r
-\r
-.navbar .nav > li > a:hover {\r
- text-shadow: 0 0 1em white;\r
-}\r
-.navbar .nav > .active > a, \r
- .navbar .nav > .active > a:hover,\r
- .navbar .nav > .active > a:focus {\r
- box-shadow: none;\r
- text-decoration: underline;\r
-}\r
-\r
-.dropdown-submenu > a:after {\r
- margin-right: -5px;\r
-}\r
-\r
-body { padding-top: @navbarHeight + 15 } /* 60px to make the container go all the way to the bottom of the topbar */\r
-footer { margin-top: 25px; padding: 15px 0 16px; border-top: 1px solid #E5E5E5; }\r
-\r
-a:hover { text-decoration: underline !important; }\r
-em { color: #50a000; }\r
+++ /dev/null
-## Data Access Object (DAO)\r
-\r
-[JDBI](http://jdbi.org) brings an interesting feature to the table with dynamic generation of an annotation-based, partially type-safe DAO. This is a great idea and one that Iciql has absorbed into it's featureset.\r
-\r
-The Iciql implementation is quite different, but the usage is very similar. Iciql does not aim to recreate all features and capabilities of JDBI's DAO.\r
-\r
-### Instantiating a DAO\r
-\r
-Once you have a Db instance, you may generate a dynamic DAO instance which is backed by it.\r
-\r
----JAVA---\r
-Db db = Db.open("jdbc:h2:mem:iciql");\r
-db.open(MyDao.class);\r
----JAVA---\r
-\r
-A minimal DAO is an *interface* that extends the `Dao` interface. This gives your DAO instance access to the standard Iciql CRUD methods for interacting with your database models, the `db()` method to retrieve the underlying db instance, and the `close()` method for closing the underlying JDBC connection.\r
-\r
----JAVA---\r
-public interface MyDao extends Dao {\r
-}\r
----JAVA---\r
-\r
-Your `Dao` instance is also auto-closable so you may use the Java 7 try-with-resources syntax.\r
-\r
-**Note:** You never implement the DAO methods - that is taken care of for you through the magic of `java.lang.reflect.Proxy` and `com.iciql.DaoProxy`.\r
-\r
-### @SqlQuery\r
-\r
-DAO queries are method declarations annotated with `@SqlQuery`.\r
-\r
-#### Return types\r
-\r
-1. An `@SqlQuery` method must specify a non-void return a type.\r
-2. The return type may not be a `java.util.Collection`, but it may be an array [] type. This is due to generic type erasure by javac whereas arrays preserve their component type information.\r
-**NOTE:** Iciql will always return a 0-length array instead of a null when there are no results so you won't have to worry about null checks.\r
-3. An `@SqlQuery` method may specify a data type adapter using the `@TypeAdapter` annotation if the returned value is a field, not a row.\r
-\r
-##### Returning a field with @TypeAdapter\r
-\r
-Normally, Iciql will map the fields in a query ResultSet to your return type object. However, if you are querying a single field from a table then you may specify a `@TypeAdapter` on an `@SqlQuery` method allowing you to deserialize complex data into an object.\r
-\r
-For example, if you are using the Postgres JSON/JSONB column type in your table then you might want to directly deserialize the raw JSON stored in Postgres into an object rather than just retrieving the JSON document and manually transforming it. You can use a `@TypeAdapter` to perform this work for you.\r
-\r
-#### Method Argument->Statement Parameter mapping\r
-\r
-`@SqlQuery` supports 6 techniques for mapping method arguments to statement parameters.\r
-\r
-1. `:?` where the method argument order implicitly determines statement parameter order. This is similar to a PreparedStatement.\r
-2. `:arg0` where you specify the 0-based index of the method argument.\r
-3. `:1` where you specify the 1-based index of the method argument.\r
-4. `:name` automatic Java 8 method parameter naming, assuming you are compiling on Java 8 with the `-parameters` javac flag.\r
-5. `@Bind("name") + :name` argument annotation where you explicitly name the statement parameter.\r
-6. `@BindBean("prefix") + :prefix.property` argument annotation which flags the argument as a JavaBean. This allows you to access JavaBean properties from your statement.\r
-**NOTE:** If the prefix is empty, your JavaBean properties will be directly accessible. (e.g. `:property` not `:p.property`)\r
-\r
-#### Example @SqlQuery usage\r
-\r
----JAVA---\r
-public interface MyDao extends Dao {\r
-\r
- @SqlQuery("select * from Product")\r
- Product [] getAllProducts();\r
- \r
- // Named parameters\r
- @SqlQuery("select * from Product where productId = :id")\r
- Product getProduct(@Bind("id") long id);\r
- \r
- // Reflection-style 0-indexed args\r
- @SqlQuery("select * from Product where productId = :arg0")\r
- Product getProduct2(long id);\r
-\r
- // JDBC-style 1-indexed parameters\r
- @SqlQuery("select * from Product where productId = :1")\r
- Product getProduct2(long id);\r
-\r
- // If you are compiling on Java 8 with -parameters\r
- @SqlQuery("select * from Product where productId = :id")\r
- Product getProduct2(long id);\r
- \r
- // demonstrates how to use bean binding\r
- @SqlQuery("select productId from Product where category = :p.category and unitsInStock >= :p.unitsInStock")\r
- long [] getSimilarInStockItemIds(@BindBean("p") Product p);\r
-\r
- // You can extract a field with full standard type mapping\r
- @SqlQuery("select orderDate from Orders order by orderDate desc limit 1")\r
- Date getMostRecentOrderDate();\r
- \r
- // You can extract a field that requires a data type adapter (e.g. a Postgres JSON/JSONB, BLOB, etc)\r
- @SqlQuery("select invoice from Invoices order by received desc limit 1")\r
- @TypeAdapter(InvoiceAdapterImpl.class)\r
- Invoice getMostRecentInvoice();\r
-\r
-}\r
----JAVA---\r
-\r
-### @SqlStatement\r
-\r
-DAO statements are method declarations annotated with `@SqlStatement`.\r
-\r
-#### Return types\r
-\r
-Statements to now return a ResultSet so `@SqlStatement` methods have three acceptable return types:\r
-\r
-1. *void*\r
-2. *boolean*, if the affected row count is non-zero, true is returned, otherwise false\r
-3. *int*, returns the affected row count\r
-\r
-`@TypeAdapter` may not be annotated on a `@SqlStatement` method. However it may be used on the method arguments.\r
-\r
-#### Method Argument->Statement Parameter mapping\r
-\r
-The parameter mapping rules are exactly the same as for `@SqlQuery`.\r
-\r
-#### Example @SqlStatement usage\r
-\r
----JAVA---\r
-public interface MyDao extends Dao {\r
-\r
- // this statement does not return anything\r
- @SqlStatement("update Product set productName = :name where productId = :id")\r
- void setProductName(@Bind("id") long id, @Bind("name") String name);\r
-\r
- // this statement returns true if at least one row was affected\r
- @SqlStatement("update Product set productName = :name where productId = :id")\r
- boolean renameProduct(@Bind("id") long id, @Bind("name") String name);\r
-\r
- // this statement returns the number of affected rows\r
- @SqlStatement("update Product set category = :new where category = :old")\r
- int renameProductCategory(@Bind("old") String oldCategory, @Bind("new") String newCategory);\r
- \r
- // You can update a field that requires a data type adapter\r
- @SqlStatement("update Invoices set invoice = :2 where id = :1")\r
- boolean setInvoice(long id, @TypeAdapter(InvoiceAdapterImpl.class) Invoice invoice);\r
-\r
-}\r
----JAVA---\r
-\r
-### Runtime Mode & External Statements\r
-\r
-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.\r
-\r
-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`.\r
-\r
-#### External Statement DAO Example\r
----JAVA---\r
-public interface MyDao extends Dao {\r
- @SqlQuery("some.query")\r
- Product [] getProductsWithRuntimeModeDependentQuery();\r
-}\r
-\r
-Db db = Db.open("jdbc:h2:mem:iciql");\r
-// set a classpath statement resource provider\r
-db.setDaoStatementProvider(new DaoClasspathStatementProvider());\r
-\r
-// open the dao and retrieve the products\r
-MyDao dao = db.open(MyDao.class);\r
-Product [] products = dao.getProductsWithRuntimeModeDependentQuery();\r
----JAVA---\r
-\r
-#### External Statement Resource Example\r
-\r
----FIXED---\r
-some.query = select * from Products # default statement\r
-%prod.some.query = select * from Products # will be used in PROD mode\r
-%test.some.query = select * from Products where category = 'Beverages' # will be used in TEST mode\r
-%dev.some.query = select * from Products where category = 'Condiments' # will be used in DEV mode\r
----FIXED---\r
-\r
-#### DaoClasspathStatementProvider\r
-\r
-Iciql ships with one useful implementation of a DaoStatementProvider: `DaoClasspathStatementProvider`.\r
-\r
-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.\r
-\r
-1. `/iciql.properties`\r
-2. `/iciql.xml`\r
-3. `/conf/iciql.properties`\r
-4. `/conf/iciql.xml`\r
-\r
-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
+++ /dev/null
-## Data Type Adapters\r
-\r
-Data type adapters allow you to extend Iciql's support for field data types.\r
-\r
-For example, you might want to take advantage of the [Postgres JSON/JSONB support](http://www.postgresql.org/docs/9.4/static/datatype-json.html) in 9.3/9.4 but instead of directly handling JSON text documents you might want to represent that JSON as a domain object and serialize/deserialize to JSON only when executing an SQL operation.\r
-\r
-Data type adapters give you this flexibility.\r
-\r
-**NOTE:** Data type adapters are reused within a Db instance and are not inherently thread-safe. You must handle thread-safety on your own, if it is an issue.\r
-\r
-### An example\r
-\r
-Consider the following model class.\r
-\r
----JAVA---\r
-@IQTable\r
-public class Invoices {\r
- \r
- @IQColumn(primaryKey = true, autoIncrement = true)\r
- public long _id;\r
- \r
- @IQColumn\r
- Date received;\r
- \r
- @IQColumn\r
- @TypeAdapter(InvoiceAdapterImpl.class)\r
- Invoice invoice;\r
-}\r
----JAVA---\r
-\r
-This is a really simple table with three columns, but the third column uses a type adapter to map our *invoice* object field to an SQL type. You can use the `@TypeAdapter` annotation either on the field definition or on the class definition of your domain model.\r
-\r
-Let's take a look at *InvoiceAdapterImpl*.\r
-\r
----JAVA---\r
-public class InvoiceAdapterImpl implements DataTypeAdapter<Invoice> {\r
-\r
- Mode mode;\r
- \r
- @Override\r
- public void setMode(Mode mode) {\r
- this.mode = mode;\r
- }\r
-\r
- @Override\r
- public String getDataType() {\r
- return "jsonb";\r
- }\r
-\r
- @Override\r
- public Class<Invoice> getJavaType() {\r
- return Invoice.class;\r
- }\r
-\r
- Gson gson() {\r
- return new GsonBuilder().create();\r
- }\r
-\r
- @Override\r
- public Object serialize(Invoice value) {\r
- String json = gson().toJson(value);\r
- PGobject pg = new PGobject();\r
- pg.setType(getDataType());\r
- try {\r
- pg.setValue(json);\r
- } catch (SQLException e) {\r
- // ignore, never thrown\r
- }\r
- return pg;\r
- }\r
-\r
- @Override\r
- public Invoice deserialize(Object value) {\r
-\r
- // the incoming object is always represented as a string\r
- final String json = value.toString();\r
- final Invoice invoice = gson().fromJson(json, getJavaType());\r
-\r
- return invoice;\r
- }\r
-}\r
----JAVA---\r
-\r
-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.\r
-\r
-### Runtime Mode\r
-\r
-Data type adapters can respond to the Iciql runtime mode (`DEV`, `TEST`, or `PROD`) allowing them to change their behavior. This is useful for targetting a data type that might be available in your production database but may not be available in your development or testing database.\r
-\r
-### Custom annotations\r
-\r
-It is a little verbose to repeat `@TypeAdapter(InvoiceAdapterImpl.class)` everywhere you want to use your adapter.\r
-\r
-To simplify this, you can implement your own annotation which specifies your type adapter.\r
-\r
----JAVA---\r
-@Retention(RetentionPolicy.RUNTIME)\r
-@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER })\r
-@TypeAdapter(InvoiceAdapterImpl.class)\r
-public @interface InvoiceAdapter { }\r
----JAVA---\r
-\r
-### Included Data Type Adapters\r
-\r
-The following adapters are included in Iciql. They may require an optional dependency such as Gson, XStream, or SnakeYaml.\r
-\r
-<table class="table">\r
-<tr><td colspan="4"><b>Common Type Adapters</b></tr>\r
-<tr><td><i>Adapter</i></td><td><i>Java</i></td><td><i>SQL</i></td><td><i>Description</i></td></tr>\r
-\r
-<tr><td>com.iciql.adapter.JavaSerializationTypeAdapter</td><td>Object</td><td>BLOB</td><td>Uses Java serialization to (de)serialize your object</td></tr>\r
-\r
-<tr><td>com.iciql.adapter.GsonTypeAdapter<T></td><td><T></td><td>TEXT</td><td>\r
-Uses Google Gson to (de)serialize your object as JSON</td></tr>\r
-\r
-<tr><td>com.iciql.adapter.XStreamTypeAdapter</td><td>Object</td><td>TEXT</td><td>\r
-Uses XStream to (de)serialize your object as XML</td></tr>\r
-\r
-<tr><td>com.iciql.adapter.SnakeYamlTypeAdapter<T></td><td><T></td><td>TEXT</td><td>\r
-Uses SnakeYaml to (de)serialize your object as YAML</td></tr>\r
-\r
-<tr><td colspan="4"><b>PostgreSQL Type Adapters</b></tr>\r
-<tr><td><i>Object Adapters</i></td><td><i>Java</i></td><td><i>SQL</i></td><td><i>Description</i></td></tr>\r
-\r
-<tr><td>com.iciql.adapter.postgresql.JsonObjectAdapter<T></td><td><T></td><td>JSON</td><td>\r
-Uses Google Gson to (de)serialize your object as JSON</td></tr>\r
-\r
-<tr><td>com.iciql.adapter.postgresql.JsonbObjectAdapter<T></td><td><T></td><td>JSONB</td><td>\r
-Uses Google Gson to (de)serialize your object as JSONB</td></tr>\r
-\r
-<tr><td>com.iciql.adapter.postgresql.XmlObjectAdapter</td><td>Object</td><td>XML</td><td>\r
-Uses XStream to (de)serialize your object as XML</td></tr>\r
-\r
-<tr><td colspan="4"><i>String Adapters</i></td></tr>\r
-\r
-<tr><td>com.iciql.adapter.postgresql.JsonStringAdapter</td><td>String</td><td>JSON</td><td>\r
-Maps the JSON data type to a java.lang.String</td></tr>\r
-\r
-<tr><td>com.iciql.adapter.postgresql.JsonbStringAdapter</td><td>String</td><td>JSONB</td><td>\r
-Maps the JSONB data type to a java.lang.String</td></tr>\r
-\r
-<tr><td>com.iciql.adapter.postgresql.XmlStringAdapter</td><td>String</td><td>XML</td><td>\r
-Maps the XML data type to a java.lang.String</td></tr>\r
-\r
-</table>\r
+++ /dev/null
-## SQL DSL Examples\r
-\r
-Here are some examples of using the Iciql SQL DSL.\r
-\r
-### Select Statements\r
-\r
----JAVA---\r
-// select * from products\r
-List<Product> allProducts = db.from(p).select();\r
-\r
-// select * from customers where region='WA'\r
-Customer c = new Customer();\r
-List<Customer> waCustomers = db.from(c).where(c.region).is("WA").select();\r
-\r
-// select distinct customerId from customers where region='WA'\r
-Customer c = new Customer();\r
-List<String> customerIds = db.from(c).where(c.region).is("WA").selectDistinct(c.customerId);\r
-\r
-public static class ProductPrice {\r
- public String productName;\r
- public String category;\r
- public Double price;\r
-}\r
-\r
-// select with generation of new anonymous inner class\r
-List<ProductPrice> productPrices =\r
- db.from(p).\r
- orderBy(p.productId).\r
- select(new ProductPrice() {{\r
- productName = p.productName;\r
- category = p.category;\r
- price = p.unitPrice;\r
- }});\r
----JAVA---\r
-\r
-### Insert Statements\r
-\r
----JAVA---\r
-// single record insertion\r
-db.insert(singleProduct);\r
-\r
-// single record insertion with primary key retrieval\r
-Long key = db.insertAndGetKey(singleProduct);\r
-\r
-// batch record insertion\r
-db.insertAll(myProducts);\r
-\r
-// batch insertion with primary key retrieval\r
-List<Long> myKeys = db.insertAllAndGetKeys(list);\r
----JAVA---\r
-\r
-### Update Statements\r
-\r
----JAVA---\r
-// single record update\r
-db.update(singleProduct);\r
-\r
-// batch record updates\r
-db.updateAll(myProducts);\r
-\r
-// update query\r
-db.from(p).set(p.productName).to("updated")\r
- .increment(p.unitPrice).by(3.14)\r
- .increment(p.unitsInStock).by(2)\r
- .where(p.productId).is(1).update();\r
- \r
-// reusable, parameterized update query\r
-String q = db.from(p).set(p.productName).toParameter().where(p.productId).is(1).toSQL();\r
-db.executeUpdate(q, "Lettuce");\r
----JAVA---\r
-\r
-### Upsert/Merge Statements\r
-\r
-The Upsert or Merge methods will insert a new object if the primary key does not already exist or will update the record for the primary key.\r
- \r
----JAVA---\r
-Product pChang = db.from(p).where(p.productName).is("Chang").selectFirst();\r
-pChang.unitPrice = 19.5;\r
-pChang.unitsInStock = 16;\r
-db.merge(pChang);\r
----JAVA---\r
-\r
-### Delete Statements\r
-\r
----JAVA---\r
-// single record deletion\r
-db.delete(singleProduct); \r
-\r
-// batch record deletion\r
-db.deleteAll(myProducts);\r
-\r
-// delete query\r
-db.from(p).where(p.productId).atLeast(10).delete();\r
----JAVA---\r
-\r
-### Inner Join Statements\r
-\r
----JAVA---\r
-final Customer c = new Customer();\r
-final Order o = new Order();\r
-\r
-List<Customer> customersWithLargeOrders =\r
- db.from(c).\r
- innerJoin(o).on(c.customerId).is(o.customerId).\r
- where(o.total).greaterThan(new BigDecimal("500.00")).\r
- groupBy(c.customerId).select();\r
-\r
-List<CustOrder> orders =\r
- db.from(c).\r
- innerJoin(o).on(c.customerId).is(o.customerId).\r
- where(o.total).lessThan(new BigDecimal("500.00")).\r
- orderBy(1).\r
- select(new CustOrder() {{\r
- customerId = c.customerId;\r
- orderId = o.orderId;\r
- total = o.total;\r
- }});\r
----JAVA---\r
-\r
-### View Statements\r
-\r
----JAVA---\r
-// the view named "ProductView" is created from the "Products" table\r
-@IQView(viewTableName = "Products")\r
-public class ProductView {\r
-\r
- @IQColumn\r
- @IQConstraint("this >= 200 AND this < 300")\r
- Long id;\r
- \r
- @IQColumn\r
- String name;\r
-}\r
-\r
-final ProductView v = new ProductView();\r
-List<ProductView> allProducts = db.from(v).select();\r
-\r
-// this version of the view model "ProductView" inherits table metadata\r
-// from the Products class which is annotated with IQTable\r
-@IQView(inheritColumns = true)\r
-public class ProductView extends Products {\r
-\r
- // inherited BUT replaced to define the constraint\r
- @IQColumn\r
- @IQConstraint("this >= 200 AND this < 300")\r
- Long id;\r
- \r
- // inherited from Products\r
- //@IQColumn\r
- //String name;\r
-}\r
-\r
-final ProductView v = new ProductView();\r
-List<ProductView> allProducts = db.from(v).select();\r
-\r
-// in this example we are creating a view based on a fluent query\r
-// and using 2 levels of inheritance. IQConstraints are ignored\r
-// when using this approach because we are fluently defining them.\r
-@IQView(inheritColumns = true)\r
-public class ProductViewInherited extends ProductView {\r
-\r
-}\r
-\r
-final Products p = new Products();\r
-db.from(p).where(p.id).atLeast(200L).and(p.id).lessThan(300L).createView(ProductViewInherited.class);\r
-\r
-// now replace the view with a variation\r
-db.from(p).where(p.id).atLeast(250L).and(p.id).lessThan(350L).replaceView(ProductViewInherited.class);\r
-\r
-// now drop the view from the database\r
-db.dropView(ProductViewInherited.class);\r
----JAVA---\r
-\r
-### Dynamic Queries\r
-\r
-Dynamic queries skip all field type checking and, depending on which approach you use, may skip model class/table name checking too.\r
-\r
----JAVA---\r
-// where fragment with object parameters\r
-List<Product> restock = db.from(p).where("unitsInStock=? and productName like ? order by productId", 0, "Chef%").select();\r
-\r
-// parameterized query which can be cached and re-used later\r
-String q = db.from(p).where(p.unitsInStock).isParameter().and(p.productName).likeParameter().orderBy(p.productId).toSQL();\r
-List<Product> allProducts = db.executeQuery(Product.class, q, 0, "Chef%");\r
-\r
-// statement with binding to your model class\r
-List<Product> allProducts = db.executeQuery(Product.class, "select * from products");\r
-\r
-// statement with object parameters and binding to your model class\r
-List<Product> restock = db.executeQuery(Product.class, "select * from products where unitsInStock=?", 0);\r
-\r
-/**\r
- * If you want to process the intermediate ResultSet\r
- * yourself make sure to use the <i>closeSilently()</i> method \r
- * to ensure the parent statement is closed too.\r
- */\r
-ResultSet rs = db.executeQuery("select * from products");\r
-List<Product> allProducts = db.buildObjects(Product.class, rs);\r
-JdbcUtils.closeSilently(rs, true);\r
----JAVA---\r
+++ /dev/null
-## Overview\r
-\r
-iciql **is**...\r
-\r
-- a model-based, database access wrapper for JDBC\r
-- for modest database schemas and basic statement generation\r
-- for those who want to write code, instead of SQL, using IDE completion and compile-time type-safety\r
-- small (<250KB) with debug symbols and no runtime dependencies\r
-- pronounced *icicle* (although it could be French: *ici ql* - here query language)\r
-- a friendly fork of the H2 [JaQu][jaqu] subproject\r
-\r
-iciql **is not**...\r
-\r
-- a complete alternative to JDBC\r
-- designed to compete with more powerful database query tools like [jOOQ][jooq] or [QueryDSL][querydsl]\r
-- designed to compete with enterprise [ORM][orm] tools like [Hibernate][hibernate] or [mybatis][mybatis]\r
-\r
-### Fluent, type-safe SQL DSL with rich object mapping\r
-\r
-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.\r
-\r
----JAVA---\r
-try (Db db = Db.open("jdbc:h2:mem:iciql")) {\r
-\r
- db.insertAll(Product.getList());\r
- Product p = new Product();\r
- List<Product> restock = db.from(p).where(p.unitsInStock).is(0).select();\r
- List<Product> all = db.executeQuery(Product.class, "select * from products");\r
- \r
-}\r
----JAVA---\r
-\r
-### Dynamic, annotated DAO with standard crud operations\r
-\r
-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.\r
-\r
----JAVA---\r
-// Define your DAO with SQL annotations and optional type adapters\r
-public interface MyDao extends Dao {\r
-\r
- @SqlQuery("select * from Product where unitsInStock = 0")\r
- Product[] getProductsOutOfStock();\r
-\r
- @SqlQuery("select * from Product where productId = :id")\r
- Product getProduct(@Bind("id") long id);\r
- \r
- // retrieve a custom type from the matched row in the Invoices table\r
- @SqlQuery("select invoice from Invoices where id = :arg0")\r
- @InvoiceAdapter\r
- Invoice getInvoice(long id);\r
-\r
- // retrieve a custom type from the matched row in the Invoices table\r
- @SqlQuery("select invoice from Invoices where id = :p.invoiceId")\r
- @InvoiceAdapter\r
- Invoice getInvoice(@BindBean("p") Product product);\r
-\r
- // update a custom type for the matched row in the Invoices table\r
- @SqlStatement("update Invoices set invoice = :2 where id = :1")\r
- boolean updateInvoice(long id, @InvoiceAdapter Invoice invoice);\r
-\r
-}\r
-\r
-// Define a type adapter annotation for the Invoice object\r
-@Retention(RetentionPolicy.RUNTIME)\r
-@Target({ ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER })\r
-@TypeAdapter(InvoiceAdapterImpl.class)\r
-public @interface InvoiceAdapter { }\r
-\r
-// Create a DAO instance with your Db and work more clearly\r
-try (Db db = Db.open("jdbc:h2:mem:iciql")) {\r
-\r
- MyDao dao = db.open(MyDao.class);\r
- dao.insertAll(Product.getList());\r
- Product[] outofstock = dao.getProductsOutOfStock();\r
- Product p = dao.getProduct(1);\r
- Invoice i123 = dao.getInvoice(123);\r
- i123.approved = true;\r
- dao.updateInvoice(123, i123);\r
- \r
- // use the underlying Db instance for full-power\r
- dao.db().dropTable(Product.class);\r
-\r
-}\r
----JAVA---\r
-\r
-### Flexible field data types\r
-\r
-The [Data Type Adapter feature](dta.html) allows you to customize how your SQL column data types map to/from Java objects.\r
-\r
-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.\r
-\r
-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.\r
-\r
-### Runtime mode support\r
-\r
-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.\r
-\r
-### Supported Databases (Unit-Tested)\r
-- [H2](http://h2database.com) ${h2.version}\r
-- [HSQLDB](http://hsqldb.org) ${hsqldb.version}\r
-- [Derby](http://db.apache.org/derby) ${derby.version}\r
-- [MySQL](http://mysql.com) ${mysql.version}\r
-- [PostgreSQL](http://postgresql.org) ${postgresql.version}\r
-- [SQLite](http://www.sqlite.org) ${sqlite.version}\r
-\r
-Support for others is possible and may only require creating a simple "dialect" class.\r
-\r
-### Downloading\r
-\r
-As of 2.0.0 iciql is now distributed through Maven Central and it's coordinates have changed slightly.\r
-\r
----XML---\r
-<dependencies>\r
- <dependency>\r
- <groupId>com.gitblit.iciql</groupId>\r
- <artifactId>iciql</artifactId>\r
- <version>2.0.0</version>\r
- </dependency>\r
-</dependencies>\r
----XML---\r
-\r
-### Java Runtime Requirement\r
-\r
-iciql requires a Java 6 Runtime Environment (JRE) or a Java 6 Development Kit (JDK).\r
- \r
-### License\r
-iciql is distributed under the terms of the [Apache Software Foundation license, version 2.0][apachelicense]\r
-\r
-[jaqu]: http://h2database.com/html/jaqu.html "H2 JaQu project"\r
-[orm]: http://en.wikipedia.org/wiki/Object-relational_mapping "Object Relational Mapping"\r
-[jooq]: http://jooq.sourceforge.net "jOOQ"\r
-[querydsl]: http://www.querydsl.com/ "QueryDSL"\r
-[hibernate]: http://www.hibernate.org "Hibernate"\r
-[mybatis]: http://www.mybatis.org "mybatis"\r
-[github]: http://github.com/gitblit/iciql "iciql git repository"\r
-[apachelicense]: http://www.apache.org/licenses/LICENSE-2.0 "Apache License, Version 2.0"\r
+++ /dev/null
-\r
-## Comparison to JaQu \r
-\r
-This is an overview of the fundamental differences between the original JaQu project and the current featureset of iciql. \r
-\r
-<table class="table">\r
-<tr><th></th><th>Iciql</th><th>JaQu</th></tr>\r
-<tr><th colspan="3">core</th></tr>\r
-<tr><td>deployment</td><td>small, discrete library</td><td>depends on H2 database jar file</td></tr>\r
-<tr><td>databases</td><td>H2, HSQL, Derby, MySQL, PostreSQL, and SQLite</td><td>H2 only</td></tr>\r
-<tr><td>logging</td><td>console, SLF4J, or custom logging</td><td>console logging</td></tr>\r
-<tr><td>exceptions</td><td>always includes generated statement in exception, when available</td><td>--</td></tr>\r
-<tr><td>column mappings</td><td>wildcard queries index result sets by column name</td><td>all result sets built by field index<br/>this can fail for wildcard queries</td></tr>\r
-<tr><td>savepoints</td><td>bulk operations (insert, update, delete) use savepoints with rollback in the event of failure</td><td>--</td></tr>\r
-<tr><th colspan="3">syntax and api</th></tr>\r
-<tr><td>VIEWs</td><td>create readonly views either from a class definition or from a fluent statement</td><td>--</td></tr>\r
-<tr><td>Foreign Key Constraints</td><td>model classes may be annotated with foreign key constraints</td><td>--</td></tr>\r
-<tr><td>dynamic queries</td><td>methods and where clauses for dynamic queries that build iciql objects</td><td>--</td></tr>\r
-<tr><td>DROP</td><td>syntax to drop a table or view</td><td></td></tr>\r
-<tr><td>BETWEEN</td><td>syntax for specifying a BETWEEN x AND y clause</td><td>--</td></tr>\r
-<tr><td>(NOT) IN</td><td>syntax (oneOf, noneOf) for specifying a (NOT) IN clause</td><td>--</td></tr>\r
-<tr><td>compound nested conditions</td><td>WHERE (x = y OR x = z) AND (y = a OR y = b)</td><td>--</td></tr>\r
-<tr><td>dynamic DAOs</td><td>DAO interfaces with annotated statements may be declared and dynamically generated</td><td>--</td></tr>\r
-<tr><th colspan="3">types</th></tr>\r
-<tr><td>primitives</td><td>fully supported</td><td>--</td></tr>\r
-<tr><td>enums</td><td>fully supported</td><td>--</td></tr>\r
-<tr><td>DECIMAL(length,scale)</td><td>can specify length/precision and scale</td><td>--</td></tr>\r
-<tr><td>BOOLEAN</td><td>flexible mapping of boolean as bool, varchar, or int</td><td>--</td></tr>\r
-<tr><td>BLOB</td><td>partially supported <em>(can not be used in a WHERE clause)</em></td><td>--</td></tr>\r
-<tr><td>Custom</td><td>partially supported <em>uses custom-defined data type adapter (can not be used in a WHERE clause)</em></td><td>--</td></tr>\r
-<tr><td>UUID</td><td>fully supported <em>(H2 only)</em> </td><td>--</td></tr>\r
-<tr><th colspan="3">configuration</th></tr>\r
-<tr><td>DEFAULT values</td><td>set from annotation, <em>default object values</em>, or Define.defaultValue()</td><td>set from annotations</td></tr>\r
-<tr><td>Interface Configuration<br/>Mapped Fields</td><td><em>all fields</em> are mapped regardless of scope<br/>fields are ignored by annotating with @IQIgnore</td><td><em>all public fields</em> are mapped<br/>fields are ignored by reducing their scope</td></tr>\r
-<tr><td>Index names</td><td>can be set</td><td>--</td></tr>\r
-</table>\r
+++ /dev/null
-<div class="javadoc_nav">\r
-<a href="javadoc/overview-summary.html" target="javadoc">packages</a>\r
- | <a href="javadoc/overview-tree.html" target="javadoc">tree</a>\r
- | <a href="javadoc/deprecated-list.html" target="javadoc">deprecated</a>\r
- | <a href="javadoc/index-all.html" target="javadoc">index</a>\r
-</div>\r
-<iframe name="javadoc" src="javadoc/overview-summary.html" width="100%" height="650" frameborder="0"></iframe>\r
+++ /dev/null
-## Table Model Classes\r
-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.\r
-\r
-Models can be manually written using one of three approaches: *annotation configuration*, *interface configuration*, or *POJO configuration*. All approaches can be used within a project and all can be used within a single model class, although that is discouraged.\r
-\r
-Alternatively, model classes can be automatically generated by iciql using the model generation tool. Please see the [tools](tools.html) page for details.\r
-\r
-### Configuration Requirements and Limitations\r
-\r
-1. Your model class **must** provide a public default constructor.\r
-2. All **Object** fields are assumed NULLABLE unless explicitly set *@IQColumn(nullable = false)* or *Define.nullable(field, false)*.\r
-3. All **Primitive** fields are assumed NOT NULLABLE unless explicitly set *@IQColumn(nullable = true)* or *Define.nullable(field, true)*.\r
-4. Only the specified types are supported. Any other types are not supported.\r
-5. Triggers, views, and other advanced database features are not supported.\r
-\r
-### Standard Supported Data Types\r
-\r
----NOMARKDOWN---\r
-<table class="table">\r
-<tr><td colspan="3"><b>Fully Supported Types</b><br/>\r
-can be used for all iciql expressions\r
-</tr>\r
-<tr><th>Object</th><th>Primitive</th><th>SQL Type</th></tr>\r
-<tr><td>java.lang.String</td><td></td>\r
-<td>VARCHAR <em>(length > 0)</em> or CLOB <em>(length == 0)</em></td></tr>\r
- \r
-<tr><td>java.lang.Boolean</td><td>boolean</td>\r
-<td>BOOLEAN<br/><i>can only <b>declare and explicitly reference</b> one <u>primitive boolean</u> per model<br/>multiple primitives are allowed if not using where/set/on/and/or/groupBy/orderBy(boolean)</i></td></tr>\r
- \r
-<tr><td>java.lang.Byte</td><td>byte</td>\r
-<td>TINYINT</td></tr>\r
- \r
-<tr><td>java.lang.Short</td><td>short</td>\r
-<td>SMALLINT</td></tr>\r
- \r
-<tr><td>java.lang.Integer</td><td>int</td>\r
-<td>INT</td></tr>\r
- \r
-<tr><td>java.lang.Long</td><td>long</td>\r
-<td>BIGINT</td></tr>\r
- \r
-<tr><td>java.lang.Float</td><td>float</td>\r
-<td>REAL</td></tr>\r
- \r
-<tr><td>java.lang.Double</td><td>double</td>\r
-<td>DOUBLE</td></tr>\r
- \r
-<tr><td>java.math.BigDecimal</td><td> </td>\r
-<td>DECIMAL <em>(length == 0)</em> or DECIMAL(length,scale) <em>(length > 0)</em></td></tr>\r
- \r
-<tr><td>java.sql.Date</td><td> </td>\r
-<td>DATE</td></tr>\r
- \r
-<tr><td>java.sql.Time</td><td> </td>\r
-<td>TIME</td></tr>\r
- \r
-<tr><td>java.sql.Timestamp</td><td> </td>\r
-<td>TIMESTAMP</td></tr>\r
-\r
-<tr><td>java.util.Date</td><td> </td>\r
-<td>TIMESTAMP</td></tr>\r
-\r
-<tr><td>java.lang.Enum.name()<br/><em>default type</em></td><td></td>\r
-<td>VARCHAR <em>(length > 0)</em> or CLOB <em>(length == 0)</em><br/><em>EnumType.NAME</em><br/><i>can only <b>declare and explicitly reference</b> one instance of <u>each enum type</u> per model<br/>multiple instances of an enum type within a model is allowed if not using where/set/on/and/or/groupBy/orderBy(enum)</i></td></tr>\r
-\r
-<tr><td>java.lang.Enum.ordinal()</td><td> </td>\r
-<td>INT<br/><em>EnumType.ORDINAL</em><br/><i>can only <b>declare and explicitly reference</b> one instance of <u>each enum type</u> per model<br/>multiple instances of an enum type within a model is allowed if not using where/set/on/and/or/groupBy/orderBy(enum)</i></td></tr>\r
-\r
-<tr><td>java.lang.Enum implements<br/><em>com.iciql.Iciql.EnumId.enumId()</em></td><td> </td>\r
-<td><i>variable</i><br/><em>EnumType.ENUMID</em><br/><i>can only <b>declare and explicitly reference</b> one instance of <u>each enum type</u> per model<br/>multiple instances of an enum type within a model is allowed if not using where/set/on/and/or/groupBy/orderBy(enum)</i></td></tr>\r
-\r
-<tr><td colspan="3"><b>Partially Supported Types</b><br/>\r
-can not be directly referenced in an expression</td></tr>\r
-<tr><td>byte []</td> <td></td>\r
-<td>BLOB</td><tr/>\r
-<tr><td>Custom</td> <td>create a DataTypeAdapter<Custom></td>\r
-<td>Custom</td><tr/>\r
-\r
-<tr><td colspan="3"><b>H2 Database Types</b><br/>\r
-fully supported when paired with an H2 database \r
-</td></tr>\r
-<tr><td>java.util.UUID</td><td> </td>\r
-<td>UUID</td></tr>\r
-\r
-</table>\r
----NOMARKDOWN---\r
-**NOTE:**<br/>\r
-The reverse lookup used for model generation, SQL type -> Java type, contains more mappings.<br/>\r
-Please consult the `com.iciql.ModelUtils` class for details. \r
-\r
-## Annotation Configuration\r
-The recommended approach to setup a model class is to annotate the class and field declarations.\r
-\r
-### advantages\r
-\r
-- 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.\r
-- model runtime dependency is limited to the small, portable `com.iciql.Iciql` class file which contains the annotation definitions\r
-\r
-### disadvantages\r
-\r
-- more verbose model classes\r
-- indexes are defined using "fragile" string column names\r
-- compound primary keys are defined using "fragile" string column names\r
-\r
-### field mapping\r
-\r
-- By default, **ONLY** fields annotated with *@IQColumn* are mapped.\r
-- scope is irrelevant.\r
-- transient is irrelevant.\r
-\r
-### default values\r
-\r
-You may specify default values for an *@IQColumn* by either:\r
-\r
-1. specifying the default value string within your annotation<br/>\r
-**NOTE:**<br/>\r
-The annotated default value always takes priority over a field default value.\r
----JAVA---\r
-// notice the single ticks!\r
-@IQColumn(defaultValue="'2000-01-01 00:00:00'")\r
-Date myDate;\r
----JAVA---\r
-\r
-2. setting a default value on the field<br/>\r
-**NOTE:**<br/>\r
-Primitive types have an implicit default value of *0* or *false*.\r
----JAVA---\r
-@IQColumn\r
-Date myDate = new Date(100, 0, 1);\r
-\r
-@IQColumn\r
-int myId;\r
----JAVA---\r
-\r
-If you want to specify a database-specific variable or function as your default value (e.g. CURRENT_TIMESTAMP) you must do that within the annotation. Also note that the *IQColumn.defaultValue* must be a well-formatted SQL DEFAULT expression whereas object defaults will be automatically converted to an SQL DEFAULT expression.\r
-\r
-### Special Case: primitive autoincrement fields and 0\r
----JAVA---\r
-@IQColumn(autoIncrement = true)\r
-int myId;\r
----JAVA---\r
-\r
-Because primitive types have implicit default values, this field will be excluded from an INSERT statement if its value is 0. Iciql can not differentiate an implicit/uninitialized 0 from a explicitly assigned 0.\r
-\r
-### Example Annotated Model\r
----JAVA---\r
-import com.iciql.Iciql.EnumType;\r
-import com.iciql.Iciql.IQColumn;\r
-import com.iciql.Iciql.IQEnum;\r
-import com.iciql.Iciql.IQIndex;\r
-import com.iciql.Iciql.IQTable;\r
-\r
-@IQTable\r
-@IQIndexes({\r
- @IQIndex({"productName", "category"}),\r
- @IQIndex(name="nameindex", value="productName")\r
-})\r
-public class Product {\r
-\r
- @IQEnum(EnumType.ORDINAL)\r
- public enum Availability {\r
- ACTIVE, DISCONTINUED;\r
- }\r
-\r
- @IQColumn(primaryKey = true)\r
- public Integer productId;\r
- \r
- @IQColumn(length = 200, trim = true)\r
- public String productName;\r
- \r
- @IQColumn(length = 50, trim = true)\r
- public String category;\r
- \r
- @IQColumn\r
- public Double unitPrice;\r
- \r
- @IQColumn(name = "units")\r
- public Integer unitsInStock;\r
- \r
- @IQColumn\r
- private Integer reorderQuantity;\r
- \r
- @IQColumn\r
- private Availability availability;\r
- \r
- @IQColumn(typeAdapter = MyCustomClassAdapter.class)\r
- private MyCustomClass;\r
- \r
- // ignored because it is not annotated AND the class is @IQTable annotated\r
- private Integer ignoredField;\r
- \r
- public Product() {\r
- // default constructor\r
- }\r
-}\r
----JAVA---\r
-\r
-### Foreign Keys\r
-\r
----JAVA---\r
-@IQTable(name = "AnnotatedProduct", primaryKey = "id")\r
-@IQIndexes({ @IQIndex({ "name", "cat" }), @IQIndex(name = "nameidx", type = IndexType.HASH, value = "name") })\r
-@IQContraintForeignKey(\r
- foreignColumns= { "cat" }, \r
- referenceName = "AnnotatedCategory",\r
- referenceColumns = { "categ" },\r
- deleteType = ConstraintDeleteType.CASCADE\r
-)\r
-public class ProductAnnotationOnlyWithForeignKey {\r
-\r
- public String unmappedField;\r
-\r
- @IQColumn(name = "id", autoIncrement = true)\r
- public Long productId;\r
-\r
- @IQColumn(name = "cat", length = 15, trim = true)\r
- public String category;\r
-\r
- @IQColumn(name = "name", length = 50)\r
- public String productName;\r
-\r
- @SuppressWarnings("unused")\r
- @IQColumn\r
- private Double unitPrice;\r
-\r
- @IQColumn\r
- private Integer unitsInStock;\r
-}\r
----JAVA---\r
-\r
-### Views with Field Constraints\r
----JAVA---\r
-@IQView(name = "AnnotatedProductView", tableName = "AnnotatedProduct")\r
-public class ProductView {\r
-\r
- public String unmappedField;\r
-\r
- @IQColumn(name = "id", autoIncrement = true)\r
- @IQConstraint("this <= 7 AND this > 2")\r
- public Long productId; \r
- @IQColumn(name = "name")\r
- public String productName;\r
-\r
- public String toString() {\r
- return productName + " (" + productId + ")";\r
- }\r
-}\r
----JAVA---\r
-\r
-## Interface Configuration\r
-Alternatively, you may map your model classes using the interface approach by implementing the `com.iciql.Iciql` interface.\r
-\r
-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.\r
-\r
-The `com.iciql.Iciql` interface specifies a single method, *defineIQ()*. In your implementation of *defineIQ()* you would use static method calls to set:\r
-\r
-- the schema name\r
-- the table name (if it's not the class name)\r
-- the column name (if it's not the field name)\r
-- the max length and trim of a string field\r
-- the precision and scale of a decimal field\r
-- the autoincrement flag of a long or integer field\r
-- the nullable flag of a field \r
-- the primaryKey (single field or compound)\r
-- any indexes (single field or compound)\r
-\r
-### advantages\r
-\r
-- less verbose model class\r
-- compile-time index definitions\r
-- compile-time compound primary key definitions\r
-\r
-### disadvantages\r
-\r
-- model runtime dependency on entire iciql library\r
-- *defineIQ()* is called from a static synchronized block which may be a bottleneck for highly concurrent systems\r
-\r
-### field mapping\r
-\r
-- **ALL** fields are mapped unless annotated with *@IQIgnore*.\r
-- scope is irrelevant.\r
-- transient is irrelevant.\r
-\r
-### default values\r
-\r
-You may specify default values for an field by either:\r
-\r
-1. specifying the default value string within your *defineIQ()* method<br/>\r
-**NOTE:**<br/>\r
-The defineIQ() value always takes priority over a field default value.\r
----JAVA---\r
-Date myDate;\r
-\r
-public void defineIQ() {\r
- // notice the single ticks!\r
- Define.defaultValue(myDate, "'2000-01-01 00:00:00'");\r
-}\r
----JAVA---\r
-\r
-2. setting a default value on the field<br/>\r
-**NOTE:**<br/>\r
-Primitive types have an implicit default value of *0* or *false*.\r
----JAVA---\r
-Date myDate = new Date(100, 0, 1);\r
-\r
-int myId;\r
----JAVA---\r
-\r
-### Example Interface Model\r
----JAVA---\r
-import com.iciql.Iciql;\r
-import com.iciql.Iciql.IQIgnore;\r
-\r
-public class Product implements Iciql {\r
- public Integer productId;\r
- public String productName;\r
- public String category;\r
- public Double unitPrice;\r
- public Integer unitsInStock;\r
- \r
- @IQIgnore\r
- Integer reorderQuantity;\r
- \r
- public Product() {\r
- }\r
- \r
- @Override\r
- public void defineIQ() {\r
- com.iciql.Define.primaryKey(productId);\r
- com.iciql.Define.columnName(unitsInStock, "units");\r
- com.iciql.Define.length(productName, 200);\r
- com.iciql.Define.length(category, 50);\r
- com.iciql.Define.index(productName, category);\r
- }\r
-}\r
----JAVA---\r
-\r
-## POJO (Plain Old Java Object) Configuration\r
-\r
-This approach is very similar to the *interface configuration* approach; it is the least verbose and also the least useful.\r
-\r
-This approach would be suitable for quickly modeling an existing table where only SELECT and INSERT statements will be generated.\r
-\r
-### advantages\r
-\r
-- nearly zero-configuration\r
-\r
-### disadvantages\r
-\r
-- can not execute DELETE, UPDATE, or MERGE statements (they require a primary key specification)\r
-- table name MUST MATCH model class name\r
-- column names MUST MATCH model field names\r
-- can not specify any column attributes\r
-- can not specify indexes\r
-\r
-### field mapping\r
-\r
-- **ALL** fields are mapped unless annotated with *@IQIgnore*.\r
-- scope is irrelevant.\r
-- transient is irrelevant.\r
-\r
-### default values\r
-\r
-You may specify a default value on the field.\r
-\r
-**NOTE:**<br/>\r
-Primitive types have an implicit default value of *0* or *false*.\r
----JAVA---\r
-Date myDate = new Date(100, 0, 1);\r
-\r
-int myId;\r
----JAVA---\r
-\r
-### Example POJO Model\r
----JAVA---\r
-import com.iciql.Iciql.IQIgnore;\r
-\r
-public class Product {\r
- public Integer productId;\r
- public String productName;\r
- public String category;\r
- public Double unitPrice;\r
- public Integer units;\r
- \r
- @IQIgnore\r
- Integer reorderQuantity;\r
- \r
- public Product() {\r
- } \r
-}\r
----JAVA---\r
+++ /dev/null
-\r
-## Performance\r
-\r
-The information provided here may be based on flawed test procedures. You have to be the judge of what is performant and non-performant.\r
-\r
-### iciql statement generation\r
-\r
-Performance of iciql statement generation is not currently benchmarked.\r
-\r
-### iciql+database performance comparison\r
-\r
-The following data was generated by running the *single-threaded* iciql test suite. All database connections are pooled and re-used within each execution of the test suite using [Apache Commons DBCP](http://commons.apache.org/dbcp).\r
-\r
-Connections are pooled to normalize embedded database performance with out-of-process database performance. Some of the Java embedded database configurations have a very high startup-time penalty. Notably, H2 is slow to open a database and its performance is substantially affected if connection pooling is not enabled to keep the embedded database open.\r
-\r
-SQLite uses the default [DELETE journaling mode](https://www.sqlite.org/lockingv3.html#rollback). About a 4x performance improvement can be achieved when using the [WAL journaling mode](https://www.sqlite.org/wal.html) (`PRAGMA journal_mode = WAL`).\r
-\r
-External process databases (MySQL & PostgreSQL) use the default settings as provided by the platform.\r
-\r
-All tables are created as CACHED when the database distinguishes between CACHED and MEMORY tables.\r
- \r
-All performance numbers include the combined overhead of iciql statement generation and JUnit 4 test framework execution so they are not bare-metal database metrics.\r
-\r
-All bulk operations (insertAll, updateAll, deleteAll, etc) automatically create savepoints, if supported by the JDBC connector, to help ensure atomicity of the operation.\r
-\r
-<pre>\r
-%DBPERFORMANCE%\r
-</pre>
\ No newline at end of file
+++ /dev/null
-/site_analytics.html
-/site_ads.html
+++ /dev/null
-/* Javadoc style sheet */\r
-\r
-/* Define colors, fonts and other style attributes here to override the defaults */\r
-\r
-/* Page background color */\r
-body { font-size:13px; background-color: #FFFFFF; color:#000000 }\r
-\r
-hr { \r
- color: #ffffff;\r
- background-color: #ffffff;\r
- height: 1px; !important\r
-}\r
-\r
-/* Headings */\r
-h1 { font-size: 1.5em }\r
-h2 { font-size: 1.5em }\r
-\r
-table {\r
- border: 1px solid #ccc; !important \r
-}\r
-\r
-table th {\r
- border: 0px solid #ccc; !important\r
- font-size: 1.0em; !important\r
-}\r
-\r
-table th font { \r
- font-size: 1.3em; !important\r
-}\r
-\r
-table td {\r
- border: 0px solid; !important\r
-}\r
-\r
-/* Table colors */\r
-.TableHeadingColor { background-color: #f0f0f0; } /* light gray */\r
-.TableSubHeadingColor { background-color: #f0f0f0; } /* light gray */\r
-.TableRowColor { } \r
-\r
-/* Font used in left-hand frame lists */\r
-.FrameTitleFont { }\r
-.FrameHeadingFont { }\r
-.FrameItemFont { }\r
-\r
-/* Navigation bar fonts and colors */\r
-.NavBarCell1 { background-color:#f0f0f0; } /* light gray */\r
-.NavBarCell1Rev { background-color:#00008B; color:#ffffff} /* Dark Blue */\r
-.NavBarFont1 { }\r
-.NavBarFont1Rev { color:#ffffff;}\r
-\r
-.NavBarCell2 { }\r
-.NavBarCell3 { }
\ No newline at end of file
+++ /dev/null
-## Database & Table Versioning\r
-\r
-Iciql supports an optional, simple versioning mechanism. There are two parts to the mechanism.\r
-\r
-1. You must supply an implementation of `com.iciql.DbUpgrader` to your `com.iciql.Db` instance.\r
-2. One or more of your table model classes must specify the `IQVersion(version)` annotation<br/>\r
-AND/OR<br/>\r
-Your `com.iciql.DbUpgrader` implementation must specify the `IQVersion(version)` annotation\r
-\r
-### How does it work?\r
-If you choose to use versioning, iciql will maintain a table within your database named *iq_versions* which is defined as:\r
-\r
- CREATE TABLE IQ_VERSIONS(SCHEMANAME VARCHAR(255) NOT NULL, TABLENAME VARCHAR(255) NOT NULL, VERSION INT NOT NULL)\r
- \r
-This database table is automatically created if and only if at least one of your model classes specifies a *version* > 0.\r
-\r
-When you generate a statement, iciql will compare the annotated version field of your model class to its last known value in the *iq_versions* table. If *iq_versions* lags behind the model annotation, iciql will immediately call the registered `com.iciql.DbUpgrader` implementation before generating and executing the current statement.\r
-\r
-When an upgrade scenario is identified, the current version and the annotated version information is passed to either:\r
-\r
-- `DbUpgrader.upgradeDatabase(db, fromVersion, toVersion)`\r
-- `DbUpgrader.upgradeTable(db, schema, table, fromVersion, toVersion)`\r
-\r
-both of which allow for non-linear upgrades. If the upgrade method call is successful and returns *true*, iciql will update the *iq_versions* table with the annotated version number.\r
-\r
-The actual upgrade procedure is beyond the scope of iciql and is your responsibility to implement. This is simply a mechanism to automatically identify when an upgrade is necessary.\r
-\r
-**NOTE:**<br/>\r
-The database entry of the *iq_versions* table is specified as SCHEMANAME='' and TABLENAME=''.\r
-\r
-### Effective use of Versioning with a DAO\r
-\r
-When Iciql identifies that a version upgrade is necessary it will call the appropriate method and give you a `Db` instance. With the `Db` instance you may open a version-specific [DAO](dao.html) instance that could give you a clean way to define all your upgrade commands.\r
-\r
----JAVA---\r
-public interface V2Upgrade extends Dao {\r
-\r
- @SqlStatement("ALTER TABLE PRODUCT ADD COLUMN TEST INT DEFAULT 0")\r
- void updateProductTable();\r
- \r
- @SqlStatement("UPDATE PRODUCT SET CATEGORY = :new WHERE CATEGORY = :old"")\r
- void renameCategory(@Bind("old") String oldName, @Bind("new") String newName);\r
-}\r
-\r
-public class MyUpgrader implements DbUpgrader {\r
-\r
- public boolean upgradeDatabase(Db db, int fromVersion, int toVersion) {\r
- \r
- if (2 == toVersion) {\r
- V2Upgrade dao = db.open(V2Upgrade.class);\r
- dao.updateProductTable();\r
- dao.renameCategory("Condiments", "Dressings");\r
- return true;\r
- }\r
- \r
- return false;\r
- }\r
-\r
----JAVA---
\ No newline at end of file
+++ /dev/null
-<#include "macros.ftl">\r
-<@AtomMacro posts=releases posturl="${project.url}/history.html#" />
\ No newline at end of file
+++ /dev/null
-<#macro LogMacro title version date description log logTitle="">\r
- <#if log??>\r
- <h3 id="${version}" class="section"><a href="#${version}" class="sectionlink"><i class="icon-share-alt"> </i></a>${title} (${version}) <small>${description}</small></h3>\r
- <table class="table">\r
- <tbody>\r
- <tr>\r
- <td style="background-color:inherit;width:100px">${date}</td>\r
- <td style="background-color:inherit;"><@LogDescriptionMacro log=log title=logTitle /></td>\r
- </tr>\r
- </tbody>\r
- </table>\r
- </#if>\r
-</#macro>\r
-\r
-<#macro LogDescriptionMacro log title=log.title>\r
- <#if (title!?length > 0)>\r
- <p class="lead">${title}</p> \r
- </#if>\r
- \r
- <#if (log.html!?length > 0)>\r
- <p>${log.html}</p>\r
- </#if>\r
- \r
- <#if (log.text!?length > 0)>\r
- <blockquote><p>${log.text!?html?replace("\n", "<br />")}</p></blockquote> \r
- </#if>\r
-\r
- <#if (log.note!?length > 0)>\r
- <div class="alert alert-info">\r
- <h4>Note</h4>\r
- ${log.note?html?replace("\n", "<p />")}\r
- </div>\r
- </#if>\r
-\r
- <#if (log.security!?size > 0)>\r
- <@SecurityListMacro title="security" list=log.security/>\r
- </#if>\r
- <#if (log.fixes!?size > 0)>\r
- <@UnorderedListMacro title="fixes" list=log.fixes />\r
- </#if>\r
- <#if (log.changes!?size > 0)>\r
- <@UnorderedListMacro title="changes" list=log.changes />\r
- </#if>\r
- <#if (log.additions!?size > 0)>\r
- <@UnorderedListMacro title="additions" list=log.additions />\r
- </#if>\r
- <#if (log.settings!?size > 0)>\r
- <@SettingsTableMacro title="new settings" list=log.settings /> \r
- </#if>\r
- <#if (log.dependencyChanges!?size > 0)>\r
- <@UnorderedListMacro title="dependency changes" list=log.dependencyChanges />\r
- </#if>\r
- <#if (log.contributors!?size > 0)>\r
- <@UnorderedListMacro title="contributors" list=log.contributors?sort />\r
- </#if> \r
-</#macro>\r
-\r
-<#macro SecurityListMacro list title>\r
- <h4 style="color:red;">${title}</h4>\r
- <ul>\r
- <#list list as item>\r
- <li>${item?html?replace("\n", "<br/>")}</li>\r
- </#list>\r
- </ul>\r
-</#macro>\r
-\r
-<#macro UnorderedListMacro list title>\r
- <h4>${title}</h4>\r
- <ul>\r
- <#list list as item>\r
- <li>${item?html?replace("\n", "<br/>")}</li>\r
- </#list>\r
- </ul>\r
-</#macro>\r
-\r
-<#macro SettingsTableMacro list title>\r
- <h4>${title}</h4>\r
- <table class="table">\r
- <#list list as item>\r
- <tr>\r
- <td><em>${item.name}</em></td><td>${item.defaultValue}</td>\r
- </tr>\r
- </#list>\r
- </table>\r
-</#macro>\r
-\r
-<#macro RssMacro posts posturl>\r
-<?xml version="1.0" standalone='yes'?>\r
-<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/">\r
- <channel>\r
- <title><![CDATA[${project.name}]]></title>\r
- <link>${project.url}</link>\r
- <description><![CDATA[${project.description}]]></description>\r
- <generator>Moxie Toolkit</generator>\r
- <#list posts as post>\r
- <item>\r
- <title><![CDATA[${post.title}]]></title>\r
- <link><![CDATA[${posturl}${post.id}]]></link>\r
- <guid isPermaLink="true">${posturl}${post.id}</guid>\r
- <#if (post.text!?length > 0)>\r
- <description><![CDATA[${post.text}]]></description>\r
- </#if>\r
- <#if (post.keywords!?size > 0)>\r
- <#list post.keywords as keyword>\r
- <category><![CDATA[${keyword}]]></category>\r
- </#list>\r
- </#if>\r
- <#if (post.author!?length > 0)>\r
- <dc:creator><![CDATA[${post.author}]]></dc:creator>\r
- <#else>\r
- <dc:creator><![CDATA[${project.name}]]></dc:creator>\r
- </#if>\r
- <pubDate>${post.date?string("EEE, dd MMM yyyy HH:mm:ss Z")}</pubDate>\r
- </item>\r
- </#list>\r
- </channel>\r
-</rss>\r
-</#macro>\r
-\r
-<#macro AtomMacro posts posturl>\r
-<?xml version="1.0" standalone='yes'?>\r
-<feed xmlns="http://www.w3.org/2005/Atom">\r
- <generator uri="${project.url}" version="${project.version}">${project.name}</generator>\r
- <title><![CDATA[${project.name}]]></title>\r
- <updated>${project.releaseDate}</updated>\r
- <#list posts as post>\r
- <entry>\r
- <content type="text/plain" />\r
- <title type="text"><![CDATA[${post.title}]]></title>\r
- <#if (post.text!?length > 0)>\r
- <summary type="text"><![CDATA[${post.text}]]></summary>\r
- </#if>\r
- <link href="${posturl}${post.id}" rel="via" />\r
- <guid isPermaLink="true">${posturl}${post.id}</guid>\r
- <#if (post.text!?length > 0)>\r
- <content><![CDATA[${post.text}]]></content>\r
- </#if>\r
- <#if (post.keywords!?size > 0)>\r
- <#list post.keywords as keyword>\r
- <category label="<![CDATA[${keyword}]]>" />\r
- </#list>\r
- </#if>\r
- <published>${post.date?string("yyyy-MM-dd'T'HH:mm:ssZ")}</published>\r
- </entry>\r
- </#list>\r
-</feed>\r
-</#macro>
\ No newline at end of file
+++ /dev/null
-<#include "macros.ftl" >
-
-<!-- CURRENT RELEASE -->
-<@LogMacro
- title="Current Release"
- log=release
- version=project.releaseVersion
- date=reference.releaseDate?string("yyyy-MM-dd")
- description="this is the current stable release" />
-
-<!-- NEXT RELEASE -->
-<#if snapshot??>
-<@LogMacro
- title="Next Release"
- log=snapshot
- version=project.version
- date="PENDING"
- description="these changes are queued for an upcoming release" />
-</#if>
-
-<div>
- <ul class="pager">
- <li class="next"><a href="releases.html">All Releases →</a></li>
- </ul>
-</div>
+++ /dev/null
-<#include "macros.ftl" >
-
-<!-- HISTORY -->
-<#if (releases!?size > 0)>
- <p></p>
- <h2>All Releases</h2>
- <table class="table">
- <tbody>
- <!-- RELEASE HISTORY -->
- <#list releases?sort_by("date")?reverse as log>
- <tr id="${log.id}">
- <td style="width:100px" id="${log.id}">
- <b><a href="#${log.id}">${log.id}</a></b><br/>
- ${log.date?string("yyyy-MM-dd")}
- </td>
- <td><@LogDescriptionMacro log=log /></td>
- </tr>
- </#list>
- </tbody>
- </table>
-</#if>
\ No newline at end of file
+++ /dev/null
-<#include "macros.ftl">\r
-<@RssMacro posts=releases posturl="${project.url}/releases.html#" />
\ No newline at end of file
+++ /dev/null
-## Model Generation\r
-If you do not have or do not want to annotate your existing model classes, you can use the included model generation tool to create iciql model classes.\r
-\r
----FIXED---\r
- win: java -cp iciql.jar;your_db_driver.jar <parameters>\r
-*nix: java -cp iciql.jar:your_db_driver.jar <parameters>\r
----FIXED---\r
-\r
-### Parameters\r
-<table class="table">\r
-<tr><th>-url</th><td>JDBC url for the database</td><td><em>REQUIRED</em></td></tr>\r
-<tr><th>-username</th><td>username for JDBC connection</td><td><em>optional</em></td></tr>\r
-<tr><th>-password</th><td>password for JDBC connection</td><td><em>optional</em></td></tr>\r
-<tr><th>-schema</th><td>the target schema for model generation</td><td><em>default:</em> all schemas</td></tr>\r
-<tr><th>-table</th><td>the target table for model generation</td><td><em>default:</em> all tables</td></tr>\r
-<tr><th>-package</th><td>the destination package name for generated models</td><td><em>default:</em> default package</td></tr>\r
-<tr><th>-folder</th><td>the output folder for .java files</td><td><em>default:</em> current folder</td></tr>\r
-<tr><th>-annotateSchema</th><td>include the schema name in the class annotations</td><td><em>default:</em> true</td></tr>\r
-<tr><th>-trimStrings</th><td>annotate trimStrings=true for any VARCHAR string mappings </td><td><em>default:</em> false</td></tr>\r
-</table>\r
-\r
-## Model Validation\r
-Iciql can validate your model classes against your database to ensure that your models are optimally defined and are consistent with the current table and index definitions.\r
-\r
-Each `com.iciql.ValidationRemark` returned by the validation has an associated level from the following enum:\r
----JAVA---\r
-public static enum Level {\r
- CONSIDER, WARN, ERROR;\r
-}\r
----JAVA---\r
-\r
-A typical validation may output recommendations for adjusting a model field annotation such as setting the *maxLength* of a string to match the length of its linked VARCHAR column.\r
-\r
-### Sample Model Validation using JUnit 4\r
----JAVA---\r
-import static org.junit.Assert.assertTrue;\r
-\r
-import java.sql.SQLException;\r
-\r
-import org.junit.After;\r
-import org.junit.Before;\r
-import org.junit.Rule;\r
-import org.junit.Test;\r
-import org.junit.rules.ErrorCollector;\r
-\r
-import com.iciql.Db;\r
-import com.iciql.DbInspector;\r
-import com.iciql.ValidationRemark;\r
-import com.iciql.test.models.Product;\r
-import com.iciql.test.models.ProductAnnotationOnly;\r
-import com.iciql.test.models.ProductMixedAnnotation;\r
-\r
-public class ValidateModels {\r
-\r
- /*\r
- * The ErrorCollector Rule allows execution of a test to continue after the\r
- * first problem is found and report them all at once\r
- */\r
- @Rule\r
- public ErrorCollector errorCollector = new ErrorCollector();\r
- \r
- private Db db;\r
- \r
- @Before\r
- public void setUp() {\r
- db = Db.open("jdbc:h2:mem:", "sa", "sa");\r
- }\r
-\r
- @After\r
- public void tearDown() {\r
- db.close();\r
- }\r
- \r
- @Test\r
- public void testValidateModels() {\r
- DbInspector inspector = new DbInspector(db);\r
- validateModel(inspector, new Product());\r
- validateModel(inspector, new ProductAnnotationOnly());\r
- validateModel(inspector, new ProductMixedAnnotation());\r
- }\r
- \r
- private void validateModel(DbInspector inspector, Object o) {\r
- List<ValidationRemark> remarks = inspector.validateModel(o, false);\r
- assertTrue("Validation remarks are null for " + o.getClass().getName(), remarks != null);\r
- log("Validation remarks for " + o.getClass().getName());\r
- for (ValidationRemark remark : remarks) {\r
- log(remark.toString());\r
- if (remark.isError()) {\r
- errorCollector.addError(new SQLException(remark.toString()));\r
- }\r
- }\r
- }\r
- \r
- private void log(String message) {\r
- System.out.println(message);\r
- }\r
-}\r
----JAVA---
\ No newline at end of file
+++ /dev/null
-## SQL DSL Usage\r
-\r
-Aside from this brief usage guide, please consult the [DSL examples](examples.html), the [javadoc](javadoc.html) and the [source code](${project.scmUrl}).\r
-\r
-### Instantiating a Db\r
-\r
-Use one of the static utility methods to instantiate a Db instance:\r
-\r
----JAVA---\r
-Db.open(String url, String user, String password);\r
-Db.open(String url, String user, char[] password);\r
-Db.open(Connection conn);\r
-Db.open(DataSource dataSource);\r
----JAVA---\r
- \r
-### Compile-Time Statements\r
-\r
-You compose your statements using the builder pattern where each method call returns an object that is used to specify the next part of the statement. Through clever usage of generics, pioneered by the original JaQu project, compile-time safety flows through the statement.\r
-\r
----JAVA---\r
-Db db = Db.open("jdbc:h2:mem:", "sa", "sa");\r
-db.insertAll(Product.getList());\r
-db.insertAll(Customer.getList());\r
-\r
-List<Product> restock =\r
- db.from(p).\r
- where(p.unitsInStock).\r
- is(0).orderBy(p.productId).select();\r
- \r
-for (Product product : restock) {\r
- db.from(p).\r
- set(p.unitsInStock).to(25).\r
- where(p.productId).is(product.productId).update();\r
-}\r
-db.close();\r
----JAVA---\r
- \r
-Please see the [examples](examples.html) page for more code samples. \r
- \r
-### Dynamic Runtime Queries\r
-\r
-Iciql gives you compile-time type-safety, but it becomes inconvenient if your design requires more dynamic statement generation. For these scenarios iciql offers some runtime query support through a hybrid approach or a pure JDBC approach.\r
-\r
-#### Where String Fragment Approach\r
-This approach is a mixture of iciql and jdbc. It uses the traditional prepared statement *field=?* tokens with iciql compile-time model class type checking. There is no field token type-safety checking.\r
----JAVA---\r
-List<Product> restock = db.from(p).where("unitsInStock=? and productName like ? order by productId", 0, "Chef%").select();\r
----JAVA---\r
-\r
-#### Db.executeQuery Approaches\r
-There may be times when the hybrid approach is still too restrictive and you'd prefer to write straight SQL. You can do that too and use iciql to build objects from your ResultSet, but be careful:\r
-\r
-1. Make sure to _select *_ in your query otherwise db.buildObjects() will throw a RuntimeException\r
-2. There is no model class type checking nor field type checking. \r
-\r
----JAVA---\r
-List<Product> allProducts = db.executeQuery(Product.class, "select * from products");\r
-List<Product> restock = db.executeQuery(Product.class, "select * from products where unitsInStock=?", 0);\r
-\r
-// parameterized query which can be cached and re-used later\r
-String q = db.from(p).where(p.unitsInStock).isParameter().toSQL();\r
-List<Product> restock = db.executeQuery(Product.class, q, 0);\r
----JAVA---\r
-\r
-Or if you want access to the raw *ResultSet* before building your model object instances...\r
-\r
----JAVA---\r
-ResultSet rs = db.executeQuery("select * from products");\r
-List<Product> allProducts = db.buildObjects(Product.class, rs);\r
-// This method ensures the creating statement is closed\r
-JdbcUtils.closeSilently(rs, true);\r
----JAVA---\r
-\r
-### Compound Nested Conditions\r
-\r
-It is possible to specify type-safe compound nested conditions in your WHERE clauses using `And` and `Or` statements.\r
-\r
----JAVA---\r
-final Customer model = new Customer();\r
-\r
-// SELECT * FROM CUSTOMERS\r
-// WHERE customerId IS NOT NULL\r
-// AND region IS NOT NULL\r
-// AND (\r
-// region = 'LA' OR region = 'CA'\r
-// )\r
-List<Customer> regionals = db.from(model)\r
- .where(model.customerId).isNotNull()\r
- .and(model.region).isNotNull()\r
- .and(new Or<Customer>(db, model) {{\r
- or(model.region).is("LA");\r
- or(model.region).is("CA");\r
- }});\r
----JAVA---\r
-\r
-### Finding Matches for a List of Values\r
-\r
-You can use SQL's *IN* WHERE clause with the `oneOf` or `noneOf` conditions.\r
-\r
----JAVA---\r
-final Customer model = new Customer();\r
-\r
-List<Customer> regionals = db.from(model).where(model.region).oneOf("CA", "LA");\r
-List<Customer> others = db.from(model).where(model.region).noneOf("CA", "LA");\r
-\r
----JAVA---\r
-\r
-### Read-only Views\r
-\r
-View model classes can inherit their field definitions from a parent table model class.\r
-\r
----JAVA---\r
-@IQView(name = "AnnotatedProductViewInherited", inheritColumns = true)\r
-public class ProductViewFromQuery extends ProductAnnotationOnly {\r
-\r
- public String unmappedField;\r
-\r
- @IQColumn(name = "id")\r
- public Long productId;\r
-\r
- public String toString() {\r
- return productName + " (" + productId + ")";\r
- }\r
-}\r
----JAVA---\r
-\r
-You can then create or replace the VIEW in the database using a fluent syntax.\r
-\r
----JAVA---\r
-// create view from query\r
-ProductAnnotationOnly product = new ProductAnnotationOnly();\r
-db.from(product).where(product.productId).exceeds(2L)\r
- .and(product.productId).atMost(7L).createView(ProductViewFromQuery.class);\r
- \r
-// select from the created view\r
-ProductViewFromQuery view = new ProductViewFromQuery();\r
-List<ProductViewFromQuery> products = db.from(view).select();\r
- \r
-// replace the view\r
-db.from(product).where(product.productId).exceeds(3L)\r
- .and(product.productId).atMost(8L).replaceView(ProductViewFromQuery.class);\r
- \r
-// select from the replaced view\r
-products = db.from(view).select();\r
----JAVA---\r
-\r
-### Natural Syntax\r
-\r
-<span class="alert alert-warning">Not Actively Developed</span>\r
-\r
-The original JaQu source offers partial support for Java expressions in *where* clauses.\r
-\r
-This works by decompiling a Java expression, at runtime, to an SQL condition. The expression is written as an anonymous inner class implementation of the `com.iciql.Filter` interface.\r
-\r
-A proof-of-concept decompiler is included, but is incomplete.\r
-\r
-The proposed syntax is:\r
----JAVA---\r
-long count = db.from(co).\r
- where(new Filter() { public boolean where() {\r
- return co.id == x\r
- && co.name.equals(name)\r
- && co.value == new BigDecimal("1")\r
- && co.amount == 1L\r
- && co.birthday.before(new java.util.Date())\r
- && co.created.before(java.sql.Timestamp.valueOf("2005-05-05 05:05:05"))\r
- && co.time.before(java.sql.Time.valueOf("23:23:23"));\r
- }\r
- }).selectCount();\r
----JAVA---\r
-\r
-### JDBC Statements, ResultSets, and Exception Handling\r
-\r
-Iciql opens and closes all JDBC objects automatically. SQLExceptions thrown during execution of a statement (except for *close()* calls), will be caught, wrapped, and rethrown as an `IciqlException`, which is a RuntimeException.\r
-\r
-Iciql does not throw any [checked exceptions](http://en.wikipedia.org/wiki/Exception_handling#Checked_exceptions).\r
-\r
-### Statement Logging\r
-\r
-Iciql provides a mechanism to log generated statements and warnings to the console, to SLF4J, or to your own logging framework. Exceptions are not logged using this mechanism; exceptions are wrapped and rethrown as `IciqlException`, which is a RuntimeException.\r
-\r
-#### Console Logging\r
----JAVA---\r
-IciqlLogger.activeConsoleLogger();\r
-IciqlLogger.deactiveConsoleLogger();\r
----JAVA---\r
-\r
-#### SLF4J Logging\r
----JAVA---\r
-Slf4jIciqlListener slf4j = new Slf4jIciqlListener();\r
-slf4j.setLevel(StatementType.CREATE, Level.WARN);\r
-slf4j.setLevel(StatementType.DELETE, Level.WARN);\r
-slf4j.setLevel(StatementType.MERGE, Level.OFF);\r
-IciqlLogger.registerListener(slf4j);\r
-IciqlLogger.unregisterListener(slf4j);\r
----JAVA---\r
-\r
-#### Custom Logging\r
----JAVA---\r
-IciqlListener custom = new IciqlListener() {\r
- public void logIciql(StatementType type, String statement) {\r
- // do log\r
- }\r
-};\r
-IciqlLogger.registerListener(custom);\r
-IciqlLogger.unregisterListener(custom);\r
----JAVA---\r
-\r
-## Understanding Aliases and Model Classes\r
-Consider the following example:\r
----JAVA---\r
-Product p = new Product();\r
-List<Product> restock = db.from(p).where(p.unitsInStock).is(0).select();\r
----JAVA---\r
-\r
-The Product model class instance named **p** is an *alias* object. An *alias* is simply an instance of your model class that is only used to build the compile-time/runtime representation of your table.\r
-\r
-1. *Alias* instances are **NOT** thread-safe and must not be used concurrently.\r
-2. *Alias* instances have no other purpose than to provide a compile-time/runtime map of your table.\r
-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()\r
-\r
-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`.\r
- \r
-### Why are Aliases not thread-safe?\r
-\r
-The _db.from(p)_ call reinstantiates each member field of p. Those reinstantiated fields are then subsequently used in clauses like _where(p.unitsInStock)_. If your *alias* instance is shared concurrently then its highly probable that when _queryA_ executes, _queryC_ has reinstantiated all the *alias* fields and broken _queryA's_ runtime field mapping.\r
-\r
-Depending on your design, you might consider using a [ThreadLocal](http://download.oracle.com/javase/6/docs/api/java/lang/ThreadLocal.html) variable if you do not want to keep instantiating *alias* instances. A utility function is included for easily creating ThreadLocal variables.\r
-\r
----JAVA---\r
-final ThreadLocal<Product> p = Utils.newThreadLocal(Product.class);\r
-db.from(p.get()).select();\r
----JAVA---\r
-\r
-## Best Practices\r
-\r
-1. Close your *Db* instances when you are done with them, this closes the underlying connection or directs the pool to "close" the connection.\r
-2. Aliases instances are not thread-safe so DO NOT SHARE an alias!<br/>Consider using a *ThreadLocal* alias instance with the `com.iciql.Utils.newThreadLocal()` utility method.\r
-\r
-<p/>\r
-<table class="table">\r
-<tr><th>Not Thread-Safe</th><th>Thread-Safe</th></tr>\r
-<tr><td>\r
----JAVA---\r
-final Product p = new Product();\r
-for (int i = 0; i < 5; i++) {\r
- Thread thread = new Thread(new Runnable() {\r
- public void run() {\r
- // from(p) reinstantiates p's fields\r
- db.from(p).select();\r
- }\r
- }, "Thread-" + i);\r
- thread.start();\r
-}\r
----JAVA---\r
-\r
-</td><td>\r
----JAVA---\r
-final ThreadLocal<Product> p = Utils.newThreadLocal(Product.class);\r
-for (int i = 0; i < 5; i++) {\r
- Thread thread = new Thread(new Runnable() {\r
- public void run() {\r
- // a unique p for this thread \r
- db.from(p.get()).select();\r
- }\r
- }, "Thread-" + i);\r
- thread.start();\r
-}\r
----JAVA---\r
-\r
-</td></tr>\r
-</table>\r
projects / iciql.git / commitdiff
