THIS IS ARCHIVE DOCUMENTATION FOR TERRACOTTA v. 3.1. For the current release, see the current DSO documentation »

Release: 3.1.1
Publish Date: October, 2009

General FAQ

For technical issues not covered here, see the Technical FAQ and the Troubleshooting Guide.

The Terracotta FAQ is divided into the following subject areas:

General Questions

Q: Where can I get the enterprise version of Terracotta (certified release) software?

A: You can download trial versions of the enterprise software from the [Terracotta download page]. For more information about Terracotta enterprise software and services, see the [enterprise pages] or email us.

Q: Is there any difference in functionality between Terracotta open source software and Terracotta enterprise software?

A: Terracotta enterprise offerings include industry-leading technical support, certified software patches and updates, and outstanding support tools. Also available is a license key manager to help facilitate managing software compliance. For differences in functionality between the enterprise and open-source versions, see [the product matrix] for more information.

Q: What's your license?

A: The Terracotta Public License, which is the Mozilla Public License, version 1.1, with a few minor changes to make it specific to Terracotta, including an attribution requirement. For more details See the Licensing FAQ section.

Q: Where do I find detail and pricing information for subscription support?

A: See our [product information]. Contact us for pricing.

Q: Where do I find detail and pricing information for training?

A: See our [training information]. Contact us for pricing.

Q: I received a product-key (or license) file, now how do I use it?

A: If you received a file called product.key from Terracotta to run a version of Terracotta other than the OSS version, save it to your Terracotta installation's root directory and start or restart Terracotta.

Note the following:

• The name of the product-key file should not be changed.
• Each Terracotta client and server instance in your cluster requires a copy of the product-key file.
• The number of Terracotta clients that can run simultaneously in the cluster is fixed by the product key and cannot be changed without obtaining a new product key.
• Trial product keys expire after a trial period. See the file product.key for the limitations on the key you have. Expiration warnings are issued both to logs and standard output to allow enough time to contact Terracotta for an extension.
• If you are using an express installation, such as Terracotta for Hibernate or distributed cache, you must set one of the following properties for your application, depending on the location of product.key:
  If product.key is in the Terracotta installation directory:

  -Dtc.install-root=/path/to/tc-install-dir
  

  If product.key is in a different location:

  -Dcom.tc.productkey.path=/path/to/product.key
  

  If you are using a Terracotta configuration file (tc-config.xml by default), product.key can be specified in that file by adding the following to the beginning of the configuration: <tc-properties> <property name="productkey.path" value="path/to/product.key" /> </tc-properties>

Q: How can I verify what my product key allows?

A: There are a number of ways to verify what features are allowed and what limitations are imposed by your product key. The first is by looking at the file containing the product key. Since it's a readable text file, you can view its contents.

Second, as a Terracotta instance starts, a message detailing what the product key allows is sent to standard output.

Third, a message similar to the following should appear in the Terracotta log:

2008-09-26 15:24:20,245 INFO - Terracotta license: #999, for MyCompany, type: production; max clients: 999; enabled modules: {all}; DSO HA enabled: true

Finally, see the server information panels in the Terracotta Developer Console#server panel or Terracotta Operations Center#server panel.

Q: Why does Terracotta not support feature X?

A: Terracotta is an open-source project. It supports most of the JDK, as well as many popular open-source frameworks, application servers and projects. We are always working support more, but Java is a big place, and we have to prioritize what we work on.

If Terracotta does not currently support something you would like to use, here is what you can do:

• Contact Us. Our priorities lie with our customers. If you want something built on Enterprise time, not OSS time, contact us to see how we can help.
• Contribute a patch. Open-source happens because of you. See How To Contribute to see how you can improve Terracotta.
• File a JIRA. If you would like to see a feature added, or have found a bug, we track everything through JIRA.
• Vote on a JIRA. If there is already a JIRA filed, you can vote for it. We review all JIRA's at the start of every release, JIRA's with more votes get more consideration.
• Post a message on the respective forum group. If the feature you are looking for is support for a particular framework (such as Wicket, Spring, Hibernate, EHCache etc) then you should also post a message on their forums. This helps the members of those projects to be aware of the demand for supporting Terracotta.

Product Questions

For troubleshooting tips, check out the Troubleshooting Guide.

Q: What is the best way to get started with Terracotta software?

A: Follow the progressive learning track that starts with [What Is Terracotta].

Q: Can I skip the learning track and go straight to working with the software?

A: Yes. See [Tutorials].

Q: Which application stacks does Terracotta support? What platforms does Terracotta run on?

A: Supported platforms are listed in Platform Support. For the status of Terracotta integrations with other technologies, contact us.

Q: Do Terracotta clusters have a single point of failure?

