You can use the Event Replicator Target Adapter to replicate data to Terracotta in memory caches.

The following diagram depicts the interaction between the Event Replicator Target Adapter and Terracotta.

This document describes how to set up this Terracotta support in the Event Replicator Target Adapter. It covers the following topics:

• Requirements

• Implementation Steps

• Terracotta-specific Notes

---

Requirements

Terracotta Version 4.3 must be installed in your enterprise. For complete information, read Terracotta, available in the "IBO and Big Data" documentation on Software AG's Empower web site. The necessary components to connect to the Terracotta target are provided with the delivery of Event Replicator Target Adapter, except for the licenses described under Implementation Steps below.

Implementation Steps

Licenses

Event Replicator Target Adapter must be licensed to communicate with the Terracotta target. This is an additional license to the one you used when installing v. In addition, if you are connecting to/using the enterprise features of the Terracotta cache server, you must also provide a copy of that license to the v environment.

To license Event Replicator Target Adapter for connection to the Terracotta server:

• Obtain a license for the Terracotta target from your Software AG representative. This license will likely be provided to you in the form of an .xml file with a name like <numericprefix>_arttc.xml.

  • Rename this file to arttc.xml.

  • Manually copy this file to <Root>/common/conf.

You will be able to connect to the Terracotta server without this license file, but your ability to use Terracotta features will be limited to 30 minutes of use in a single Event Replicator Target Adapter session.

The use the Terracotta enterprise features:

To use the features of the enterprise versions of the Terracotta products a Terracotta license is required. This is the same license you were provided in order to use the enterprise features of your Terracotta server installation. A copy of this license must be manually placed in a resource location available to Event Replicator Target Adapter:

• Recommended: simply copy the file to:

  Windows: <Root>\EventReplicatorTargetAdapter\art\data\webapps\sqlrep\WEB-INF\classes.

  UNIX: <Root>/EventReplicatorTargetAdapter/art/TargetAdapter/webapps/sqlrep/WEB-INF/classes.

  This is a resource location already "well known" to Event Replicator Target Adapter and the application will load the license from this resource location.

• Optional (not recommended as it involves manually editing an installed file):

  Set the path to the license in the CATALINA_OPTS section of the ERTA.bat (Windows)/ERTA.sh (Unix) file. This file will be found in:

  Windows: <Root>\EventReplicatorTargetAdapter\art\program\bin

  UNIX: <Root>/EventReplicatorTargetAdapter/art/bin.

  Add the property:

  -Dcom.tc.productkey.path=/path/to/terracotta-license.key

  …at the end of the line that sets CATALINA_OPTS.

  For example:

  Windows: set CATALINA_OPTS=-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=%ART_JMX_PORT% -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.tc.productkey.path=/path/to/terracotta-license.key

  UNIX: CATALINA_OPTS="-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=${ART_JMX_PORT} -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false" -Dcom.tc.productkey.path=/path/to/terracotta-license.key

For other possibilities on specifying the location of this file, check the Terracotta documentation.

Terracotta-specific Notes

Cache Configuration File

The Ehcache cache configuration file (ehcache.xml) contains the configuration for the CacheManager that is used by the client. It contains all information about the environment, parameters, caches, etc. At a minimum, the ehcache.xml file used by Event Replicator Target Adapter should contain the following:

<?xml version="1.0" encoding="UTF-8"?>

<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:noNamespaceSchemaLocation="ehcache.xsd" updateCheck="false"
	monitoring="autodetect" dynamicConfig="true">

	<!-- Mandatory Default Cache configuration. These settings will be applied 
		to caches created programmtically using CacheManager.add(String cacheName). 
		The defaultCache has an implicit name "default" which is a reserved cache 
		name. -->
	<defaultCache eternal="true"
		overflowToDisk="false" maxEntriesLocalHeap="1">
		<terracotta/>
	</defaultCache>

	<terracottaConfig url="terracottahost:port" rejoin="true"/> This line is only needed for interaction with the enterprise version of Terracotta.
</ehcache>

For more information about the Cache Configuration File, read Terracotta, available in the "IBO and Big Data" documentation on Software AG's Empower web site.

Cache Definition

Although not necessary, cache definitions can be defined in the Cache Configuration File (ehcache.xml). The path to this file is specified using Event Replicator Target Adapter Administration in the your target configuration.

The main reason to use a cache definition in echache.xml is to enable a client application to search by a particular key. Event Replicator Target Adapter does not require your cache be defined in this file; however, specifying the cache definition in echache.xml does let you control which Adabas descriptor fields are to be marked in the Terracotta cache as keys (searchable fields). If no cache definition exists in echache.xml, the cache will be dynamically created when a CREATE statement (schema) is sent from Event Replicator for Mainframe and all fields specified in the Adabas DDM as descriptors will be marked as searchable in the Terracotta cache. For more information see Searchable Attributes below.

AdabasObject

A Terracotta cache is in general a Key-Value store for Java objects. To store Adabas records in such a Key-Value store the record must be transformed to a Java object (value). The key for this object is the key that is provided by the Event Replication. Unless you specified a custom Primary Key in the replication GFB/GFFT, the ISN by default will be used as key. The Java object that is stored in the cache is an instance of AdabasObject, which is a simple Java class. To retrieve the fields from this objects the method Object evaluateValue(String fieldName) must be used, where fieldname is the long name for this field as defined in the GFFT (e.g. NAME, Address, etc.). The result type depends on the type of the Adabas field:

Adabas Structure	Adabas Object	Example
Field	Java type	String, int, float,
Multiple field	List of Java type	List <String>, List<int>
Group	Adabas Object	AdabasObject
Periodic group	List of Adabas Object	List<AdabasObject>

Searchable Attributes

The data in the Terracotta cache is accessible via the key. To use the Terracotta search capabilities the attributes must be marked as searchable. By default, when a cache is created with receipt of a schema from Event Replicator Target Adapter, any Adabas field marked as a Descriptor in the GFFT is created as a searchable key in the Terracotta cache. For information on how to use Searchable Attributes to query the cache, please refer to the Terracotta documentation in Empower.