Clustered DatasetManager using XML
Creating a Clustered DatasetManager
URL configUrl = getClass().getResource("clustered.xml"); // 1
DatasetManagerConfiguration datasetManagerConfiguration =
XmlConfiguration.parseDatasetManagerConfig(configUrl); // 2
try (DatasetManager datasetManager =
DatasetManager.using(datasetManagerConfiguration,
ConfigurationMode.CREATE)) { // 3
try (Dataset<Long> dataset = datasetManager.getDataset("orders",
Type.LONG)) { // 4
// use the dataset
}
}
1 | |
2 | Creates a DatasetManagerConfiguration using the configuration URL. |
3 | Creates a clustered DatasetManager using the given DatasetManagerConfiguration and ConfigurationMode (see
Configuration modes). |
4 | Gets the Dataset with name orders and type LONG. |
Getting DatasetManager configuration in XML form
try (DatasetManager datasetManager = DatasetManager.clustered(
URI.create("terracotta://localhost:9510")).build()) { // 1
DatasetManagerConfiguration datasetManagerConfiguration =
datasetManager.getDatasetManagerConfiguration(); // 2
String xmlConfig = XmlConfiguration.toXml(datasetManagerConfiguration)) // 3
}
1 | Creates a clustered DatasetManager. |
2 | Gets the DatasetManagerConfiguration of the DatasetManager. |
3 | Converts the DatasetManagerConfiguration to XML form. |
Clustered DatasetManager XML configuration
<clustered xmlns=
"http://www.terracottatech.com/v1/terracotta/store/clustered"> <!-- 1 -->
<cluster-connection>
<server host="localhost" port="9510"/> <!-- 2 -->
<connection-timeout unit="MILLIS">10</connection-timeout> <!-- 3 -->
<reconnection-timeout unit="MILLIS">20</reconnection-timeout> <!-- 4 -->
<security-root-directory>/path/to/security-dir
</security-root-directory> <!-- 5 -->
<client-alias>client-alias</client-alias> <!-- 6 -->
<client-tags>client-tags</client-tags> <!-- 7 -->
</cluster-connection>
<dataset name="orders" key-type="LONG"> <!-- 8 -->
<!-- dataset configuration -->
</dataset>
<!-- other datasets -->
</clustered>
1 | Declares a clustered DatasetManager configuration. |
2 | Configures a Terracotta server in the cluster (port attribute is optional, default is 9410) |
3 | Configures the connection timeout for this connection (optional, default 20 milliseconds). |
4 | Configures the reconnection timeout for this connection (optional, default 0 milliseconds). |
5 | Configures the security root directory to make a secure connection to the Terracotta cluster (optional). |
6 | Configures an alias to identify this client (optional, default is a randomly generated string). |
7 | Configures tags for this client (optional, default is no tags). |
8 | |
Dataset XML configuration
<dataset name="orders" key-type="LONG"
xmlns:tcs="http://www.terracottatech.com/v1/terracotta/store"> <!--1-->
<tcs:offheap-resource>offheap</tcs:offheap-resource> <!--2-->
<tcs:disk-resource storage-type="FRS">disk</tcs:disk-resource> <!--3-->
<tcs:indexes>
<tcs:index> <!--4-->
<tcs:cell-definition name="cell" type="BOOL"/>
<tcs:type>BTREE</tcs:type>
</tcs:index>
</tcs:indexes>
<tcs:durability-eventual/> <!--5-->
<tcs:advanced> <!--6-->
<tcs:concurrency-hint>16</tcs:concurrency-hint>
</tcs:advanced>
</dataset>
1 | Declares a Dataset configuration. |
2 | Configures an offheap resource for this dataset. |
3 | Configures a disk resource for this dataset (optional) with an optional storage-type attribute that specifies the persistent storage engine to be used. The available engines are described in the section Storage Types below. |
4 | Configures an index for this dataset with a cell definition and its type (optional). |
5 | Configures disk durability for this dataset (optional). |
6 | Advanced Dataset configuration such as concurrency-hint (optional). |
Configuration modes
Defines whether datasets configured in DatasetManagerConfiguration should be created or validated. The three supported configuration modes are:
1. CREATE
![*](chapterTOC_bullet.png)
creates all configured datasets.
![*](chapterTOC_bullet.png)
If any of the datasets already exists then the creation for that dataset fails, and no attempt is made to create any subsequent datasets in the list.
![*](chapterTOC_bullet.png)
If the creation of a dataset fails, an exception is thrown containing the list of datasets that got created before it failed.
![*](chapterTOC_bullet.png)
For example - Suppose we are trying to create three datasets named dataset1, dataset2 and datase3, and dataset2 exists already with the same key type or a different key type. In this scenario dataset1 will get created, but since dataset2 already exists, an exception will be thrown containing the message "A dataset with the name dataset2 already exists, following datasets were created so far: dataset1". No attempt will be made to create dataset3, since the creation stops at the exception for dataset2.
![*](chapterTOC_bullet.png)
If the datasets creation using CREATE mode fails for any reason it is recommended to retry creating the datasets using AUTO mode so that any exceptions related to an already existing dataset can be avoided.
2. VALIDATE
![*](chapterTOC_bullet.png)
validates all configured datasets.
![*](chapterTOC_bullet.png)
If any of the datasets does not exist, or if it exists but has a different key type, then the validation fails and an exception is thrown. The exception contains a message stating whether the validation failed because the dataset does not exist, or because the dataset exists but has a different key type.
![*](chapterTOC_bullet.png)
If the validation fails for a dataset, no validation is performed for the subsequent datasets in the list.
3. AUTO
![*](chapterTOC_bullet.png)
creates datasets if any of the configured datasets don't exist, otherwise it validates the existing datasets.
![*](chapterTOC_bullet.png)
For example - Suppose we are trying to create datasets named dataset1, dataset2 and dataset3, and dataset2 already exists with a different key type. In this scenario dataset1 will get created. Since dataset2 already exists, it will be validated, and an exception will be thrown since the key type is different. As a result, dataset3 will not be created because the exception for dataset2 stops the execution.
Storage Types
One of the following storage types can be specified for a given dataset.
![*](chapterTOC_bullet.png)
FRS - Specifies FRS storage engine
![*](chapterTOC_bullet.png)
HYBRID - Specifies HYBRID storage engine