diff options
Diffstat (limited to 'documentation/sqlcontainer/sqlcontainer-freeform.asciidoc')
| -rw-r--r-- | documentation/sqlcontainer/sqlcontainer-freeform.asciidoc | 94 |
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#. + + + + |