Terracotta Integration Module Resolution and Versioning (TC Version 2.5.1 and below)
See: DEV-1051: Document TIM resolution and versioning
RESOLUTION
Terracotta searches for Terracotta Integration Modules (TIM) using the following locations:
- From the list of repositories specified via the l1.modules.repositories system property.
- From the list of repositories specified via the <repository/> elements in the application tc-config.xml file.
- From the Terracotta installation's modules folder.
Note that the list of repositories from l1.modules.repositories and <repository/> elements in the tc-config.xml file are consumed in reverse-order.
When Terracotta searches for a TIM in a repository, it will:
1. Construct a path using the TIM's group-id, name, and version, stemming from the root of the repository.
So if you've specified a TIM with the following attributes: group-id=org.ajax, name=foo, version=1.0.0, and the repository is at /ajax-modules/, Terracotta will locate the TIM by inspecting every JAR file found in /ajax-modules/org/ajax/foo/1.0.0/
2. If step 1 fails to yield the desired TIM (or the path does not exist), it will reconstruct the path using just the TIM's group-id and name, stemming from the root of the repository, searching for the TIM recursively.
Using the example from step 1, the recursive search will begin at: ~/ajax-modules/org/ajax/foo/
3. If step 2 fails to yield the desired TIM, it will search the for the TIM recursively starting at the root of the repository.
The recursive search will now begin at: ~/ajax-modules/
4. If step 3 fails, it will attempt to locate the TIM using the steps outlined, using the next available repository (if any)
5. If all of the repositories haven been searched and the TIM is still not found, then Terracotta will abort its start-up.
TIM JAR FILENAME
A TIM is just a JAR file; it can be named differently from its actual name, but Terracotta convention for TIM
file naming is to use its name and version number separated with a dash 
So if you have a TIM with the attributes: group-id=org.ajax, name=foo, version=1.0.0 — the recommended name for its JAR file would be: foo-1.0.0.jar and installed in a repository under the /org/ajax/foo/1.0.0 directory.
When Terracotta is searching for a TIM and is examining a JAR file, it will open its manifest and read the Bundle-SymbolicName and Bundle-Version attributes; it will extract the TIM's name from the Bundle-SymbolicName value and match it (ignoring-case) against the name of the TIM being searched.
The Bundle-SymbolicName is the concatenation of the group-id and name, separated with a dot (.); Using the example attributes, the correct Bundle-SymbolicName would be: org.ajax.foo
TERRACOTTA MAVEN PLUGIN
The Terracotta Maven Plugin also behaves in the same way, except that it will only search the local Maven repository, and with the additional step of (if the TIM is not found in the local Maven repository) attempting to download the TIM from the repositories listed in the POM of the current project.
It will NOT attempt to use the repository locations listed in the tc-config file.
For more information about the Terracotta Maven Plugin, visit: http://www.terracotta.org/confluence/display/wiki/Terracotta+Maven+Plugin
GROUPID AND NAMES
Terracotta does not recognize dashes as valid characters to use in a TIM's groupId and name attribute values.
But since the Terracotta Maven Plugin also uses the same resolver and dashes are considered as valid characters when naming artifacts and groupIds in Maven, Terracotta will substitute underscores for all occurences of the dash character in the groupId and name attribute values - so when the following configuration is present:
<module name="foo-bar" version="1.0.0" group-id="org.ajax-widgets"/>
It expects to find a JAR file named foo-bar-1.0.0.jar containing a manifest that has the following entries:
Bundle-SymbolicName: org.ajax_widgets.foo_bar
Bundle-Version: 1.0.0
For version attributes, where the dash character is also not allowed (by OSGi standards), but is used by Maven as a version qualifer separator, Terracotta will substitute a dot for all ocurrences thereof. So if the configuration was:
<module name="foo-bar" version="1.0.0-SNAPSHOT" group-id="org.ajax-widgets"/>
Then the manifest entries will be:
Bundle-SymbolicName: org.ajax_widgets.foo_bar
Bundle-Version: 1.0.0.SNAPSHOT
GroupId, name, and version matching are all case-sensitive.
VERSIONING
Terracotta Integration Modules in its current incarnation is implemented using OSGi. So the versioning requirements follow that of OSGi's bundle versioning requirements.
To specify a TIM version, use the following syntax: M.m.r[.Q]
Where M is the major-version, {{m}}is the minor-version, and r is the revision number; the version components M, m, and r must be in a numeric-format.
Q is the optional qualifier (eg: BETA, SNAPSHOT, alpha2, etc); alpha-numeric and the underscore (_) are the only valid characters that may be used to construct the qualifier.
Terracotta configuration for TIM's uses the Maven convention of group-id, names, and versions.
With Maven, version qualifiers are expressed using a dash character (eg: 1.0.0-SNAPSHOT), this is the same convention used when identifying a specific TIM version (eg: group-id=org.ajax, name=foo, version=1.0.0-SNAPSHOT) - this is the preferred and recommended way — however, in its current incarnation, Terracotta is also a little bit forgiving if you specify the version information using the OSGi convention (ie: version=1.0.0.SNAPSHOT)
Use of the OSGi convention however is REQUIRED when declaring the TIM's Bundle-Version in its manifest.
VERSION RANGES
Support for identifying TIM's using version ranges is currently not supported.
