About Terracotta DSO Installations

Terracotta Distributed Shared Objects (DSO) clusters require a special installation. DSO uses object identity, instrumented classes (byte-code instrumentation), object-graph roots, and cluster-wide locks to maintain data coherence.

Terracotta DSO clusters differ from standard (non-DSO) clusters in certain important ways. With DSO:

Objects are not serialized. If your shared classes must be serialized, do not use DSO.
All shared classes must meet portability requirements. Non-portable classes cannot be shared and must be excluded using configuration.
Clustered applications require a boot JAR to pre-instrument certain classes. The boot JAR file is platform-specific.
Special integration files, called Terracotta Integration Modules (TIMs), are required to integrate with other technologies.
Cluster-wide locking requirements are stricter and more extensive.
A limited number of platforms are supported.

The threshold for successfully setting up a DSO cluster can be substantially higher than for a non-DSO cluster due to DSO's stricter code and configuration requirements. It is recommended that if possible you use the standard installation (also called express installation) to set up a non-DSO cluster. Use the DSO installation only if your deployment requires the features of DSO.

WARNING: Do Not Combine Installation Methods
You cannot combine the standard ("express" or non-DSO) and the DSO ("custom") installations. These two installation methods are incompatible and if combined cause errors at startup. If you began with a standard install, then you cannot continue with the DSO install. If you began with the DSO install, then you cannot continue with the standard install. You must start with a fresh installation if switching between installation methods.

If you are new to Terracotta, see this resources page before proceeding with the DSO installation. For more information on comparing standard and DSO installation methods, see Standard Versus DSO Installations.

Standard Versus DSO Installations

There are two ways to install the Terracotta products: The standard installation, also called express, and the DSO installation, also called custom. Clusters based on the standard installation are much simpler and more flexible than those based on the DSO installation. The custom installation is for users who require DSO features such as Terracotta roots, preservation of object identity, or integration of other technologies using Terracotta Integration Modules (TIMs).

If you are using Ehcache on a single JVM, for example, or used cache replication for clustering, consider the standard installation (see Enterprise Ehcache Installation). If you are a current Terracotta user who requires DSO and distributed caching, it is recommended that you verify the need for DSO before continuing with the DSO installation given in this document.

If you are unsure about which installation path to choose, read both installation documents to find the one that meets your requirements. These installation paths are not compatible and cannot be used in combination.

Overview of Installation

This installation procedure is for users intending to install Enterprise Ehcache, Quartz Scheduler, or Terracotta Web Sessions. Instructions on integrating an application server (container) are also included. These products are independent of each other, but can be installed and run with clients using the same Terracotta Server Array.

The installation process involves these major tasks:

Have the JARs for the products you intend to install.
Edit the Terracotta configuration and the configuration (or script) files for products and containers.
Use tim-get to install the TIMs listed in the Terracotta configuration file.

Details on completing these tasks are provided in Performing a DSO Installation.