<?xml version="1.0" encoding="UTF-8" ?>
<!--
All content copyright Terracotta, Inc., unless otherwise indicated. All rights reserved.
-->
<!--
tc-config-reference.xml
This is a sample Terracotta configuration file. In it, you will find an
example of every permitted element, along with a brief description of each.
As such, it‘s a good reference, but vastly more than you need to get started.
Very few of the elements in this configuration file are required; they are
marked with a (REQUIRED) notation.
-->
<tc:tc-config xmlns:tc="http://www.terracotta.org/config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-5.xsd">
<tc-properties>
<!-- This section defines the tuning properties of terracotta cluster
These properties are called tc-properties and user can provide
them here too in addition to the local tc.properties file
配置TERRACOTTA CLUSTER的优化属性，可以放在这里，也可以放在TC.PROPERTIES文件中，TERRACOTTA依以下次序读取属性配置
1、安装JAR
2、本XML文件的tc-config节
3、tc.properties文件
4、系统属性定义
The order in which the properties would be overridden is the following
tc-properties from the installation jar
tc-properties from the tc-config
tc-properties from local tc.properties file
tc-properties set via system properties
http://forums.terracotta.org/forums/posts/list/3513.page
另外老马上文中的优化有
l1.cachemanager.enabled = true
l1.cachemanager.percentageToEvict = 10 <== 增加
l1.cachemanager.sleepInterval = 3000 《===减少
l1.cachemanager.criticalThreshold = 90 《== 减少
l1.cachemanager.threshold = 70 《== 减少
l1.cachemanager.monitorOldGenOnly = true 《== 设为false
-->
<property name="l2.nha.dirtydb.autoDelete" value="true"/>
<property name="l1.cachemanager.enabled" value="true"/>
<property name="logging.maxLogFileSize" value="1024"/>
</tc-properties>
<!-- The ‘system‘ section contains configuration data that affects the
entire Terracotta system as a whole; things like whether to activate
DSO services go here.
SYSTEM这一节记录一些影响Terracotta全局的数据
-->
<system>
<!-- The configuration model: ‘development‘ or ‘production‘.
In ‘development‘ mode, each client can have its own configuration,
independent of the server or any other client. This mode can result in
shared data being corrupted or lost if, for instance, two different
clients specify roots of different types.
In ‘production‘ mode, it is enforced that each client has obtained its
configuration from its server. When a client first connects to a server
it determines the servers configuration model and, if production, ensures
that its configuration source was that server. A client can specify that its
configuration come from server by setting the ‘tc.config‘ system propery as
-Dtc.config=serverHost:dsoPort.
描述启动的方式，开发或生产，默认为开发development
Default: ‘development‘.生产环境：production -->
<configuration-model>development</configuration-model>
</system>
<!--
This section defines the servers present in your Terracotta system. You can
omit this section entirely, in which case it behaves as if there‘s a
single server with all values set at their default. You can include exactly
one server entry here (the common case), or, if you‘re going to run multiple
servers for failover, you can include multiple servers here.
SERVERS一节定义系统中的所有SERVER的数据，如果指定hostname，Terracotta将自动只允许在honstname匹配的机器上
If you include more than one server here, note that each server will need to know
which configuration it should use as it starts up. If you name your servers
according to the host that they run on (and no host contains more than
one server), then they will find the hostname themselves and work
automatically.
你可以在启动时候通过-n <name>来启动指定的server
If you name your servers in any other fashion (and, again, only if there is
more than one ‘server‘ element present here), then you will need to pass the
command-line option "-n <name>" to the start-tc-server script, passing it
the name of a server configuration from this file.
-->
<servers>
<!-- The host, symbolic name and bind address of the server; host defaults to "%i" (the machine‘s
IP address), name defaults to "host:dso-port" and bind address defaults to "0.0.0.0".
Expansion parameters may be used in all attributes.
host-主机名或者IP
name-SERVER名称
bind-绑定的IP地址，0.0.0.0代表不绑定IP -->
<server host="my.host.name" name="My Server Name" bind="0.0.0.0">
<!-- Where should the server store its persistent data? (This includes
stored object data for DSO.) This value undergoes parameter substitution
before being used; this allows you to use placeholders like ‘%h‘ (for the hostname)
or ‘%(com.mycompany.propname)‘ (to substitute in the value of
Java system property ‘com.mycompany.propname‘). Thus, a value
of ‘server-data-%h‘ would expand to ‘server-data-my.host.name‘ if
running on host ‘my.host.name‘.
If this is a relative path, then it is interpreted relative to
the current working directory of the server (that is, the directory
you were in when you started the server). It is thus recommended that
you specify an absolute path here.
Default: ‘data‘; this places the ‘data‘ directory in the
directory you were in when you invoked ‘start-tc-server‘.
data-当配置以持久方式（persistent）保存数据时候的数据存放地址
-->
<data>/opt/terracotta/server-data</data>
<!-- In which directory should the server store its log files? Again,
this value undergoes parameter substitution before being used;
thus, a value like ‘server-logs-%h‘ would expand to
‘server-logs-my.host.name‘ if running on host ‘my.host.names‘.
If this is a relative path, then it is interpreted relative to
the current working directory of the server (that is, the directory
you were in when you started server). It is thus recommended that
you specify an absolute path here.
Default: ‘logs‘; this places the ‘logs‘ directory in the
directory you were in when you invoked ‘start-tc-server‘.
logs-日志存放地址
-->
<logs>/opt/terracotta/server-logs</logs>
<!-- In which directory should the server store statistics data that is
being buffered? Again, this value undergoes parameter substitution
before being used; thus, a value like ‘statistics-data-%h‘ would
expand to ‘statistics-data‘ if running on host ‘artichoke‘.
If this is a relative path, then it is interpreted relative to the
current working directory of the server (that is, the directory you
were in when you started server). It is thus recommended that you
specify an absolute path here.
Default: ‘statistics‘ This places the ‘statistics‘ directory in the
directory you were in when you invoked ‘start-tc-server‘.
statistics-存放统计分析数据的目录
-->
<statistics>/opt/terracotta/server-statistics</statistics>
<!-- On what port should the DSO server listen for connections from DSO
clients? This can be any port you like, but note that
ports below 1024 typically require ‘root‘ privileges to use
on Un*x-style systems (Linux, Solaris).
Default: 9510
dso-port-供客户端调用的端口，默认为9510
-->
<dso-port>9510</dso-port>
<!-- On what port should the server listen for connections from the
Terracotta administration console? This can be any port you
like, but note that ports below 1024 typically require ‘root‘
privileges to use on Un*x-style systems (Linux, Solaris).
Default: 9520
jmx-port JMX管理端口,默认为9520
-->
<jmx-port>9520</jmx-port>
<!-- On what port should the server listen for communication from
other servers participating in an networked-active-passive setup.
This can be any port you like, but note that ports below 1024
typically require ‘root‘ privileges to use on Un*x-style systems
(Linux, Solaris).
Default: 9530
l2-group-port:server间的监听端口
-->
<l2-group-port>9530</l2-group-port>
<!-- Turn on authentication for the Terracotta server. An empty tag
<authentication> defaults to the standard Java JMX authentication
mechanism referring to password and access files in:
$JAVA_HOME/jre/lib/management.
- $JAVA_HOME/jre/lib/management/jmxremote.password
- $JAVA_HOME/jre/lib/management/jmxremote.access
You must modify these files as such (if none exist create them):
- jmxremote.password: add a line to the end of the file declaring
your username and password followed by a caridge return:
secretusername secretpassword
- jmxremote.access: add the following line (with a caridge return)
to the end of your file:
secretusername readwrite
You must also do:
$ chmod 500 jmxremote.password
$ chown <user who will execute the tc-server> jmxremote.password
一个空的<authentication/>代表使用JAVA默认的JMX认证方式，你需要修改：
- $JAVA_HOME/jre/lib/management/jmxremote.password，增加一行 用户 密码
- $JAVA_HOME/jre/lib/management/jmxremote.access， 增加一行 用户 readwrite
同时要执行
1、chmod 500 jmxremote.password
2、chown <启动TC-SERVER的用户> jmxremote.password
-->
<authentication/>
<!-- Turn on authentication for the embedded Terracotta HTTP Server.
This requires a properties file that contains the users and passwords
that have access to the HTTP server.
The format of the properties file is:
username: password [,rolename ...]
The supported roles and protected sections are:
- statistics: for the statistics gatherer at /statistics-gatherer
Passwords may be clear text, obfuscated or checksummed.
The class com.mortbay.Util.Password should be used to generate
obfuscated passwords or password checksums.
http-authentication 定义terracotta http server 访问用户管理文件名，文件格式为
username: password [,rolename ...]
rolename目前只有statistics，允许收集统计数据
-->
<http-authentication>
<user-realm-file>/opt/terracotta/realm.properties</user-realm-file>
</http-authentication>
<!-- Configuration data for DSO that‘s specific to the DSO server.
配置 DSO相关属性-->
<dso>
<!-- How much time (in seconds) should the DSO server, upon restart, allow for previously
connected clients to reconnect? After this period, clients will
not be allowed to reconnect.
client-reconnect-window-定义在server 启动后多少秒内，previously connected clients 可以连接？
Default: 120 seconds
-->
<client-reconnect-window>120</client-reconnect-window>
<!-- Information about how DSO should persist data to disk.
persistence -定义DSO对下的持久性保存方式 -->
<persistence>
<!-- How should DSO persist data to disk? This can be one
of two values:
‘temporary-swap-only‘ causes the DSO server to use the
disk as a temporary backing store. Data is not
preserved across server restarts. This mode is somewhat
faster than ‘permanent-store‘ mode.
‘permanent-store‘ causes the DSO server to write data
immediately and permanently to disk. Upon server restart,
data will be restored, meaning data underneath roots
in your program will be restored to the exact state it
was in when the server shut down.
Note that if you are using clustered DSO servers (i.e., if
you have more than one <server> element defined,
below), then you must use ‘permanent-store‘ mode. This
is required for proper operation of the DSO
failover mechanism.
temporary-swap-only-方式只临时使用下磁盘，比permanent-store方式要快些
permanent-store-方式只有变化立即写入磁盘，更有利于SERVER异常后的数据恢复。
默认为temporary-swap-only方式
Default: ‘temporary-swap-only‘
-->
<mode>temporary-swap-only</mode>
</persistence>
<!-- Information about how DSO should perform distributed
garbage collection on the data underneath your
application‘s roots.
garbage-collection -配置分布式JVM垃圾的回收方式-->
<garbage-collection>
<!-- If ‘true‘, distributed garbage collection is enabled.
You should only set this to ‘false‘ if you are
absolutely certain that none of the data underneath
your roots will ever become garbage; certain
applications, such as those that read a large amount
of data into a Map and never remove it (merely look up
values in it) can safely do this.
A setting of ‘false‘ can also be used if distributed
garbage collection will be triggered externally
with the ‘run-dgc‘ script
true代表自动回收，false 模式下只有在‘run-dgc‘脚本被调用的情况才回收
默认为TRUE
Default: true
-->
<enabled>true</enabled>
<!-- If ‘true‘, the DSO server will emit extra information
to the log file when it performs distributed garbage
collection; this can be useful when trying to
performance-tune your application.
verbose-配置为TRUE在分布式垃圾回收的时候是否写额外信息到日志中，有利于系统优化
默认为false
Default: false
-->
<verbose>false</verbose>
<!-- How often should the DSO server perform distributed
garbage collection, in seconds?
interval-分布式垃圾回收时间间隔，单位秒，默认为3600
Default: 3600 (60 minutes)
-->
<interval>3600</interval>
</garbage-collection>
</dso>
</server>
<!-- This additional <server> element is just to illustrate
that multiple server definitions can be listed
-->
<server host="broccoli">
<data>/usr/local/tc/data</data>
<logs>/usr/local/tc/logs</logs>
<dso-port>8510</dso-port>
<dso>
<persistence>
<mode>permanent-store</mode>
</persistence>
<garbage-collection>
<enabled>true</enabled>
<verbose>true</verbose>
<interval>3600</interval>
</garbage-collection>
</dso>
</server>
<!-- This section lets you divide your servers in groups. Each
group can be composed of one or more servers out of which 1 server
will act as an Active server i.e. each group will have 1 Active
server. You can omit this section if you want to have only
1 Active server in the cluster.
mirror-groups ，对server进行分组，一组中只有1个serrver是active的
-->
<mirror-groups>
<!-- Each group can also be assigned a group name. Each group has members
which are actually the "name" of the server specified above in the server section.
More than one member can be present in a mirror group.
每组可以定义自己的名称，一个group下可以有多个server
-->
<mirror-group group-name="group1">
<members>
<member>server1</member>
</members>
<!-- Each group can have its own ha, otherwise it is taken as the common
ha defined
每个group可以定义自己的HA方式，如果没有定义，则使用公共定义
-->
<ha>
<mode>networked-active-passive</mode>
<networked-active-passive>
<election-time>5</election-time>
</networked-active-passive>
</ha>
</mirror-group>
<mirror-group>
<members>
<member>server2</member>
</members>
</mirror-group>
</mirror-groups>
<!-- This section allows you to indicate properties associated
with running your servers in active-passive mode. The properties
apply to all servers defined. You can omit this section, in which
case your servers, running in persistent mode, will run in
disk-based active-passive mode.
Note: In order to allow for at most 1 <ha> section to be defined
along with multiple <server> sections, they must be defined
in a given order (i.e., multiple <server> section then
0 or 1 <ha> section).
-->
<ha>
<!-- This section allows you configure whether servers run in
disk-based active-passive or network-based active-passive mode.
There are two HA mode options: ‘disk-based-active-passive‘ and
‘networked-active-passive‘.
ha-定义HA的模式及心跳间隔，可以为磁盘(disk-based-active-passive)
或者网络（networked-active-passive）方式，默认为disk-based-active-passive,
Default: ‘disk-based-active-passive‘
-->
<mode>disk-based-active-passive</mode>
<!-- This section allows you to declare the election time window,
which is used when servers run in network-based active-passive mode.
An active server is elected from the servers that cast a vote within
this window. The value is specified in seconds. Network latency and
work load of the servers should be taken into consideration when
choosing an appropriate window.
election-time- 心跳检查间隔，单位秒，默认值5
Default: 5
-->
<networked-active-passive>
<election-time>5</election-time>
</networked-active-passive>
</ha>
<!-- This element lets you control if and how often the Terracotta server
will check for update versions of the Terracotta platform.
-->
<update-check>
<!-- This element determines if the server will check for updates
to the version of the Terracotta platform your are using. The server
will contact the terracotta.org website and compare the version of
your software with a registry of current releases. Information about
new versions will be logged and displayed on the server‘s standard
output.
update-check：运行时候是否进行Terracotta版本检查，会连接Terracotta.org ，默认为false
Default: ‘false‘
-->
<enabled>true</enabled>
<!-- This element controls the period, in days, between update checks
given that update checking is enabled. When checking is enabled, each
time the server starts an update check is performed as well as at
subsequent intervals, according to this value.
period-days- 检查间隔天数，默认为7
Default: 7
-->
<period-days>10</period-days>
</update-check>
</servers>
<!-- This section contains settings that affect all clients that connect to the
system.
clients 设置影响所有连接到系统的client
Note that while these settings are applied uniformly across all clients,
this does not prevent you from applying different settings to various
clients. There are two ways of doing this:
- Certain parameters (‘logs‘, below) undergo parameter expansion
before being used by the client. This allows you to use various predefined
substitutions (like ‘%h‘ for host), or a general one
(%(myprop) to use the value of Java system property ‘myprop‘), for
these values; expansions are carried out in each client‘s JVM
independently. Parameter expansion is not done for values inside the
<modules> element.
-->
<clients>
<!--
This section lists any modules (currently pre-defined configurations)
for products you will be using. These do not include the products themselves
(you must provide that) but rather configuration information for Terracotta
that describes what should be clustered. Please check the ‘modules‘
directory in the Terracotta installation directory for a list of
supplied modules.
modules 描述除应用本身外应该被terracotta cluster的模块，如TIM-TOMCAT等，为可选部分
The <modules> section is optional.
-->
<modules>
<!--
The ‘modules‘ directory in the Terracotta installation directory is implied
as the first reposository, however if you have other places to look for modules
you can optionally specify as many of them as you wish here; they can be any
valid file path, absolute or relative. Repositories are searched in the order
defined here (after the implicit repository) for modules by appending
"/<module-name>-<module-version>.jar" to each path. The first match succeeds.
repository -Terracotta安装目录下modules为寻找module的默认目录，也可以在respository里面定义目录
用于寻找module，respository为可选
The <repository> element(s) is optional.
-->
<repository>/my/modules/directory</repository>
<repository>../repository</repository>
<!--
If you choose to use a module, define it here. Distributed modules have the
file name "name-version.jar" where "name" and "version" are the <module>
element attributes. You may define 0 or more modules to be used, they are
loaded in the order defined here.
The attribute "group-id" is optional and defaults to "org.terracotta.modules",
which is the group-id for most Terracotta-provided modules. The attribute
"name" is required. The attribute "version" is optional. If used, it specifies
an exact module version. If omitted, the latest version available in the
repository is included.
The <module> element(s) is optional.
要cluster的module，可选
-->
<module name="clustered-apache-struts-1.1"/>
<module name="clustered-commons-collections-3.1"/>
</modules>
<!-- Where should the client write its log files?
定义日志存放目录，可以使用参数 %h代表hostname，%i代表IP地址，默认为启动client的目录的相对目录，也可以使用绝对路径
This value undergoes parameter substitution before being used;
thus, a value like ‘client-logs-%h‘ would expand to
‘client-logs-banana‘ if running on host ‘banana‘.
If this is a relative path, then it is interpreted relative to
the current working directory of the client (that is, the directory
you were in when you started the program that uses Terracotta
services). It is thus recommended that you specify an absolute
path here.
Default: ‘logs-%i‘; this places the logs in a directory relative
to the directory you were in when you invoked the program that uses
Terracotta services (your client), and calls that directory, for example,
‘logs-10.0.0.57‘ if the machine that the client is on has assigned IP
address 10.0.0.57.
-->
<logs>logs-%i</logs>
<!-- This section contains data for Terracotta DSO that‘s specific to
the DSO client only.
dso -定义dso client相关属性 -->
<dso>
<!-- This section allows you to declare object fault count, which is
the max number of reachable objects that are prefetched from DSO server
to DSO client when an object is faulted from DSO server to DSO client.
It has a default value of 500.
定义client最大运行失败数量，缺省为500
-->
<fault-count>500</fault-count>
<!-- This section controls output from the DSO client that can help you
debug your program.
定义debugging相关属性-->
<debugging>
<!-- This section controls output from the DSO client related to
class instrumentation; each individual element controls a different kind
of output.
定义类instrumentation时候debug属性-->
<instrumentation-logging>
<class>false</class>
<locks>false</locks>
<transient-root>true</transient-root>
<roots>false</roots>
<distributed-methods>false</distributed-methods>
</instrumentation-logging>
<!-- This section controls output from the DSO client related to
operations occurring at runtime; each individual element controls a
different kind of output.
定义运行时候相关操作debug属性 -->
<runtime-logging>
<non-portable-dump>true</non-portable-dump>
<lock-debug>false</lock-debug>
<wait-notify-debug>false</wait-notify-debug>
<distributed-method-debug>false</distributed-method-debug>
<new-object-debug>false</new-object-debug>
<named-loader-debug>false</named-loader-debug>
</runtime-logging>
<!-- This section controls the exact format of the output from
any options enabled under ‘runtime-logging‘, above.
Each individual element controls a different kind of output.
定义runtime-logging模式下输出格式，其中caller配置已经是deprecated，不推荐
Setting the value of ‘caller‘ element to true is now deprecated. -->
<runtime-output-options>
<auto-lock-details>false</auto-lock-details>
<caller>false</caller>
<full-stack>false</full-stack>
</runtime-output-options>
</debugging>
</dso>
</clients>
<!-- This section contains items that affect the core behavior of Terracotta
as it relates to your application. This data must be kept consistent
across clients and servers in order for Terracotta to function properly, and
so the system will enforce this; see the comments for the
‘configuration-model‘ switch, above, for more details.
应用相关定义-->
<application>
<!-- This section controls how Terracotta DSO behaves in your application. -->
<dso>
<!-- This section controls which classes are instrumented by
Terracotta DSO. In order for an object to be shared among
JVMs by DSO, or contain a root, its class must be instrumented.
You can define ‘include‘ and ‘exclude‘ patterns here; The patterns
are evaluated bottom up according to the order in this config file.
The first pattern that matches will determine whether the class will
or will not be instrumented. If no patterns match, the class will not
be instrumented
Patterns here are AspectWerkz-compatible class specification
expressions.
Default: none; no classes are instrumented. Thus for proper
DSO functionality, you must specify at least one ‘include‘
section here.
instrumented-classes 定义那些class应该有terracotta来构建（instrument），即应该在jvm进行cluster和共享
可以通过定义包含（include）及排除（exclude）两种方式来配置
-->
<instrumented-classes>
<!-- This includes a certain set of classes for instrumentation.
定义类的构建方式 -->
<include>
<!-- The class(es) to include, as an AspectWerkz-compatible
class specification expression. (REQUIRED)
include，定义要cluster、共享的类，必须配置，可以配置多条-->
<class-expression>com.mycompany.pkga.*</class-expression>
<!-- If set to ‘true‘, then any fields in the given class(es)
that have the Java ‘transient‘ modifier are not shared
across JVMs. If set to ‘false‘, they are.
honor-transient，如果设置为false，那么所有标示为临时对象（transient）的类都要求使用terracotta来构建
默认为false
Default: false -->
<honor-transient>true</honor-transient>
<on-load>
<!-- One of either <execute> or <method> is required within an <on-load> element -->
<!-- This (zero argument) method will be called on instances of the specified class
on load of the object. Used to initialize transient fields. Use any method name
you have designated for on-load execution.
定义在装载类时候要执行的动作：
1、如果是java类方法，使用method,注意method不能有参数
2、调用脚本，使用execute
如果配置了onload，那么method和execute 2者必须配置一种 -->
<!-- <method>initTransients</method> -->
<!-- This bean shell script is called right after an object is loaded
-->
<execute><![CDATA[self.myTransientField = new ArrayList();]]></execute>
</on-load>
</include>
<!-- The class(es) to exclude, as an AspectWerkz-compatible
class specification expression.
exclude -定义不使用terracotta 构建的类，可选，可以配置多条-->
<exclude>com.mycompany.pkga.subpkg.*</exclude>
<include>
<class-expression>com.mycompany.pkgb.*</class-expression>
</include>
</instrumented-classes>
<!-- This section lets you specify certain fields as ‘transient‘ to
Terracotta DSO. Note that this does not cause these fields
to behave as ‘transient‘ for Java serialization; rather, it
simply means that the contents of these fields are not shared
across JVMs by DSO.
The expressions in ‘field-name‘ must be fully qualified
field names (expressions are not permitted)
Default: no extra fields are specified as ‘transient‘
transient-fields -列出临时属性field，即不需要在cluster、shared的属性列表-->
<transient-fields>
<field-name>com.mycompany.pkga.MyClassOne.fieldA</field-name>
<field-name>com.mycompany.pkgb.subpkg2.fieldB</field-name>
</transient-fields>
<!-- This section lets you specify locks to Terracotta DSO. Locks
are critical to correct functioning of DSO.
本节用于设置自定义的锁，锁可以分为自动锁（autolock）和命名锁（named-lock）
Two types of lock elements may be included here, in any order:
‘autolock‘ and ‘named-lock‘.
锁的级别可以分为：
1、写锁write
2、同步写锁synchronous-write
3、读锁read
4、并发锁 concurrent
其中并发锁一定要小心使用，并发允许同时写一个对象。
Locks are configured with one of the following levels: ‘write‘,
‘synchronous-write‘, ‘read‘, or ‘concurrent‘.
Write locks are used when the method(s) being locked
modify the data being protected. Only one thread in one
JVM, cluster-wide, may be inside the same write lock
at once. Further, no threads may be inside a read lock
while one thread holds a write lock of the same identity.
Synchronous-write locks add a further guarantee over write locks.
Where a write lock guarantees that all changes made in the scope of
that lock will be applied prior to a thread acquiring that lock,
synchronous-write locks guarantee that the thread holding the lock
will not release the lock until the changes made under that lock
are fully ACKed by the server.
Read locks may be used only when the method(s) being
locked do not actually modify the data in question;
multiple threads in multiple JVMs may be inside the
same read lock at the same time. However, if a thread
is locked upon the same object but using a write lock,
then any threads that require a read lock must wait
until the write locks has been released.
Concurrent locks are a looser form of write lock, and
should be used with caution. Multiple threads can be
inside a concurrent lock at the same time, and can all
write to the data; This can easily lead to nondeterministic
program behavior and thus is generally used only with
considerable caution.
-->
<locks>
<!-- Specifies an autolock (distributed synchronization).
Autolocks extend normal Java ‘synchronized‘ blocks and methods
across the entire cluster just as you‘d expect, by locking on
the object you‘re synchronizing upon. Applying an autolock to
methods that contain no synchronization (method or block)
is ineffective. If the original definition of the method is not
synchronized, it should be refactored. If it can not be factored,
enable the "auto-synchronized" attribute.
When set to true, this attribute will add a synchronized modifier
to the method signature before autolocking on the method.
By default, the "auto-synchronized" attribute is set to false.
*** NOTE THAT USING AUTO-SYNCHRONIZED MAY HAVE A SEVERE IMPACT
ON PERFORMANCE. ***
auto-lock锁可以将你期望的方法，通过java的同步机制（block和method）来进行管理，
对于没有定义为synchronized的对象，需要设置auto-synchronized=true？
-->
<autolock auto-synchronized="false">
<!-- The expression of method(s) to lock. This is an
AspectWerkz-compatible method specification expression.
(REQUIRED) -->
<method-expression>* com.mycompany.pkga.MyClassOne.set*(..)</method-expression>
<!-- The level of the lock: ‘write‘, ‘synchronous-write‘, ‘read‘, or
‘concurrent‘. See above for more details. -->
<lock-level>write</lock-level>
</autolock>
<!-- Specifies a named lock.
Named locks are completely independent of Java synchronization.
*** NOTE THAT USING NAMED LOCKS MAY HAVE A SEVERE IMPACT ON
PERFORMANCE. ***
A named lock creates a lock with the specified name. This type of
lock is always acquired when the methods to which it is applied
are invoked irrespective of whether the instance is shared or
not. Additionally, the instance does not qualify the lock in
any way; named locks cause cluster-wide excecution serialization
to methods to which they applied.
If you create multiple named-lock sections in this file that
share the same name, they behave as the same lock.
name-lock 完全依赖于java的synchronization机制，可以对锁进行命名以方便管理
-->
<named-lock>
<!-- The name of the lock. (REQUIRED) -->
<lock-name>lockOne</lock-name>
<!-- The expression of method(s) to lock. This is an
AspectWerkz-compatible method specification expression.
(REQUIRED) -->
<method-expression>* com.mycompany.pkgb.get*(int)</method-expression>
<!-- The level of the lock: ‘read‘, ‘write‘, or ‘concurrent‘.
See above for more details. -->
<lock-level>read</lock-level>
</named-lock>
</locks>
<!-- This section specifies the roots for Terracotta DSO. Roots
are the ‘share points‘ in DSO; they specify fields in a class,
such that DSO will make sure every instance of every class
in every VM always sees the same object in that field (and
in all fields of that object, and in all fields of those
objects, and so on; the transitive closure of this data is
shared, modulo transients).
Roots are specified using the fully-qualified name of a
field. They can optionally be given a name.
root 通过指定DSO对象的root，可以将对象分组管理
-->
<roots>
<root>
<!-- One of either field-name or field-expression is REQUIRED,
but not BOTH -->
<!-- The name of the field to make a root. This must be
the fully-qualified name of a field. -->
<field-name>com.mycompany.pkgc.AnotherClass.field1</field-name>
<!-- A field expression to select fields to be roots. This must be
a valid AspectWerkz-compatible field expresion.-->
<!-- <field-expression>@com.example.MyRootAnnotation * *</field-expression> -->
<!-- The name for this root. This is optional, but can
help when debugging your system, or to declare that
two (or more) unique root field names should use the
same root instance. A common root name applied to more
than one field name implies that the same root object
will be used in both fields -->
<root-name>rootOne</root-name>
</root>
<root>
<field-name>com.mycompany.pkgc.ClassTwo.field3</field-name>
<root-name>rootTwo</root-name>
</root>
</roots>
<!-- This section specifies the instances that are injected
into your application by Terracotta DSO. These injected instances
allow you to access DSO-specific information or functionalities.
terracotta注入（injected）信息，通过注入，可以访问terracotta DSO 特有的信息和功能
-->
<injected-instances>
<!-- Inject an instance into a field of a class. The type of this
field determines what kind of instance will be injected. Check
the Terracotta documentation to learn about all supported
types. -->
<injected-field>
<!-- The name of the field into which to inject the instance.
This must be the fully-qualified name of a field. -->
<field-name>com.mycompany.pkgc.AnotherClass.theField</field-name>
</injected-field>
<injected-field>
<field-name>com.mycompany.pkgc.AnotherClass.anotherField</field-name>
<!-- Allows you to specify which instance type needs to be injected
in case the type of the field by itself doesn‘t allow Terracotta
DSO to determine the injected instance type univocally. -->
<instance-type>com.tc.cluster.DsoCluster</instance-type>
</injected-field>
</injected-instances>
<!-- This section specifies methods to invoke in a distributed
fashion via Terracotta DSO. When a method matching one of the
patterns here is invoked on a *shared* object in one JVM,
Terracotta DSO will cause it to be invoked simultaneously in
all JVMs throughout the Terracotta cluster. This is often used
for ‘event listener‘ methods (for example, those used by Swing),
to make sure that all JVMs throughout the cluster are informed
when a particular event occurs.
distributed-methods-分布式方法调用，当某个method在一个JVM被调用后，整个cluster下jvm都调用此method
常用于事件监听
-->
<distributed-methods>
<!-- An AspectWerkz-compatible method specification expression
denoting which method(s) to distribute. -->
<method-expression>void com.mycompany.pkga.MyClass.somethingHappened(String, int)</method-expression>
<method-expression>String[] com.mycompany.pkgc.AnotherClass.eventOccurred(Boolean, Double)</method-expression>
<!-- An optional attribute run-on-all-nodes (default value "true")
can be set to false to execute distributed only on those nodes
that already have a reference to the object on which the method
is called
run-on-all-nodes -设置为false，那么只有在method归属对象在jvm已经创建，method才被调用，默认为true
-->
<method-expression run-on-all-nodes="false">String[] com.mycompany.pkgc.SomeOtherClass.eventOccurred(Boolean, Double)</method-expression>
</distributed-methods>
<!-- The standard java runtime classes (typically anything in the
java.*, javax.*, sun.*, etc packages) are instrumented by
Terracotta DSO in a special fashion. Specifically, they are
instrumented and placed into a special "boot JAR", which is
included on the Java boot-classpath (which is, in turn,
a different thing from the normal Java classpath) by the
dso-java script.
标准的java运行class（比如java.*,javax.*,sun.*)是被Terracotta以特殊的机制构建（instrument）的，
这些类被Terracotta以dso-java script方式放在一个特殊的启动jar（boot jar）中
This "boot JAR" can be rebuilt by the ‘make-boot-jar‘ tool
included with the Terracotta distribution, and must be rebuilt
when transitioning from one vendor‘s JVM to another, or between
different releases of the JVM.
boot jar可以使用Terracotta提供的 ‘make-boot-jar’工具来重新构造,在不同供应商的jvm（如sun，ibm）
及不同版本的jvm时候需要重新构建
可以在additional-boot-jar-classes 中配置要加入boot-jar中的特殊类，
在additional-boot-jar-classes中每个类都必须独立列出，pattern方式是不支持的
Many commonly-used classes are included by default in the
Terracotta boot JAR. However, if a class is not included by
default in the Terracotta boot JAR, then you can place its
name here and specify this configuration file to the
‘make-boot-jar‘ tool; this will cause it to be included
when the boot JAR is rebuilt. Every class must be specified
individually (patterns are not supported here)
Note that Terracotta cannot guarantee that all runtime classes
can be safely added here, although many will work correctly.
If in doubt, consult Terracotta for details.
Default: no additional classes are included in the Terracotta
boot JAR.
-->
<additional-boot-jar-classes>
<include>java.awt.datatransfer.Clipboard</include>
</additional-boot-jar-classes>
<!-- When using Terracotta DSO within an application server, you
may wish to enabled DSO session management. To do so, list the
context paths of the applications that should use DSO sessions.
For the default context path (ie. "/"), use the special value
‘ROOT‘ (without the quotes)
在web应用中，可以使用Terracotta来管理session，可以在 web-applications来
配置WEB 应用名（context path）
There is an attribute "session-locking" in web-application which is
optional and true by default. By default, locking is implicitly
provided and auto-locking is not required when modifying/mutating
shared objects in the session.
When session-locking=false, applications need to properly synchronize
and auto-lock before mutating shared data, though methods in HttpSession
like setAttribute(), setMaxInactiveInterval() will still have implicit
locking.
对于session内共享对象是否使用auto-lock模式自动进行管理，可以通过设置session-locking
值来决定，如果设置为false，就不进行auto-lock自动模式管理，而是需要应用进行控制，
但无论哪种模式，通过HttpSession对象进行操作，比如setAttribute(), setMaxInactiveInterval()仍然自动会锁
-->
<web-applications>
<web-application>petstore</web-application>
<web-application session-locking="false">billing_app</web-application>
<web-application>ROOT</web-application>
</web-applications>
<!-- In order to share common classes between different applications,
declare the applications to be in the same app-group. The applications
must be run on separate Terracotta nodes; sharing data between different
applications in the same node (e.g., the same app server instance) is
not supported. In order to use a named-classloader element you need to
know the name of the classloader; see the named-loader-debug property in
order to record all registered classloader names in the log file.
可以通过将应用放在同一应用组中来共享class，但必须将应用放在不同Terracotta节点中，
比如放在不同web server实例中，目前Terracotta不支持在同一节点中共享不同应用的class
同时可以通过named-classloader指定class 装载类
-->
<app-groups>
<app-group name="petstore-group">
<web-application>petstore</web-application>
<web-application>billing_app</web-application>
<named-classloader>Standard.system</named-classloader>
</app-group>
</app-groups>
<!-- When enabled, the default, mutations to shared objects made
through reflection behave like normal shared object changes. When
disabled, changes made to shared objects via reflection are not
cluster-wide (disable only if reflection is not used to mutate
shared objects).
默认为TURE,启用 mutations方式来影射共享对象-->
<dso-reflection-enabled>true</dso-reflection-enabled>
</dso>
</application>
</tc:tc-config>