Child pages
  • tim-get

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 4.0

Include Page

Reference Documentation
Wiki Markup

Wiki Markup


h1. tim-get

h2. Introduction
tim-get is a Terracotta integration module (TIM) management tool that simplifies interaction with the catalog of integration modules available for Terracotta DSO. Utilizing a speedy command-line tool, tim-get offers control over a number of complex tasks, including sorting out dependencies, matching release versions, and setting correct configuration and installation options.

Using tim-get, 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.
* Review potential conflicts using a "dry-run" install.

By using tim-get, you can ensure that the TIMs you install are the ones most suitable for your version of Terracotta.

TIMs are installed on Terracotta clients, which run on your application servers. TIMs should not be installed on Terracotta server instances. Applications and application containers are never integrated with Terracotta server instances, only with Terracotta clients.

h2. Accessing tim-get

To access tim-get, execute the tim-get script. tim-get is a Terracotta tool located in the <Terracotta_Home>/bin directory.

On UNIX/Linux, execute the following:

{noformat} [command] [argument] --option

On Windows, execute the following: 

  tim-get.bat [command] [argument] --option

While the examples in this document use {{}}, they are also valid for {{tim-get.bat}}.

h3. The Terracotta Configuration File

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

|[help|#help] | Display general help or command-specific help| Command names| -h, --help
|[list|#list]| Display a list of installed or available TIMs| Search terms| -h, --help
-a, --all
|[info|#info]| Display information about a specific TIM| TIM name
(optional) TIM group ID (optional) version|  -h, --help
|[install|#install]| Install a TIM| TIM name
(optional) TIM group ID (optional) version|  -h, --help
|[install-for|#install-for]| Install the latest TIMs specified in the Terracotta configuration file| Path to Terracotta configuration file |  -h, --help
-u, --update-index
|[update|#update]| Update a TIM to the latest version| TIM name
(optional) TIM group ID|  -h, --help
|[upgrade|#upgrade]| Update and install the TIMs specified in a Terracotta configuration file to the latest versions | Path to the Terracotta configuration file |  -h, --help

h2. Displaying 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} [command] --help

h2. Getting Information on TIMs
The {{list}} and {{info}} commands 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:

[PROMPT] 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- (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

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


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


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.

Only installed non-internal TIMs found in the Terracotta {{modules}} directory are displayed in the TIM table. The following types of installed TIMs do _not_ appear in the TIM table:

* "Internal" TIMs required by Terracotta. To see these, use the {{list}} command with the -a or --all option.
* TIMs installed in repositories outside the Terracotta {{modules}} directory.

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

[PROMPT] 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

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 Terracotta DSO annotations:

[PROMPT] info tim-annotations

Terracotta 3.0.0, as of 20090318-110315 (Revision 12200 by cruise@su105 from 3.0)

(-) tim-annotations 1.5.0

   Installed: NO

   Author   : Terracotta, Inc.
   Copyright: Copyright (c) 2007 - 2008 Terracotta, Inc.
   Homepage :
   Docs     :
   Download :
   Status   : Supported
   Internal : false

   Annotations package for Terracotta projects

   Compatible with any Terracotta version.



   Maven Coordinates:

      groupId   : org.terracotta.modules
      artifactId: tim-annotations
      version   : 1.5.0


         <module name="tim-annotations" />

   The following versions are also available:

      (-) 1.4.2-SNAPSHOT
      (-) 1.4.1
      (-) 1.4.1-SNAPSHOT
      (-) 1.4.0

   Issue the following command to install the latest version:

      tim-get.bat install tim-annotations

(+) Installed  (-) Not installed  (!) Installed but newer version exists

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 if it is started with a configuration file that includes this snippet. 

To display detailed information on all available TIMs with one command, enter:
[PROMPT] list -v -a

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

h2. Installing TIMs
The two ways of installing TIMs are:

* Using the {{install}} command -- Installs specified individual TIMs, but can also install all available TIMs.
* Using the [{{install-for}} command|#install-for] -- Installs all TIMs configured in a specified Terracotta configuration file.

h3. The install Command
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:

[PROMPT] install tim-hibernate-3.2.5

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:

[PROMPT] install tim-hibernate-3.2.5 --overwrite

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

[PROMPT] install --all

Downloaded files are verified using a checksum algorithm. To avoid the checksum verification, use the {{\--no-verify}} option:
[PROMPT] install --all --no-verify

h3. Installing Configured TIMs
The {{install-for}} command installs the TIMs configured in the specified Terracotta configuration file, based on the latest index of TIMs cached in your installation of Terracotta. 

To download the latest index of TIMs before installing the configured TIMs, use the {{\-u}} option ({{\-\-update-index}}) with {{install-for}}.

For example, if you are clustering an application using Spring Security, you must add the following TIM to your Terracotta configuration file:

<module name="tim-spring-security-2.0" />

To install the Spring Security TIM, simply enter the following command:

[PROMPT] install-for <path/to/Terracotta/configuration/file>

Note that {{install-for}} does not require the TIM version number to be specified in the Terracotta configuration file.

h3. TIM Installation Path
A TIM is installed following 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:

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

If you install the tim-ehcache-1.2.4 TIM with tim-get, it is installed in:

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

[PROMPT] install tim-hibernate-3.2.5 --dry-run

Using install with {{--dry-run}} generates the same messages to standard output as a real installation, but with no affect on installed files.

h2. Updating TIMs
You can update existing TIMs with the latest versions for your Terracotta installation without having to learn the version numbers. 

You can update in the following ways:

* Update specific TIMs
* Update all configured TIMs

h3. Update Specific TIMs
Use the {{update}} command to install updates to specific 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 {{\--force}} to overwrite TIMs even if 

tim-get reports that no updates were found. For example, if you're updating tim-lucene-2.0.0, and the latest version is already 

installed, tim-get will reply with {{No updates found}}. To override this, enter:

[PROMPT] update tim-lucene-2.0.0 --force

{{\--force}} also updates dependencies even if the latest versions are already installed.

h3. Upgrade Configured TIMs
Use the {{upgrade}} command to update the TIMs configured in the Terracotta configuration file ({{tc-config.xml}} by default). 

{{upgrade}} also automatically updates the version numbers in the Terracotta configuration file. This command allows you to keep your TIMs and configuration file current in one step.

{{upgrade}} has the same options as {{update}} except for {{--all}}.

To update a the configrured TIMs in a Terracotta installation, enter:

[PROMPT] upgrade <path/to/tc-config.xml>

Before being edited, the existing Terracotta configuration file is saved with the extension {{.original}}.

h2. Troubleshooting Connection Problems

Often connection problems are caused by local firewalls and typically appear as "connection timed out" errors when you attempt tim-get operations. For connection problems resulting from a local firewall, configure tim-get to always use a specified proxy by adding the following property to the file {{<Terracotta_Home>/lib/resources/}}:

org.terracotta.modules.tool.proxyUrl = http://HOST:PORT

For example, if your company's proxy server is {{}}, add the following to {{}}:

org.terracotta.modules.tool.proxyUrl =

The current {{}} file does not support authorization. If your proxy requires authorization, see [these alternatives|#alternative access].

{anchor:alternative access}
h3. Alternatives for Accessing Projects
If connection problems persist or cannot be solved by using a proxy, try the following:

* If using Maven, access Terracotta projects through the [Terracotta Maven repository|Maven].
* Use SVN to download the target projects. The root SVN URL is
* If your proxy requires authentication, try a work-around such as using proxy software which allows you to specify authentication. For example, on Microsoft networks based on the NTLM protocol, you may be able to use the [NTML Authorisation Proxy Server|].