Working with Terracotta Configuration Files

翻译了terracotta官方文档中关于配置文件的部分，希望对读者有所帮助，翻译的有问题的地方，请高手们执政，希望各路高手不吝赐教，本人将感激不尽！一起学习terracotta！

文中有几个看不到的图片其实就是官网上同节的三个架构图！

 

Working with Terracotta Configuration Files

Terracotta XML配置文件能够设置Terracotta server实例和Terracotta 客户端的特性和行为。最简单的方式就是根据编辑存在于Terracotta kit中的例子配置文件的一份拷贝来创建自己的Terracotta配置文件。

你在哪里找到这个Terracotta的配置文件呢？或者说你的Terracotta server和client 的配置文件如何加载，这依赖于你的项目的步骤和体系结构。这篇文档涵盖了如下情况：

Ø 开发阶段，1台Terracotta server 

Ø 开发阶段，2台Terracotta server

Ø 部署阶段

本文讨论在Terracotta Server Array.中进行集群配置。阅读Terracotta Server Arrays一节能够学习到更多关于Terracotta server 多实例的知识。

查看config-samples/tc-config-express-reference.xml文件能够综合的全方位的了解配置文件的信息。

How Terracotta Servers Get Configured

在启动的时候，Terracotta servers 从如下的源之一来加载配置：

Ø 包含在Terracotta 工具中的默认配置

Ø 本地的或远程的xml文件

Default Configuration

如果没有指定配置文件并且在Terracotta 实例启动目录中不存在tc-config.xml，那么就会使用默认的配置。

Local XML File (默认)

如果在Terracotta 实例启动的文件夹下存在tc-config.xml文件并且没有在启动脚本后没有使用-f参数明确指定配置文件，将会默认使用这个文件

Local or Remote Configuration File

在启动Terracotta server时可以在启动脚本后通过-f参数明确制定一个配置文件。比如，在Unix/Linux上，启动一个Terracotta server可以使用脚本：

start-tc-server.sh -f <path_to_configuration_file>

<path_to_configuration_file>可以是一个URL或者一个相对路径。在Microsoft 中使用start-tc-server.bat。

How Terracotta Clients Get Configured

启动的时候，Terracotta clients 从下面的源之一加载配置文件：

Ø 本地或远程的xml文件

Ø Terracotta Server 

Ø 用于Enterprise Ehcache and Enterprise Ehcache for Hibernate的Ehcache 配置文件(使用 <terracottaConfig>元素)

Ø 用于Quartz Scheduler的Quartz 属性文件（使用org.quartz.jobStore.tcConfigUrl属性）

Ø 用于容器和Terracotta Sessions的过滤器（在web.xml中）或值（在context.xml中）元素

