|
Release: 2.5.4 Previous Releases
Publish Date: March, 2008 |
rate-9143682-81848
| Article Rating? |
|
|
|
Terracotta Tools Overview
Introduction
This page is a catalog of all of the tools that come with Terracotta.
Eclipse Plugin
The Terracotta Eclipse Plugin provides a self-contained Terracotta runtime environment for developing your clustered applications.
Refer to Eclipse Plugin Quick Start for information about installing the plug-in.
Refer to the Eclipse Plugin Reference Guide for detailed information regarding the features of the plug-in.
Refer to the POJO Clustering Tutorial for a walk-through clustering a simple POJO using the plug-in.
Terracotta Sessions Configurator (sessions-configurator)
The Terracotta Sessions Configuration is a graphical tool that assists you in clustering your webapps session data.
Refer to the Terracotta Sessions Quick Start for information about installing Terracotta and getting started with the The Configurator.
Refer to Sessions Configurator Reference Guide for detailed information regarding the features of The Configurator.
Terracotta Administration Console (admin)
The Terracotta Administration Console is a graphical tool you can use to monitor aspects of your Terracotta Servers.
Refer to Admin Console Guide for detailed information regarding the features of the AdminConsole.
Terracotta Welcome Tool (welcome)
Terracotta Welcome is a graphical tool that serves as an easy introduction to the Terracotta platform. From Terracotta Welcome you can access the Quick Start Guides, run the POJO Samples Launcher, Administration Console, and Sessions Configurator, as well as read the various tutorials.
The Terracotta Welcome can be run by invoking the welcome script in the bin directory of the Terracotta installation:
Windows
> %TERRACOTTA_HOME%\bin\welcome.bat
Unix
> ${TERRACOTTA_HOME}/bin/welcome.sh&
Terracotta Sample Launcher (samples)
Terracotta Sample Launcher is a graphical tool that provides an easy way to run the Terracotta for POJO samples in a point-and-click manner. When run, Sample Launcher automatically starts up the demo Terracotta Server, which it also shuts down upon termination. A selection of samples demonstrating POJO clustering are listed and can be launched. Descriptions of each sample, including information about how to run the sample from the command-line, as well as sample code and configuration can be browsed.
Sample Launcher can be accessed directly from Terracotta Welcome or it can be run from the command-line.
Windows
> %TERRACOTTA_HOME%\tools\pojo\samples.bat
Unix
> ${TERRACOTTA_HOME}/tools/pojo/samples.sh&
Terracotta Archive Tool (archive-tool)
archive-tool is used to gather filesystem artifacts generated by a Terracotta Server or DSO client application for the purpose of contacting Terracotta with a support query.
Windows
> %TERRACOTTA_HOME%\bin\archive-tool.bat <args>
Unix
> ${TERRACOTTA_HOME}/bin/archive-tool.sh <args>
where <args> are:
- [-n] (No Data - excludes data files)
- [-c] (Client - include files from the dso client)
- <path to terracotta config xml file (tc-config.xml)> | <path to data and/or logs directory>
- [<output filename in .zip format>]
Terracotta Make Boot Jar Tool (make-boot-jar)
The make-boot-jar script will generate a boot jar file based on the contents of the current configuration file (or the default configuration if none is present). It's smart enough to detect if the boot jar needs to be re-created, but you can force it to always create one by passing the -w option. It returns with exit code 1 if the boot jar file is incomplete, otherwise the exit code is 0.
Terracotta Scan Boot Jar Tool (scan-boot-jar)
The scan-boot-jar script will verify the contents of the the boot jar file against an L1 configuration. It will list all of the classes declared in the <additional-boot-jar-classes/> section that is not included in the boot jar, as well as classes in the boot jar that is not listed in the <additional-boot-jar-classes/> section. It returns with exit code 1 if the boot jar file is incomplete, otherwise the exit code is 0.
Terracotta Boot Jar Path Tool (boot-jar-path)
boot-jar-path is a helper utility used by the dso-env script for determining the full path to the JVM-specific DSO bootjar. This script is not meant to be used directly.
Terracotta DSO Environment Tool (dso-env)
The dso-env script helps you setup your environment to run a DSO client application, using existing environment variables and setting TC_JAVA_OPTS to a value you can pass to java. It expects JAVA_HOME, TC_INSTALL_DIR, and TC_CONFIG_PATH to be set prior to invocation. dso-env is meant to executed in your custom startup scripts, and is also used by each Terracotta demo script
Windows
set TC_INSTALL_DIR=%TERRACOTTA_HOME%
set TC_CONFIG_PATH=<config specification>
call "%TC_INSTALL_DIR%\bin\dso-env.bat" -q
set JAVA_OPTS=%TC_JAVA_OPTS% %JAVA_OPTS%
call "%JAVA_HOME%\bin\java" %JAVA_OPTS% ...
Unix
TC_INSTALL_DIR=${TERRACOTTA_HOME}
TC_CONFIG_PATH=<config specification>
. ${TC_INSTALL_DIR}/bin/dso-env.sh -q
JAVA_OPTS="${TC_JAVA_OPTS} ${JAVA_OPTS}"
${JAVA_HOME}/bin/java ${JAVA_OPTS} ...
<config specification> above is either the path to a local config file or a <server>:<dso-port> tuple specifying the configuration of a running Terracotta Server. If the config specification is not set, an existing file in the current working directory named tc-config.xml will be used. If no config is specified and no local tc-config.xml is found, the Terracotta runtime will fail to start.
Terracotta dso-java Tool
dso-java is a script that can be used to run a DSO client application in a manner similar to running a standard java application. For instance, one way to run the jtable POJO sample is to first run the demo server:
> ${TERRACOTTA_HOME}/samples/start-demo-server.sh&
... and to change into the jtable directory and invoke dso-java in the following way:
> cd ${TERRACOTTA_HOME}/samples/pojo/jtable
> ${TERRACOTTA_HOME}/bin/dso-java -cp classes demo.jtable.Main
dso-java uses the dso-env helper script to specify the Java runtime options needed to activate the Terracotta runtime. The configuration file, tc-config.xml, is located in the current working directory. If the configuration file was in a different location, specify that location using the tc.config Java system property, e.g.: -Dtc.config=<config-specification>.
<config specification> is a comma-separated list of:
- path to configuration file
- URL to configuration file
- <server host>:<dso-port> of running Terracotta Server
When a <config specification> is comprised of a list of configuration sources, the first configuration successfully obtained will be used.
Run Distributed Garbage Collector Tool (run-dgc)
run-dgc is a utility that causes the specified Terracotta Server to perform distributed garbage collection (dgc). The ability to force a dgc using this script is only available if time period-based collection is disabled in the server configuration. This script is meant to be used by the operator who desires more control of when dgc occurs than is provided via the time period-based collection offered by the server configuration.
Windows
> %TERRACOTTA_HOME%\bin\run-dgc.bat <hostname> <jmx-port>
Unix
> ${TERRACOTTA_HOME}/bin/run-dgc.sh <hostname> <jmx-port>
Further reading:
For more information on distributed garbage collection see the Concept and Architecture Guide.
For information on monitoring the Terracotta Server's garbage collection, see the Terracotta Console Guide.
Starting and Stopping the Terracotta Server (start-tc-server)
Use the start-tc-server script to run the Terracotta Server, optionally specifying a configuration file:
Windows
> %TERRACOTTA_HOME%\bin\start-tc-server.bat [-f <config specification>]
Unix
> ${TERRACOTTA_HOME}/bin/start-tc-server.sh [-f <config specification>]
<config specification> can be one of:
- path to configuration file
- URL to configuration file
- <server host>:<dso-port> of another running Terracotta Server
If no configuration is specified, a file named tc-config.xml in the current working directory will be used. If no configuration is specified and no file named tc-config.xml is found in the current working directory, a default configuration will be used. The default configuration includes no DSO application element and is therefor useful only in development mode, where each DSO client provides it's own configuration.
For production purposes, DSO clients should obtain their configuration from a Terracotta Server using the tc.config system property.
Use the stop-tc-server script to cause the Terracotta Server to gracefully terminate:
Windows
> %TERRACOTTA_HOME%\bin\stop-tc-server.bat [<server-host> <jmx-port>]
Unix
> ${TERRACOTTA_HOME}/bin/stop-tc-server.sh [<server-host> <jmx-port>]
stop-tc-server uses JMX to ask the server to terminate. If you have secured your server, requiring authenticated access, you will be prompted for a password.
Further reading:
For more information on securing your server for JMX access see the Configuration Guide and Reference.
Terracotta Version Tool (version)
Terracotta Version Tool is a utility script that outputs information about the Terracotta installation, including the version, date, and version-control change number from which the installation was created. When contacting Terracotta with a support query, please include the output from Version Tool to expedite the resolution of your issue.
Windows
> %TERRACOTTA_HOME%\bin\version.bat
Unix
> ${TERRACOTTA_HOME}/bin/version.sh&
Appendix
Contacting Terracotta
Contact Terracotta at the following:
Web site: http://www.terracotta.org
Online forums: http://forums.terracottatech.com/forums/
Information: info@terracottatech.com
Platform Support
See Platform Support for information on which platforms are supported by Terracotta.
See the Integrations space to see the status of integrations with third-party technologies.
Copyright Information
Copyright © 2005-2007
Terracotta, Inc.
All Rights Reserved
This publication (the "Documentation") and the Terracotta software which it describes (the "Software") are protected to the maximum extent permitted under applicable law, including but not limited to, the regulations set forth in Title 17 of the United States Code, and California law. This Documentation, or any parts thereof, may not be reproduced in any form, by any method, for any purpose, without the express written consent of Terracotta. Terracotta makes no warranty, either express or implied, including but not limited to any implied warranties of merchantability or fitness for a particular purpose, with respect to the Software discussed in this Documentation, and the Documentation itself (collectively, "the Materials"). The Materials are made available solely on an "as-is" basis. In no event shall Terracotta be liable to anyone for special, collateral, incidental, indirect, punitive, exemplary, or consequential damages in connection with, or arising from the purchase or use of, the Materials. Under no circumstances and regardless of the cause of action alleged, shall Terracotta's liability exceed the purchase price of the Software described herein. Terracotta reserves the right to revise and improve its Software and Documentation as it deems fit. The Documentation describes the state of the Software at the time of publication.
Trademarks
"Terracotta," the stylized "T" logo, and "Open Terracotta" are trademarks of Terracotta. All other brand names, product names, or trademarks belong to their respective holders. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. All other brand names, product names, or trademarks belong to their respective holders.
Government Use
Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in FAR 12.212 (Commercial Computer Software-Restricted Rights) and DFAR 267.7202 (Rights in Technical Data and Computer Software), as applicable.
