Merge branch 'documentation'

Change-Id: I6ef85a35077e6278831b968595c068898cee2770

1 files changed, 94 insertions, 0 deletions

diff --git a/documentation/sqlcontainer/sqlcontainer-freeform.asciidoc b/documentation/sqlcontainer/sqlcontainer-freeform.asciidoc
new file mode 100644
index 0000000000..c5e6d1094c
--- /dev/null
+++ b/documentation/sqlcontainer/sqlcontainer-freeform.asciidoc
@@ -0,0 +1,94 @@
+---
+title: Making Freeform Queries
+order: 7
+layout: page
+---
+
+[[sqlcontainer.freeform]]
+= Making Freeform Queries
+
+In most cases, the provided [classname]#TableQuery# will be enough to allow a
+developer to gain effortless access to an SQL data source. However there may
+arise situations when a more complex query with, for example, join expressions
+is needed. Or perhaps you need to redefine how the writing or filtering should
+be done. The [classname]#FreeformQuery# query delegate is provided for this
+exact purpose. Out of the box the [classname]#FreeformQuery# supports read-only
+access to a database, but it can be extended to allow writing also.
+
+[[sqlcontainer.freeform.getting-started]]
+== Getting started
+
+Getting started with the [classname]#FreeformQuery# may be done as shown in the
+following. The connection pool initialization is similar to the
+[classname]#TableQuery# example so it is omitted here. Note that the name(s) of
+the primary key column(s) must be provided to the [classname]#FreeformQuery#
+manually. This is required because depending on the query the result set may or
+may not contain data about primary key columns. In this example, there is one
+primary key column with a name 'ID'.
+
+
+----
+FreeformQuery query = new FreeformQuery(
+        "SELECT * FROM SAMPLE", pool, "ID");
+SQLContainer container = new SQLContainer(query);
+----
+
+
+[[sqlcontainer.freeform.limitations]]
+== Limitations
+
+While this looks just as easy as with the [classname]#TableQuery#, do note that
+there are some important caveats here. Using [classname]#FreeformQuery# like
+this (without providing [classname]#FreeformQueryDelegate# or
+[classname]#FreeformStatementDelegate# implementation) it can only be used as a
+read-only window to the resultset of the query. Additionally filtering, sorting
+and lazy loading features will not be supported, and the row count will be
+fetched in quite an inefficient manner. Bearing these limitations in mind, it
+becomes quite obvious that the developer is in reality meant to implement the
+[classname]#FreeformQueryDelegate# or [classname]#FreeformStatementDelegate#
+interface.
+
+The [classname]#FreeformStatementDelegate# interface is an extension of the
+[classname]#FreeformQueryDelegate# interface, which returns
+[classname]#StatementHelper# objects instead of pure query [classname]#String#s.
+This enables the developer to use prepared statetemens instead of regular
+statements. It is highly recommended to use the
+[classname]#FreeformStatementDelegate# in all implementations. From this chapter
+onwards, we will only refer to the [classname]#FreeformStatementDelegate# in
+cases where [classname]#FreeformQueryDelegate# could also be applied.
+
+
+[[sqlcontainer.freeform.custom-freeformstatementdelegate]]
+== Creating your own [classname]#FreeformStatementDelegate#
+
+To create your own delegate for [classname]#FreeformQuery# you must implement
+some or all of the methods from the [classname]#FreeformStatementDelegate#
+interface, depending on which ones your use case requires. The interface
+contains eight methods which are shown below. For more detailed requirements,
+see the JavaDoc documentation of the interface.
+
+
+----
+// Read-only queries
+public StatementHelper getCountStatement()
+public StatementHelper getQueryStatement(int offset, int limit)
+public StatementHelper getContainsRowQueryStatement(Object... keys)
+
+// Filtering and sorting
+public void setFilters(List<Filter> filters)
+public void setFilters(List<Filter> filters,
+                       FilteringMode filteringMode)
+public void setOrderBy(List<OrderBy> orderBys)
+
+// Write support
+public int storeRow(Connection conn, RowItem row)
+public boolean removeRow(Connection conn, RowItem row)
+----
+
+A simple demo implementation of this interface can be found in the SQLContainer
+package, more specifically in the class
+[classname]#com.vaadin.addon.sqlcontainer.demo.DemoFreeformQueryDelegate#.
+
+
+
+