How Terracotta Clients Get Configured

Edit online

At startup, Terracotta clients load their configuration from one of the following sources:

  • Local or Remote XML File

  • Terracotta Server

  • An Ehcache configuration file (using the <terracottaConfig> element) used with BigMemory Max and BigMemory Go.

  • A Quartz properties file (using the org.quartz.jobStore.tcConfigUrl property) used with Quartz Scheduler.

  • A Filter (in web.xml) element used with containers and Terracotta Web Sessions.

  • The client constructor ( TerracottaClient() ) used when a client is instantiated programmatically.

Terracotta clients can load customized configuration files to specify <client> and <application> configuration. However, the <servers> block of every client in a cluster must match the <servers> block of the servers in the cluster. If there is a mismatch, the client will emit an error and fail to complete its startup. However, there are options you can set for server settings to override client settings. For details, see "How Server Settings Can Override Client Settings" in the BigMemory Max Configuration Guide.

Note: Error with Matching Configuration Files - On startup, a Terracotta client may emit a configuration-mismatch error if its <servers> block does not match that of the server it connects to. However, under certain circumstances, this error may occur even if the <servers> blocks appear to match.

The following suggestions may help prevent this error:

  • Use -Djava.net.preferIPv4Stack consistently. If it is explicitly set on the client, be sure to explicitly set it on the server.
  • Ensure the etc/hosts file does not contain multiple entries for hosts running Terracotta servers.
  • Ensure that DNS always returns the same address for hosts running Terracotta servers.

Local or Remote XML File

See the discussion for local XML file (default) in How Terracotta Servers Get Configured.

To specify a configuration file for a Terracotta client, see Clients in Development.

Note: Fetching Configuration from the Server - On startup, Terracotta clients must fetch certain configuration properties from a Terracotta server. A client loading its own configuration will attempt to connect to the Terracotta servers named in that configuration. If none of the servers named in that configuration are available, the client cannot complete its startup.

Terracotta Server

Terracotta clients can load configuration from an active Terracotta server by specifying its hostname and TSA port (see Clients in Production).