A: No. All data in a Terracotta cluster is managed by the Terracotta Server Array. The Server Array can be configured to run in a two-server active-standby configuration to provide failover services. The standby server immediately takes command if the active fails, while the active automatically becomes the passive when restored. Available in the Terracotta FX product is the ability to configure multiple server group stripes for added scale.

Q: Terracotta doesn't just keep data in memory, it also writes to disk, so won't everything slow down during writes?

A: To both extend the available memory heap and persist data, Terracotta uses asynchronous write operations that don't impact performance. In addition, disk writes can be reduced using optimization strategies such as increasing server and client heap sizes and implementing better locality of reference.

Q: As my application is scaled up with more Terracotta clients, won't that overload the Terracotta server?

A: Only changes to clustered data are communicated to and from the Terracotta server. With sufficient (commodity) hardware, ample memory, and a fast network, Terracotta scales to dozens of nodes. With software optimizations such as lazy-loading and partial collections, throughput can reach the speed of your networks ports. Enterprise customers can benefit further from a multi-server, single-cluster configuration for high-efficiency scaling and performance gain.

Q: Isn't clustering extremely complicated because it involves individually debugging many nodes?

A: There is no requirement to work individually with each client node. Terracotta features are available to give you command and control over the entire cluster from a single machine. For example:

• Push a single configuration file from the server to all clients.
• Use visual tools to track lock use, object graphs, client health, and more.
• Configure a single backup that can restore all shared data.

Q: Are you a JVM?

A: We are not a JVM. Terracotta is made up of two parts: library software for your JVM and a separate software server. The software server is typically deployed in a separate jvm process. At the application level, our software libraries plug in to existing off the shelf application servers and JVM's, like Sun Hotspot & Tomcat.

Q: What is the Terracotta Client?

A: The Terracotta Client is a Java library that operates inside your JVM and injects runtime clustering behavior into the classes you specify. When your JVM starts, the Terracotta Client automatically connects to the Terracotta Server to engage the clustering services such as the lock manager, object manager, and memory manager.

more »

Q: What is the Terracotta Server Array used for?

A: The Terracotta Server Array coordinates shared objects among all the associated Terracotta Clients; it also stores a copy of the current state of every shared object and writes associated changes to disk.

more »

Q: Do you use byte code instrumentation?

A: We utilize byte code instrumentation to weave functionality into your application at runtime.

Q: Does Terracotta work in App Servers?

A: Yes. See [Integration Guides] for how to integrate Terracotta with a number of popular application servers and the [Encyclopedia of Integrations] for a full list of the status of Terracotta integrations with application servers.

Q: Where can I find more technical questions like these?

A: See the Technical FAQ for more technical questions on Terracotta.

Support Questions

Q: Do you offer support?

A: Yes. We do offer subscriptions - both 5x12 (Monday-Friday 6am-6pm, PST) and 7x24. See [Support] for details.

Q: How do I open a support ticket?

A: Terracotta customers can either call or email our support line, or log into our support portal to report an issue. Issues can also be reported through the Terracotta community issue-tracking system.

Q: Do you offer professional services?

A: Yes. We have a team of services engineers who have deep expertise with Terracotta products, enterprise Java development, and deploying large scale java applications. See [Services] for details.

Q: Do you have a network of consulting partners?

A: Yes, you may contact any of our open source consulting partners. See [Partners] for a list of Terracotta partners.

Q: Can I get training on Terracotta products?

A: We offer custom training on site and have a schedule of 2-day training courses in various cities in the Americas, Europe and Asia. See [Training] for details.

Q: What kind of support options do you provide for ISV's?

A: We offer a 7x24 custom support option for our ISV partners. Each support offering is customized to meet the ISV current and future support needs. For more information, contact info@terracotta.org

Q: Is there a guide describing the Terracotta deployment process from start to finish?

A: Start with the [Integration Overview] and follow the instructions through the [Operations Guide].

Licensing Facts

This FAQ provides answers to commonly asked questions related to the Terracotta Public License ("TPL"). It is provided for informational purposes only. It is not part of, nor does it modify, amend, or supplement the terms of the TPL. The TPL is a legal agreement that governs the rights granted with respect to material licensed under it, so please read it carefully. If there is any conflict between this FAQ and the TPL, the terms of the TPL shall govern. This FAQ should not be regarded as legal advice. If you need legal advice, you should contact your own attorney.

Guaranteed Rights: The Things Everyone Can Always Do Under the Terracotta Public License

Whether you're using Terracotta for yourself or your enterprise, or you're using Terracotta to build software for someone else's enterprise, you can always:

• run Terracotta for free
• distribute Terracotta for free
• implement and integrate Terracotta with other programs
• fix bugs
• build new programs
• share contributions

Using Terracotta for Yourself or Your Enterprise

If you're using Terracotta in either its original or modified form for yourself, or for your enterprise, then you can always:

