Reference Documentation
{div:style=margin-top:20px}
{include:documentation-index}
{div}
{div9:id=documentationcolumn}

h1. The TIM Update Center

The Terracotta integration module (TIM) Update Center provides a simple way to manage the catalog of integration modules available for Terracotta DSO. Utilizing a speedy command-line tool, the TIM Update Center offers transparent control over a number of complex tasks, including sorting out dependencies, matching release versions, and setting correct configuration and installation options.

Using the TIM Update Center, you can quickly and easily do the following:

* See the most current TIMs available for your version of Terracotta DSO.
* Get in-depth information on a specific TIM.
* Install new TIMs directly from the the Terracotta Forge.
* Update your installed TIMs to the latest version.
* Print a current inventory of available TIMs.
* View the status of each TIM.
* Verify action results from standard-output messages.
* Review potential conflicts using a "pretend" install.

h2. Running the TIM Update Center

To run the TIM Update Center, execute the {{tim-get.sh}} (UNIX/Linux):

{noformat}
  tim-get.sh [command] [argument] --option
{noformat}

The tim-get script is also available on Windows as {{tim-get.bat}}: 

{noformat}
  tim-get.bat [command] [argument] --option
{noformat}

While the examples in this document use the UNIX/Linux version of tim-get, they are valid for {{tim-get.bat}}, the Windows version.

h5. Command Summaray
The following table serves as a quick-reference to the commands available to the TIM Update Center tim-get script. For a fuller discussion of commands, arguments, and options, click a command name or see the following sections.