Ø 当一个客户端使用Terracotta Toolkit进行实例化的时候，这个客户端的构造器构造（(TerracottaClient()）

Terracotta 客户端可以通过指定<client>和<application>配置项来加载自定义的配置文件。

尽管如此，集群中服务端和客户端中的<servers>块必须匹配。如果没有匹配，客户端将会弹出错误然后启动失败。

注意：启动时配置文件不匹配这个错误，在不匹配的情况下肯定会出现，但在有些情况下，即使匹配也会出现这个错误。

下面这些建议可以帮助你预防这个错误：

Ø 始终使用-Djava.net.preferIPv4Stack 参数。客户端和服务端都要同时进行设置，如果都没设置就都不设置。

Ø 确保etc/hosts 文件不会包含多个条目到对运行Terracotta server的主机进行解析（Ensure etc/hosts file does not contain multiple entries for hosts running Terracotta servers）。

Ø 确保DNS总是给运行Terracotta server的主机返回相同的地址

Local or Remote XML File

在How Terracotta Servers Get Configured中阅读关于本地XML file (默认)的讨论。

阅读Clients in Development，了解如何为Terracotta 客户端指定一个配置文件。

注意：在启动的时候从server中获取配置，Terracotta 客户端必须从服务端获取某些配置属性。加载了配置信息的客户端将会试图去连接在配置信息中命名的Terracotta server。如果配置信息中命名的server名称不可用，则客户端不会启动。

Terracotta Server

Terracotta 客户端能够通过指定hostname和DSO端口来从一个存活的 Terracotta server上加载配置信息。（阅读 Clients in Production）

Configuration in a Development Environment

在开发环境中，为每个Terracotta 客户端使用不同的配置文件可以帮助测试和配置项的调试。这是一种在使用 Terracotta DSO集群时有效并且实际的方式来获取有价值信息。

One-Server Setup in Development

对于一台Terracotta server，默认的配置是有效的。

使用默认配置进行设置，是start-tc-server.sh (or start-tc-server.bat) 脚本文件来启动Terracotta server ：[PROMPT] ${TERRACOTTA_HOME}\bin\start-tc-server.sh

也可以指定配置文件，可以阅读How Terracotta Servers Get Configured一节中的讨论。

Two-Server Setup in Development

双服务器模式，有时也只主从模式，有一个活动服务器和一个“热备份”服务器，两台服务器都需要家在同一个配置文件。

被Terracotta servers加载的配置文件必须使用<server>元素分别对每台服务器上进行定义。比如：

<tc:tc-config xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-5.xsd"

xmlns:tc="http://www.terracotta.org/config"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

...

<!-- Use an IP address or a resolvable host name for the host attribute. -->

  <server host="123.456.7.890" name="Server1">

...

  <server host="myResolvableHostName" name="Server2">

...

</tc:tc-config>

假定Server1 是活动服务器，使用同样的配置文件来使得Server2 成为热备份服务器并且维持环境在必要的情况下进行故障转移。如果你在同一个主机上运行主从实例，那么在配置文件中的<dso-port>只能被指定唯一的一个端口; <jmx-port> 和<l2-group-port>元素的值自动填充。

注意：如果在同一台主机上运行多个实例，那么在<server>段中的某些元素，比如<dso-port> 和 <server-logs>等，必须为每个server配置不同的值。

Server Names for Startup

当启动一个server的时候，多个<server> 元素的“name”属性必须被指定以避免含糊不清：

比如，如果在同一台主机上运行多个Terracotta server实例，你必须指定name属性来设置不含糊的启动对象。但是，如果使用了不明确的设置来启动server，还可以通过指定不同的IP地址来进行区别，启动脚本会假定这个server使用这个IP地址来作为启动目标。

Clients in Development

当你启动application和Terracotta客户端时，你可以明确地指定一个客户端的Terracotta配置文件，通过传递如下内容：-Dtc.config=path/to/my-tc-config.xml

DSO 用户可以使用dso-java.sh脚本进行启动（如果在Windows上使用dso-java.bat）：

dso-java.sh -Dtc.config=path/to/my-tc-config.xml -cp classes myApp.class.Main

这里的myApp.class.Main是用于启动应用并且和Terracotta进行集群的类。

如果tc-config.xml文件存在于dso-java文件夹下，可以不使用-Dtc.config进行加载。

提示：如果没有使用DSO，请避免使用dso-java脚本，Terracotta 提供了简单的配置设置。

如果你使用了DSO，你可能不想使用dso-java脚本，并使用你自己的脚本来启动你的应用和Terracotta 客户端。阅读Setting Up the Terracotta Environment一节。

Configuration in a Production Environment

为了配置一个高效的生产环境，建议你维护一个Terracotta 配置文件。这个文件将会被Terracotta server（或者servers）加载然后推向客户端。这是一种集中的降低维护的有效的方式。

如果在server元素中的hostname 属性使用了”%i”,那么在实际中将其更换为实际的hostname，比如，在开发环境中你使用了如下的内容：<server host="%i" name="Server1">

并且实际的host的hostname为myHostName，那么就将这个配置修改为：

<server host="myHostName" name="Server1">

Clients in Production

对于实际中的client，你可以在启动应用之前进行设置。DSO 用户可以使用dso-java脚本。

Setting Up the Terracotta Environment

为了使用你自己的脚本来启动你应用和Terracotta client，首先要设置如下环境变量：

TC_INSTALL_DIR=<path_to_local_Terracotta_home>

TC_CONFIG_PATH=<path/to/tc-config.xml>

或者

TC_CONFIG_PATH=<server_host>:<dso-port>

<server_host>:<dso-port>指向运行中的<server_host>:<dso-port>。指定的Terracotta server将会把配置信息推送个给Terracotta client。

如果不止一个Terracotta server可用，将他们使用逗号进行分离： 

TC_CONFIG_PATH=<server_host1>:<dso-port>,<server_host2>:<dso-port>

如果使用了DSO，通过运行下面的脚本来完整的设置Terracotta 客户端的环境：

UNIX/Linux

[PROMPT] ${TC_INSTALL_DIR}/platform/bin/dso-env.sh -q

[PROMPT] export JAVA_OPTS="$TC_JAVA_OPTS $JAVA_OPTS"

Microsoft Windows {#pgfId-998513}

[PROMPT] %TC_INSTALL_DIR%\bin\dso-env.bat -q

[PROMPT] set JAVA_OPTS=%TC_JAVA_OPTS%;%JAVA_OPTS%

在启动你的应用之前，确定JAVA_OPTS的值是正确的。其实这个JAVA_OPTS变量就是用来设置JVM的内存参数：即-Xms和-Xmx。

http://www.cnblogs.com/zxp_9527/archive/2008/12/24/1361911.html 中讲得很清楚。

Terracotta Products

不使用DSO的Terracotta （也被称作”express”安装）能够使用自己的配置文件进行path的配置。对于 Enterprise Ehcache and Enterprise Ehcache for Hibernate而言，在Ehcache 配置文件（默认是ehcache.xml）中使用 <terracottaConfig>元素进行设置：

<terracottaConfig url="localhost:9510" />

对于Quartz, 使用Quartz 属性文件中的org.quartz.jobStore.tcConfigUrl 属性进行设置。默认是quartz.properties：org.quartz.jobStore.tcConfigUrl = /myPath/to/tc-config.xml

对于Terracotta Web Sessions, 使用web.xml 或context.xml中合适的元素进行配置。

Binding Ports to Interfaces

通常，在Terracotta 配置中，为一个server 指定的端口被绑定到一个接口，这个接口与指定给这个server的host联系在一起。比如，如果这个server被配置类一个IP地址”12.345.678.8”，（或者hostname配置这个ip地址），这个server的端口就被绑定到同一个接口。

<server host="12.345.678.8" name="Server1">

 ...

 <dso-port>9510</dso-port>

 <jmx-port>9520</jmx-port>

 <l2-group-port>9530</l2-group-port>

</server>

但是，在某些情况下可能必须为一个server的一个或多个端口指定不同的接口。这是使用bind属性来设置的，这个属性允许把一个端口绑定到一个不同的接口上。比如，一个JMX客户端仅能够连接到一个主机上的特定接口：

<server host="12.345.678.8" name="Server1">

 ...

 <dso-port>9510</dso-port>

 <jmx-port bind="12.345.678.9">9520</jmx-port>

 <l2-group-port>9530</l2-group-port>

</server>