• run Terracotta in your enterprise, with no attribution
• modify and edit Terracotta code, and deploy it without attribution
• use Terracotta code taken from another product that uses Terracotta, with no attribution

Using Terracotta Within Your Enterprise to Benefit Others Who Are Outside Your Enterprise

Many developers use Terracotta within their enterprise, in a way that benefits users who are outside their enterprise. For example, Google can run Terracotta internally, to benefit users who visit its site. Similarly, an ASP can cluster its application service with Terracotta, to provide a better experience to its users. In these cases, you can always:

• run Terracotta in your enterprise, with no attribution
• modify and edit Terracotta code, and deploy it without attribution
• use Terracotta code taken from another product that uses Terracotta, with no attribution

Distributing Terracotta to Others, Outside Your Enterprise

If you're going to distribute Terracotta in either its original or modified form to someone else, outside your enterprise, then you can always:

• use Terracotta code in its original form in your software, as long as you include attribution and you license the Terracotta files under the TPL
• modify and edit Terracotta code and use it in your software, as long as the changes are licensed under the TPL
• license your own code under a license that you choose, including a proprietary license

Real-World Licensing Examples

Q: I am an ISV. Can I embed Terracotta software in my software, and then distribute it without open sourcing my software?

A: Yes, you can redistribute Terracotta code in your software without open sourcing, as long as you provide attribution to Terracotta. You can ship your own code under a license of your choice, including a proprietary license. You'll need to ship the Terracotta code (and any modifications you make to it) under the Terracotta Public License.

Q: I'm running a web app under an app server, and I'm using Terracotta as well. Do I need to comply with the attribution requirement?

A: No. In this case, you're not distributing any Terracotta code, so the attribution requirement doesn't apply.

Q: I want to write software that uses Terracotta, but my software would run in headless mode, without a GUI. If I distribute my software, how would I comply with the attribution requirement?

A: If you distribute your software and it includes Terracotta code, you'll need to include attribution. The attribution requirement applies to all user interfaces, including command-line interfaces, and not just GUIs.

Q: I work for a large company and want to use Terracotta to cluster my apps. If I only deploy Terracotta within my company (including contractors who work at my company), do I need to comply with the attribution requirement?

A: No. You are only required to include the attribution notice if you redistribute Terracotta, or any derivative works that you build from Terracotta. "Redistribute" means to give (or make available for download) the software to a third-party – in other words, someone outside of your company (other than contractors who work at your company).

Miscellaneous Licensing Questions

What kind of license do you have?

A: See "What's your license?"

How do you use a license file?

See "I received a license file, now how do I use it?"

Q: I'd like to integrate Terracotta with my own software and distribute it. Can I do that under the TPL?

A: Yes, you can integrate Terracotta with your own code, but if you want to redistribute your resulting product, you'll need to redistribute the original Terracotta files that you used and any modifications that you make to them in open-source form under the TPL. This ensures that your modifications get licensed back to the community. You can distribute your own code under any license that you choose, including a proprietary license.

Q: Does the attribution requirement apply if I don't make changes to Terracotta code?

A: Yes. The attribution requirement applies to any distribution of Terracotta code, even if it is unchanged.

Q: Does the attribution requirement apply if I only distribute changes to the Terracotta code?

A: Yes. The attribution requirement applies to any distribution of Terracotta code, even if you're just distributing modifications.

Q: I'd like to use Terracotta code in my software and then distribute it, but I don't like the attribution requirement. Do I have any other licensing options?

A: Yes. We offer an enterprise version of Terracotta, available under a commercial license, for an annual subscription. Our enterprise packages eliminate the attribution requirement, and they include mission-critical support, plus warranty and indemnification assurances. For more information, please contact info@terracotta.org.

Q: Can I distribute Terracotta?

A: Yes. You can make and distribute unlimited copies of Terracotta covered by the TPL without payment of royalties or license fees, but you must redistribute Terracotta with attribution and under the TPL. If you bundle Terracotta with your own software, you have the freedom to choose a license for your own software.

Q: If I make changes to Terracotta source code and use them internally, do I have to contribute those changes back to Terracotta?

A: No. If you don't distribute those changes outside your enterprise, then you don't need to contribute those changes back.

Q: Can I make changes to Terracotta source code and distribute those changes?

A: Yes, as long as you retain the attribution to the original code developers and that you share any code changes by publishing the source code along with your modifications.

Q: Does Terracotta link to third-party software that may require different licenses?

A: Yes. Terracotta will frequently bundle third-party Java libraries as a convenience for our users. A complete list of bundled third-party libraries and their respective licensing information can be found as part of the Terracotta download.

Q: If I have a question that isn't answered in the FAQ, how can I get help?

A: We will try to answer any questions you may have. Please post your questions to our licensing forum at http://forums.terracotta.org/forums/forums/list or you can email us at license@teracotta.org.