Terracotta Toolkit Reference

This section describes functional aspects of the Terracotta Toolkit.

Client Failures

Clients that fail will fail with System.exit() and therefore shut down the JVM. The node on which the client failed will go down, as will all other clients and applications in that JVM.

Connection Issues

Client creation can block on resolving URL at this point:

TerracottaClient client = new TerracottaClient("myHost:9510");

If it is known that resolving "myHost" may take too long or hang, your application can should wrap client instantiation with code that provides a reasonable timeout.

A separate connection issue can occur after the server URL is resolved but while the client is attempting to connect to the server. The timeout for this type of connection can be set using the Terracotta property l1.socket.connect.timeout (see First-Time Client Connection).

Multiple Terracotta Clients in a Single JVM

When using the Terracotta Toolkit, you may notice that there are more Terracotta clients in the cluster than expected.

Multiple Clients With a Single Web Application

This situation can arise whenever multiple classloaders are involved with multiple copies of the Toolkit JAR.

For example, to run a web application in Tomcat, one copy of the Toolkit JAR may need to be in the application's WEB-INF/lib directory while another may need to be in Tomcat's common lib directory to support loading of the context-level . In this case, two Terracotta clients will be running with every Tomcat instance.

Clients Sharing a Node ID

Clients instantiated using the same constructor (a constructor with matching parameters) in the same JVM will share the same node ID. For example, the following clients will have the same node ID:

TerracottaClient client1 = new TerracottaClient("myHost:9510");
TerracottaClient client2 = new TerracottaClient("myHost:9511");

Cluster events generated from client1 and client2 will appear to come from the same node. In addition, cluster topology methods may return ambiguous or useless results.

Web applications, however, can get a unique node ID even in the same JVM as long as the Terracotta Toolkit JAR is loaded by a classloader specific to the web application instead of a common classloader.