diff options
Diffstat (limited to 'documentation/sqlcontainer/sqlcontainer-caching.asciidoc')
| -rw-r--r-- | documentation/sqlcontainer/sqlcontainer-caching.asciidoc | 119 |
1 files changed, 0 insertions, 119 deletions
diff --git a/documentation/sqlcontainer/sqlcontainer-caching.asciidoc b/documentation/sqlcontainer/sqlcontainer-caching.asciidoc deleted file mode 100644 index c93a012fa5..0000000000 --- a/documentation/sqlcontainer/sqlcontainer-caching.asciidoc +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Caching, Paging and Refreshing -order: 5 -layout: page ---- - -[[sqlcontainer.caching]] -= Caching, Paging and Refreshing - -To decrease the amount of queries made to the database, SQLContainer uses -internal caching for database contents. The caching is implemented with a -size-limited [classname]#LinkedHashMap# containing a mapping from -[classname]#RowId#s to [classname]#RowItem#s. Typically developers do not need -to modify caching options, although some fine-tuning can be done if required. - -[[sqlcontainer.caching.container-size]] -== Container Size - -The [classname]#SQLContainer# keeps continuously checking the amount of rows in -the connected database table in order to detect external addition or removal of -rows. By default, the table row count is assumed to remain valid for 10 seconds. -This value can be altered from code; with -[methodname]#setSizeValidMilliSeconds()# in [classname]#SQLContainer#. - -If the size validity time has expired, the row count will be automatically -updated on: - -* A call to [methodname]#getItemIds()# method - -* A call to [methodname]#size()# method - -* Some calls to [methodname]#indexOfId(Object itemId)# method - -* A call to [methodname]#firstItemId()# method - -* When the container is fetching a set of rows to the item cache (lazy loading) - - - -[[sqlcontainer.caching.page-length]] -== Page Length and Cache Size - -The page length of the [classname]#SQLContainer# dictates the amount of rows -fetched from the database in one query. The default value is 100, and it can be -modified with the [methodname]#setPageLength()# method. To avoid constant -queries it is recommended to set the page length value to at least 5 times the -amount of rows displayed in a Vaadin [classname]#Table#; obviously, this is also -dependent on the cache ratio set for the [classname]#Table# component. - -The size of the internal item cache of the [classname]#SQLContainer# is -calculated by multiplying the page length with the cache ratio set for the -container. The cache ratio can only be set from the code, and the default value -for it is 2. Hence with the default page length of 100 the internal cache size -becomes 200 items. This should be enough even for larger [classname]#Table#s -while ensuring that no huge amounts of memory will be used on the cache. - - -[[sqlcontainer.caching.refreshing]] -== Refreshing the Container - -Normally, the [classname]#SQLContainer# will handle refreshing automatically -when required. However, there may be situations where an implicit refresh is -needed, for example, to make sure that the version column is up-to-date prior to -opening the item for editing in a form. For this purpose a -[methodname]#refresh()# method is provided. This method simply clears all -caches, resets the current item fetching offset and sets the container size -dirty. Any item-related call after this will inevitably result into row count -and item cache update. - -__Note that a call to the refresh method will not affect or reset the following -properties of the container:__ - -* The [classname]#QueryDelegate# of the container -* Auto-commit mode -* Page length -* Filters -* Sorting - - -ifdef::web[] -[[sqlcontainer.caching.flush-notification]] -== Cache Flush Notification Mechanism - -Cache usage with databases in multiuser applications always results in some kind -of a compromise between the amount of queries we want to execute on the database -and the amount of memory we want to use on caching the data; and most -importantly, risking the cached data becoming stale. - -SQLContainer provides an experimental remedy to this problem by implementing a -simple cache flush notification mechanism. Due to its nature these notifications -are disabled by default but can be easily enabled for a container instance by -calling [methodname]#enableCacheFlushNotifications()# at any time during the -lifetime of the container. - -The notification mechanism functions by storing a weak reference to all -registered containers in a static list structure. To minimize the risk of memory -leaks and to avoid unlimited growing of the reference list, dead weak references -are collected to a reference queue and removed from the list every time a -[classname]#SQLContainer# is added to the notification reference list or a -container calls the notification method. - -When a [classname]#SQLContainer# has its cache notifications set enabled, it -will call the static [methodname]#notifyOfCacheFlush()# method giving itself as -a parameter. This method will compare the notifier-container to all the others -present in the reference list. To fire a cache flush event, the target container -must have the same type of [classname]#QueryDelegate# (either -[classname]#TableQuery# or [classname]#FreeformQuery#) and the table name or -query string must match with the container that fired the notification. If a -match is found the [methodname]#refresh()# method of the matching container is -called, resulting in cache flushing in the target container. - -__Note: Standard Vaadin issues apply; even if the [classname]#SQLContainer# is -refreshed on the server side, the changes will not be reflected to the UI until -a server round-trip is performed, or unless a push mechanism is used.__ - -endif::web[] - - - |