	Terracotta Developer Documentation	Log In
	Update check

Added by Nathaniel Harward, last edited by Taylor Gautier on Oct 26, 2007 (view change)

Update check (feature)

Purpose

This feature is to allow Terracotta users/administrators to be automatically notified when new versions of the product are available. This would initially happen via the Terracotta administration console GUI.

Requirements

Notify the user with a general message, regardless of their current version of software (should be used very sparingly if it all, but might be useful in certain situations for a limited period of time).
Notify the user with a message specific to their current version of software, regardless of whether or not an update is available.
Notify the user of any number of new versions that are available, as appropriate for the software currently being run. For example a user running version 2.3.0 probably does not care if there is an update for 2.2.3, whereas a user running 2.2.2 would potentially be interested in updates for both 2.2.3 and a major version upgrade to 2.3.1. The feature should be centrally configurable such that this kind of behavior can be controlled and tuned to be of the most benefit to users.

Additional notes about the requirements:

The above features should allow for (easy and simple) centralized control: for example a promotional or legal message could be shown to all customers on 2.2.3 for a one week period and then turned off – this should not require the users to install or download any additional software.
The feature should be run initially to alert the user to it's existence. When the feature runs and alerts the user, it should prompt the user with a dialog.
The dialog should have three options:
- Ignore - the user will be asked again in 3 days
- Yes, enable checking
- No, disable checking
Additionally the dialog that prompts the user should have a checkbox "Always prompt when checking updates". When checked, the user will get the same dialog box and has to confirm the update check when the feature runs. When unchecked, the user will not be alerted to the update check feature running. The default for this box should be checked.

Initial protocol design

Have the Terracotta administration console query a java properties file on the main Terracotta website. This properties file will have keys and values as specified below, and should allow for future enhancements/changes without breaking existing code. The URL will have to be hard-coded, a suggested URL for this is:

http://www.terracotta.org/updateCheck/1.0/update-list.properties

One problem with this scheme of accessing a single properties file is that it make localization difficult. If we had a simple servlet instead, it could lookup the filename as a localized resource and return a file in the correct language.

Property file keys

Top level keys

terracotta.versions: (required) a comma separated list of known software versions, insofar as the update check feature is concerned
general.notice: (optional) a free form text field corresponding to the text to be displayed in requirement #1

Version specific keys

Version specific keys have a prefix of one of the list values of terracotta.versions, referred to below as <version>.

<version>.updates: (optional) a comma separated list of software versions that are considered updates to <version>. If undefined or empty it is taken to mean no updates are available for <version>.
<version>.notice: (optional) a free form text field corresponding to the text to be displayed in requirement #2 if the user is currently running <version>
<version>.release-notes: (optional) a valid URL to the release notes for version <version>
<version>.<anything-else>: ignored, reserved for future use

Any other keys

Any keys not matching a top level or version specific key should be ignored and are reserved for future use.

Initial GUI interaction

Upon starting the Terracotta administration console, it should (if the feature is enabled by the user) download the latest copy of the properties file from the Terracotta website and observe the following rules for each corresponding requirement listed above, in order.

If the general.notice property is defined and has a non-empty value, display the text in a (scrolling) dialog box with an "Ok" button on it to close it.
If running version "my.tc.version" of the software and the property "my.tc.version.notice" is defined and has a non-empty value, display the text in a (scrolling) dialog box with an "Ok" button on it to close it.
If running version "my.tc.version" of the software and the property "my.tc.version.updates" is defined and has a non-empty value, display a dialog with a list of the new versions available, one per line (indented, bulleted?). For each of the versions "X", if "X.release-notes" is defined and has a non-empty value, a hyperlink to the given URL should be shown after but on the same line as "X" with the clickable text "release notes". Clicking on the text should open the URL the users default web browser.

An example

Sample update properties file

## Top level keys
terracotta.versions = 2.2.0, 2.2.1, 2.2.2, 2.3.0, 2.3.1, 2.4.0-beta
# general.notice = This notice should rarely, if ever, be used as everyone running the console will see it

## 2.2.0 -- 2 updates available, 1 is a major version update
2.2.0.updates       = 2.2.2, 2.3.1
2.2.0.notice        = Terracotta recommends upgrading to the latest stable release line, 2.3.x, for best results.
2.2.0.release-notes = http://some.url/2.2.0/release-notes.html

## 2.2.1 -- 2 updates available, 1 is a major version update
2.2.1.updates       = 2.2.2, 2.3.1
2.2.1.notice        = Terracotta recommends upgrading to the latest stable release line, 2.3.x, for best results.
2.2.1.release-notes = http://some.url/2.2.1/release-notes.html

## 2.2.2 -- 1 update to a new major version
2.2.2.updates       = 2.3.1
2.2.2.notice        = Terracotta recommends upgrading to the latest stable release line, 2.3.x, for best results.
2.2.2.release-notes = http://some.url/2.2.2/release-notes.html

## 2.3.0 -- 1 update available
2.3.0.updates       = 2.3.1
2.3.0.notice        =
2.3.0.release-notes = http://some.url/2.3.0/release-notes.html

## 2.3.1 -- latest version
2.3.1.updates       =
2.3.1.notice        = Your software is up to date
2.3.1.release-notes = http://some.url/2.3.1/release-notes.html

## 2.4.0-beta -- an experimental version used by beta-testers
2.4.0-beta.updates       =
2.4.0-beta.notice        = The beta period is almost over, please take a moment to file any bugs \
                           you have a found at http://my.bugtracking.url/.  Thank you for taking the \
                           time to beta-test Terracotta software and make it better for everyone!
2.4.0-beta.release-notes = 

## This key should be ignored because it's not "terracotta.versions", "general.notice"
## and doesn't have a prefix listed in "terracotta.versions"
this.should.be.ignored = Some text no one cares about

The General and Version notices below are 80 columns wide and 8 lines long. The text should be formatted with hard newlines to accomodate 80 columns.

Testing

The AdminConsole will use a Java system property, terracotta.update-checker.url, as the location to query for the update properties file. To test a new version of the update file, run a local version of Tomcat and place the file in ${CATALINA_HOME}/webapp/ROOT/update-list.properties. Run the AdminClient like so:

> export JAVA_OPTS="-Dterracotta.update-checker.url=http://localhost:8080/update-list.properties"
> ${TC_INSTALL_DIR}/bin/admin.sh

The next-check-time can be overriden using -Dterracotta.update-checker.next-check-minutes. This sets the next-check-time to the specified number of minutes after a check is done. Automatic checks are only done at AdminConsole startup. The user can carry out a manual check at any time.

Quick Links

Developer Documentation

Architecture

Implementation

Development Process

Misc

Feature Discussions

Development Notes