Clustered DatasetManager using XML

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	Gets the clustered DatasetManager configuration URL (see Clustered DatasetManager XML configuration).
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.

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 xmlns=
"http://www.terracottatech.com/v1/terracotta/store/clustered"> 
<cluster-connection>
<server host="localhost" port="9510"/> 
<connection-timeout unit="MILLIS">10</connection-timeout> 
<reconnection-timeout unit="MILLIS">20</reconnection-timeout> 
<security-root-directory>/path/to/security-root-directory
</security-root-directory> 
<client-alias>client-alias</client-alias> 
<client-tags>client-tags</client-tags> 
</cluster-connection>
<dataset name="orders" key-type="LONG"> 

</dataset>

</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	Declares a Dataset with name orders, key type LONG and its configuration (see Dataset XML configuration).

<dataset name="orders" key-type="LONG"
xmlns:tcs="http://www.terracottatech.com/v1/terracotta/store"> 
<tcs:offheap-resource>offheap</tcs:offheap-resource> 
<tcs:disk-resource storage-type="FRS">disk</tcs:disk-resource> 
<tcs:indexes>
<tcs:index> 
<tcs:cell-definition name="cell" type="BOOL"/>
<tcs:type>BTREE</tcs:type>
</tcs:index>
</tcs:indexes>
<tcs:durability-eventual/> 
<tcs:advanced> 
<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).

Defines whether datasets configured in DatasetManagerConfiguration should be created or validated. The three supported configuration modes are:

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.

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.

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.

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.

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.