||Command||Action||Arguments||Options|
|[help|#help] | Display general help or command-specific help| Command names| -h, --help
-p, --proxy
|[list|#information]| Display a list of installed or available TIMs| Search terms| -h, --help
-p, --proxy
-v, --details
|[info|#information]| Display information about a specific TIM| TIM name
(Optional) TIM group ID, version|  -h, --help
-p, --proxy
|[install|#install]| Install a TIM| TIM name
(Optional) TIM group ID, version|  -h, --help
--pretend
--overwrite
--all
--no-verify
-p, --proxy
|[update|#update]| Update a TIM to the latest version| TIM name
(Optional) TIM group ID|  -h, --help
--pretend
--overwrite
--all
--no-verify
--force
-p, --proxy

{note:title=Avoiding Connection Problems with the --proxy Option}
If tim-get is unable to connect to the TIM Update Center, it may be getting blocked by your network's local firewall. The \--proxy (or -p) option allows tim-get to use your network's proxy to pass through the firewall. For example:
{noformat}
tim-get.sh install --all --proxy myCompany.com:6666
{noformat} 
{note}

{anchor:help}
h2. Getting Help
You can display usage help for the tim-get script as well for each command. To display help on using the tim-get script, run the script without any commands.

To display help on a specific command, run the script with the command and the {{--help}} option:

{noformat}
  tim-get.sh [command] --help
{noformat}

{anchor:information}
h2. Getting Information on TIMs
The {{list}} and {{info}} command display information on the TIMs available for, or installed with, your version of Terracotta DSO. The {{list}} command can also be used to search for specific TIMs.

h3. The list Command
The {{list}} command displays a table of installed and available TIMs. For example:

{code}
[PROMPT] tim-get.sh list

Terracotta Enterprise Edition 2.7.0-nightly-rev9528, as of 20080729-160751 (Revision 2319-9528 by cruise@rh4mo0 from 2.7)

*** Terracotta Integration Modules for TC 2.7.0-SNAPSHOT ***

- tim-jetty-6.1 (1.2.0-SNAPSHOT) [org.mortbay.jetty]
- tim-jetty-6.1.4 (1.2.0-SNAPSHOT) [org.mortbay.jetty]
+ clustered-apache-struts-1.1 (2.7.0-SNAPSHOT)
+ clustered-commons-collections-3.1 (2.7.0-SNAPSHOT)
+ clustered-glassfish-2.0 (2.7.0-SNAPSHOT)
+ clustered-surefire-2.3 (2.7.0-SNAPSHOT)
+ clustered-websphere-6.1.0.7 (2.7.0-SNAPSHOT)
! tim-ehcache-commons (1.4.0-SNAPSHOT)
- tim-hashtable (2.3.0-SNAPSHOT)
- tim-hibernate-3.1.2 (1.2.0-SNAPSHOT)
- tim-hibernate-3.2.5 (1.2.0-SNAPSHOT)
- tim-ibatis-2.2.0 (1.1.0-SNAPSHOT)
- tim-lucene-2.0.0 (1.1.0-SNAPSHOT)
- tim-rife-1.6.0 (1.1.0-SNAPSHOT)

legend: [+] already installed  [!] installed but newer version exists  [-] not installed
[PROMPT]
{code}

Each entry in the table has the following components:

* TIM installation status: 
** plus (\+) -- an up-to-date version is installed
** exclamation mark (\!) -- an out-of-date version is installed
** minus (\-) -- a version is available but hasn't been installed
* TIM name, which can include a product name and version
* TIM version, in parentheses
* group-ID value, in square brackets

For example, the entry {{-tim-jetty-6.1 (1.2.0-SNAPSHOT) \[org.mortbay.jetty\]}} means that a TIM for Jetty 6.1 is available for the local Terracotta installation, but is not installed. The TIM version is {{1.2.0-SNAPSHOT}}, and the group-ID is {{org.mortbay.jetty}}. If the group-ID value is not displayed, then it equals the default value {{org.terracotta.modules}}. The Jetty TIM is installed in

{noformat}
  <terracotta_installation_directory>/modules/org/mortbay/jetty
{noformat}

while a TIM with the default group-ID is installed in

{noformat}
  <terracotta_installation_directory>/modules/org/terracotta/modules
{noformat}

The data used to build the TIM table is periodically refreshed. However, if a connection to the Terracotta Forge is unavailable, the table is created using data from the last refresh.

{note}
The installed TIMs displayed in the TIM table are found the Terracotta {{modules}} directory. If you've installed TIMs in repositories outside the Terracotta {{modules}} directory, those TIMs will not appear in the TIM table.
{note}

To return a more focused TIM table by specifying keywords with the {{list}} command. For example, to find TIMs with the word "synchronized" in their names:

{code}
[PROMPT] tim-get.sh list synchro 
Terracotta Enterprise Edition 2.7.0-nightly-rev9528, as of 20080729-160751 (Revision 2319-9528 by cruise@rh4mo0 from 2.7)

*** Terracotta Integration Modules for TC 2.7.0-SNAPSHOT ***

- tim-synchronizedcollection (2.3.0-SNAPSHOT)
- tim-synchronizedmap (2.3.0-SNAPSHOT)
- tim-synchronizedset (2.3.0-SNAPSHOT)
- tim-synchronizedsortedmap (2.3.0-SNAPSHOT)
- tim-synchronizedsortedset (2.3.0-SNAPSHOT)

legend: [+] already installed  [!] installed but newer version exists  [-] not installed
[PROMPT]
{code}

When using keywords with the {{list}} command:
* Matches occur only on continuous strings in TIM names.
* Using a leading hyphen ("-") in a keyword returns an error or executes an option.


h3. The info Command

The {{info}} command displays a detailed report about a specified TIM. For example, to generate a detailed report about the TIM for Hibernate 3.1.2:

{code}
[PROMPT] tim-get.sh info tim-hibernate-3.1.2
Terracotta Enterprise Edition 2.7.0-nightly-rev9528, as of 20080729-160751 (Revision 2319-9528 by cruise@rh4mo0 from 2.7)

tim-hibernate-3.1.2 (1.2.0-SNAPSHOT)

   Installed: NO
   
   Author   : Terracotta, Inc.
   Copyright: Copyright (c) 2007 Terracotta, Inc.
   Homepage : http://forge.terracotta.org/releases/projects/tim-hibernate/
   Download : http://download.terracotta.org/maven2/org/terracotta/modules/tim-hibernate-3.1.2/1.2.0-SNAPSHOT/tim-hibernate-3.1.2-1.2.0-SNAPSHOT.jar
   Status   : 
   
   Terracotta Integration Module for clustering Hibernate. This project comes
   with modules for Hibernate 3.1.2 and Hibernate 3.2.5
   
   Compatible with TC 2.7.0-SNAPSHOT
   
   Dependencies:
   
      + clustered-commons-collections-3.1 (2.7.0-SNAPSHOT)
      + modules-common (2.7.0-SNAPSHOT)
      - tim-cglib-2.1.3 (1.2.0-SNAPSHOT)
      - tim-ehcache-1.2.4 (1.2.0-SNAPSHOT)
      - tim-ehcache-commons (1.2.0-SNAPSHOT)
   
   Maven Coordinates:
   
      groupId   : org.terracotta.modules
      artifactId: tim-hibernate-3.1.2
      version   : 1.2.0-SNAPSHOT
   
   Configuration:
   
      <modules>
         <module name="tim-hibernate-3.1.2" version="1.2.0-SNAPSHOT" />
      </modules>
   
   There are no other versions of this TIM that are compatible with TC 2.7.0-SNAPSHOT

legend: [+] already installed  [!] installed but newer version exists  [-] not installed
[PROMPT]
{code}

The report is organized into a number of sections, including the following:

* Dependencies: Shows which other TIMs are required, and which of those are installed or out of date.
* Maven Coordinates: Gives values for attributes needed if using Apache Maven for project management.
* Configuration: Displays the configuration snippet that must be added to the Terracotta configuration file for the TIM to be loaded. The TIM is loaded by Terracotta DSO if it is started with a configuration file that includes this snippet. See [Configruation doc] and [TIM doc] for more information.

{tip}
To display detailed information on all available TIMs with one command, enter:
{noformat}
[PROMPT] tim-get.sh list -v
{noformat}
{tip}

The detailed information in the report also includes version compatibility data on:

* The technology being integrated
* Terracotta DSO
* The TIM being reported on

In the example above, the report gave the following information about the TIM for Hibernate 3.1.2:

* It has modules to integrate Hibernate 3.1.2 and Hibernate 3.2.5
* It is compatible with Terracott DSO version 2.7.0-SNAPSHOT
* No other versions of the TIM for Hibernate 3.1.2 are available


{anchor:install}
h2. Installing New TIMs
Use the {{install}} command to install TIMs to the Terracotta modules directory. To install a specific TIM, pass the TIM name as an argument to the {{install}} command. For example, to install the tim-hibernate-3.2.5 TIM, enter:

{noformat}
[PROMPT] tim-get.sh install tim-hibernate-3.2.5
{noformat}

If the TIM already exists in the default installation location (see TIM Installation Path|#install_path], tim-get skips the installation. Use the --overwrite option to overwrite the existing TIM with the version you are downloading:

{noformat}
[PROMPT] tim-get.sh install tim-hibernate-3.2.5 --overwrite
{noformat}

To download all of the TIMs available for your version of Terracotta, use the \--all option:

{noformat}
[PROMPT] tim-get.sh install --all
{noformat}

{note}
Downloaded files are verified using a checksum algorithm. To avoid the checksum verification, use the \--verify option:
{noformat}
[PROMPT] tim-get.sh install --all --noverify
{noformat}

{anchor:install_path}
h3. TIM Installation Path
TIMs are installed in the path matching its Maven coordinates (groupID, artifactID, and version values). For example, the tim-ehcache-1.2.4 TIM has the following Maven coordinates:

{code}
groupId   : org.terracotta.modules
artifactId: tim-ehcache-1.2.4
version   : 1.4.0-SNAPSHOT
{code}

If you install the tim-ehcache-1.2.4 TIM with tim-get, it will be installed in:
{noformat}
<terracotta_installation_directory>/modules/org/terracotta/modules/tim-ehcache-1.2.4/1.4.0-SNAPSHOT
{noformat}

h3. Testing with \--pretend
Certain TIMs are installed with a number of dependencies. You can run a test install using the --pretend option to see how the installation would proceed:

{noformat}
[PROMPT] tim-get.sh install tim-hibernate-3.2.5 --pretend
{noformat}

Using install with --pretend generates the same messages to standard output as a real installation.

{anchor:update}
h2. Updating Existing TIMs
Use the {{update}} command to install updates to previously installed TIMs. This command saves you the step of having to manually discover outdated TIMs using the {{info}} or {{list}} commands.

{{update}} has the same options as {{install}}, and the additional option {{\--force}}. Use to overwrite dependencies. If you update a TIM that requires 

{div9}