This site hosts historical documentation. Visit www.terracotta.org for recent product information.
This document shows you how to add Terracotta clustering to an application that is using Quartz Scheduler. Use this express installation if you have been running your application:
To set up the cluster with Terracotta, you will add a Terracotta JAR to each application and run a Terracotta server array. Except as noted below, you can continue to use Quartz in your application as specified in the Quartz documentation.
To add Terracotta clustering to an application that is using Quartz, follow these steps:
For guaranteed compatibility, use the JAR files included with the Terracotta kit you are installing. Mixing with older components may cause errors or unexpected behavior.
To install the Quartz Scheduler in your application, add the following JAR files to your application's classpath:
${TERRACOTTA_HOME}/quartz/quartz-terracotta-ee-<version>.jar
<version> is the current version of the Quartz-Terracotta JAR.${TERRACOTTA_HOME}/quartz/quartz-<quartz-version>.jar
${TERRACOTTA_HOME}/common/terracotta-toolkit-<API-version>-runtime-ee-<version>.jar
The Terracotta Toolkit JAR contains the Terracotta client libraries. <API-version> refers to the Terracotta Toolkit API version. <version> is the current version of the Terracotta Toolkit JAR.If you are using the open-source edition of the Terracotta kit, no JAR files will have "-ee-" as part of their name.
If you are using a WAR file, add these JAR files to its WEB-INF/lib
directory.
Most application servers (or web containers) should work with this installation of the Quartz Scheduler. However, note the following:
|
The Quartz configuration file, quartz.properties
by default, should be on your application's classpath. If you are using a WAR file, add the Quartz configuration file to WEB-INF/classes
or to a JAR file that is included in WEB-INF/lib
.
To be clustered by Terracotta, the following properties in quartz.properties
must be set as follows:
# Do not use the jobStore class TerracottaJobStore unless you are using the open-source version of the Terracotta Server Array.
org.quartz.jobStore.class = org.terracotta.quartz.EnterpriseTerracottaJobStore
org.quartz.jobStore.tcConfigUrl = <path/to/Terracotta/configuration>
The property org.quartz.jobStore.tcConfigUrl
must point the client (or application server) at the location of the Terracotta configuration.
In a Terracotta cluster, the application server is also known as the client. |
The client must load the configuration from a file or a Terracotta server. If loading from a server, give the server’s hostname and its Terracotta DSO port (9510 by default). The following example shows a configuration that is loaded from the Terracotta server on the local host:
# Do not use the jobStore class TerracottaJobStore unless you are using the open-source version of the Terracotta Server Array.
org.quartz.jobStore.class = org.terracotta.quartz.EnterpriseTerracottaJobStore
org.quartz.jobStore.tcConfigUrl = localhost:9510
To load Terracotta configuration from a Terracotta configuration file (tc-config.xml
by default), use a path. For example, if the Terracotta configuration file is located on myHost.myNet.net
at /usr/local/TerracottaHome
, use the full URL along with the configuration file’s name:
# Do not use the jobStore class TerracottaJobStore unless you are using the open-source version of Terracotta Server Array.
org.quartz.jobStore.class = org.terracotta.quartz.EnterpriseTerracottaJobStore
org.quartz.jobStore.tcConfigUrl = file://myHost.myNet.net/usr/local/TerracottaHome/tc-config.xml
If the Terracotta configuration source changes at a later time, it must be updated in configuration.
A Quartz scheduler has a default name configured by the following quartz.properties
property:
org.quartz.scheduler.instanceName = QuartzScheduler
Setting this property is not required. However, you can use this property to instantiate and differentiate between two or more instances of the scheduler, each of which then receives a separate store in the Terracotta cluster.
Using different scheduler names allows you to isolate different job stores within the Terracotta cluster (logically unique scheduler instances). Using the same scheduler name allows different scheduler instances to share the same job store in the cluster.
Start the Terracotta server:
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/start-tc-server.sh &
Microsoft Windows
[PROMPT] ${TERRACOTTA_HOME}\bin\start-tc-server.bat
Start the Terracotta Developer Console:
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/dev-console.sh &
Microsoft Windows
[PROMPT] ${TERRACOTTA_HOME}\bin\dev-console.bat
This step shows you how to run clients and servers on separate machines and add failover (High Availability). You will expand the Terracotta cluster and add High Availability by doing the following:
These tasks bring your cluster closer to a production architecture.
Create a Terracotta configuration file called tc-config.xml
with contents similar to the following:
<servers>
<!-- Sets where the Terracotta server can be found. Replace the value of host with the server's IP address. -->
<server host="server.1.ip.address" name="Server1">
<data>%(user.home)/terracotta/server-data</data>
<logs>%(user.home)/terracotta/server-logs</logs>
</server>
<!-- If using a standby Terracotta server, also referred to as an ACTIVE-PASSIVE configuration, add the second server here. -->
<server host="server.2.ip.address" name="Server2">
<data>%(user.home)/terracotta/server-data</data>
<logs>%(user.home)/terracotta/server-logs</logs>
</server>
<!-- If using more than one server, add an <ha> section. -->
<ha>
<mode>networked-active-passive</mode>
<networked-active-passive>
<election-time>5</election-time>
</networked-active-passive>
</ha>
</servers>
<!-- Sets where the generated client logs are saved on clients. -->
<clients>
<logs>%(user.home)/terracotta/client-logs</logs>
</clients>
</tc:tc-config>
tc-config.xml
.tc-config.xml
to a location accessible to the Terracotta servers.org.quartz.jobStore.tcConfigUrl
property in quartz.properties
to list both Terracotta servers:
org.quartz.jobStore.tcConfigUrl = server.1.ip.address:9510,server.2.ip.address:9510quartz.properties
to each application node and ensure that it is on your application's classpath. If you are using a WAR file, add the Quartz configuration file to WEB-INF/classes
or to a JAR file that is included in WEB-INF/lib
.Start the Terracotta server in the following way, replacing "Server1" with the name you gave your server in tc-config.xml
:
UNIX/Linux
[PROMPT] ${TERRACOTTA_HOME}/bin/start-tc-server.sh -f <path/to/tc-config.xml> -n Server1 &
Microsoft Windows
[PROMPT] ${TERRACOTTA_HOME}\bin\start-tc-server.bat -f <path\to\tc-config.xml> -n Server1 &
If you configured a second server, start that server in the same way on its machine, entering its name after the -n
flag. The second server to start up becomes the "hot" standby, or PASSIVE. Any other servers you configured will also start up as standby servers.
To learn more about working with a Terracotta cluster, see the following documents:
tc-config.xml
is propagated and loaded in a Terracotta cluster in different environments.