Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 139 insertions, 0 deletions

diff --git a/documentation/sqlcontainer/sqlcontainer-editing.asciidoc b/documentation/sqlcontainer/sqlcontainer-editing.asciidoc
new file mode 100644
index 0000000000..9fe8d7ba7a
--- /dev/null
+++ b/documentation/sqlcontainer/sqlcontainer-editing.asciidoc
@@ -0,0 +1,139 @@
+---
+title: Editing
+order: 4
+layout: page
+---
+
+[[sqlcontainer.editing]]
+= Editing
+
+Editing the items ( [classname]#RowItem#s) of SQLContainer can be done similarly
+to editing the items of any Vaadin container. [classname]#ColumnProperties# of a
+[classname]#RowItem# will automatically notify SQLContainer to make sure that
+changes to the items are recorded and will be applied to the database
+immediately or on commit, depending on the state of the auto-commit mode.
+
+[[sqlcontainer.editing.adding]]
+== Adding items
+
+Adding items to an [classname]#SQLContainer# object can only be done via the
+[methodname]#addItem()# method. This method will create a new [classname]#Item#
+based on the connected database table column properties. The new item will
+either be buffered by the container or committed to the database through the
+query delegate depending on whether the auto commit mode (see the next section)
+has been enabled.
+
+When an item is added to the container it is impossible to precisely know what
+the primary keys of the row will be, or will the row insertion succeed at all.
+This is why the SQLContainer will assign an instance of
+[classname]#TemporaryRowId# as a [classname]#RowId# for the new item. We will
+later describe how to fetch the actual key after the row insertion has
+succeeded.
+
+If auto-commit mode is enabled in the [classname]#SQLContainer#, the
+[methodname]#addItem()# method will return the final [classname]#RowId# of the
+new item.
+
+
+[[sqlcontainer.editing.fetching]]
+== Fetching generated row keys
+
+Since it is a common need to fetch the generated key of a row right after
+insertion, a listener/notifier has been added into the
+[classname]#QueryDelegate# interface. Currently only the [classname]#TableQuery#
+class implements the [classname]#RowIdChangeNotifier# interface, and thus can
+notify interested objects of changed row IDs. The events fill be fired after
+[methodname]#commit()# in [classname]#TableQuery# has finished; this method is
+called by [classname]#SQLContainer# when necessary.
+
+To receive updates on the row IDs, you might use the following code (assuming
+container is an instance of [classname]#SQLContainer#). Note that these events
+are not fired if auto commit mode is enabled.
+
+
+----
+app.getDbHelp().getCityContainer().addListener(
+    new QueryDelegate.RowIdChangeListener() {
+        public void rowIdChange(RowIdChangeEvent event) {
+            System.err.println("Old ID: " + event.getOldRowId());
+            System.err.println("New ID: " + event.getNewRowId());
+        }
+    });
+----
+
+
+[[sqlcontainer.editing.version-column]]
+== Version column requirement
+
+If you are using the [classname]#TableQuery# class as the query delegate to the
+[classname]#SQLContainer# and need to enable write support, there is an enforced
+requirement of specifying a version column name to the [classname]#TableQuery#
+instance. The column name can be set to the [classname]#TableQuery# using the
+following statement:
+
+
+----
+tq.setVersionColumn("OPTLOCK");
+----
+
+The version column is preferrably an integer or timestamp typed column in the
+table that is attached to the [classname]#TableQuery#. This column will be used
+for optimistic locking; before a row modification the [classname]#TableQuery#
+will check before that the version column value is the same as it was when the
+data was read into the container. This should ensure that no one has modified
+the row inbetween the current user's reads and writes.
+
+Note! [classname]#TableQuery# assumes that the database will take care of
+updating the version column by either using an actual [literal]#++VERSION++#
+column (if supported by the database in question) or by a trigger or a similar
+mechanism.
+
+If you are certain that you do not need optimistic locking, but do want to
+enable write support, you may point the version column to, for example, a
+primary key column of the table.
+
+
+[[sqlcontainer.editing.autocommit]]
+== Auto-commit mode
+
+[classname]#SQLContainer# is by default in transaction mode, which means that
+actions that edit, add or remove items are recorded internally by the container.
+These actions can be either committed to the database by calling
+[methodname]#commit()# or discarded by calling [methodname]#rollback()#.
+
+The container can also be set to auto-commit mode. When this mode is enabled,
+all changes will be committed to the database immediately. To enable or disable
+the auto-commit mode, call the following method:
+
+
+----
+public void setAutoCommit(boolean autoCommitEnabled)
+----
+
+It is recommended to leave the auto-commit mode disabled, as it ensures that the
+changes can be rolled back if any problems are noticed within the container
+items. Using the auto-commit mode will also lead to failure in item addition if
+the database table contains non-nullable columns.
+
+
+[[sqlcontainer.editing.modified-state]]
+== Modified state
+
+When used in the transaction mode it may be useful to determine whether the
+contents of the [classname]#SQLContainer# have been modified or not. For this
+purpose the container provides an [methodname]#isModified()# method, which will
+tell the state of the container to the developer. This method will return true
+if any items have been added to or removed from the container, as well as if any
+value of an existing item has been modified.
+
+Additionally, each [classname]#RowItem# and each [classname]#ColumnProperty#
+have [methodname]#isModified()# methods to allow for a more detailed view over
+the modification status. Do note that the modification statuses of
+[classname]#RowItem# and [classname]#ColumnProperty# objects only depend on
+whether or not the actual [classname]#Property# values have been modified. That
+is, they do not reflect situations where the whole [classname]#RowItem# has been
+marked for removal or has just been added to the container.
+
+
+
+