Chapter 11. Remotely Creating Data Grid Caches
Add caches to Data Grid Server so you can store data.
11.1. Cache Configuration with Data Grid Server
Caches configure the data container on Data Grid Server.
You create caches at run-time by adding definitions based on org.infinispan
templates or Data Grid configuration through the console, the Command Line Interface (CLI), the Hot Rod endpoint, or the REST endpoint.
When you create caches at run-time, Data Grid Server replicates your cache definitions across the cluster.
Configuration that you declare directly in infinispan.xml
is not automatically synchronized across Data Grid clusters. In this case you should use configuration management tooling, such as Ansible or Chef, to ensure that configuration is propagated to all nodes in your cluster.
11.2. Default Cache Manager
Data Grid Server provides a default Cache Manager configuration. When you start Data Grid Server, it instantiates the Cache Manager so you can remotely create caches at run-time.
Default Cache Manager
<!-- Creates a Cache Manager named "default" and exports metrics. --> <cache-container name="default" statistics="true"> <!-- Adds cluster transport that uses the default JGroups TCP stack. --> <transport cluster="${infinispan.cluster.name:cluster}" stack="${infinispan.cluster.stack:tcp}" node-name="${infinispan.node.name:}"/> </cache-container>
Examining the Cache Manager
After you start Data Grid Server and add user credentials, you can access the default Cache Manager through the Command Line Interface (CLI) or REST endpoint as follows:
CLI: Use the
describe
command in the default container.[//containers/default]> describe
-
REST: Navigate to
<server_hostname>:11222/rest/v2/cache-managers/default/
in any browser.
11.3. Creating Caches with the Data Grid Console
Dynamically add caches from templates or configuration files through the Data Grid console.
Prerequisites
Create a user and start at least one Data Grid server instance.
Procedure
-
Navigate to
<server_hostname>:11222/console/
in any browser. - Log in to the console.
- Open the Data Container view.
- Select Create Cache and then add a cache from a template or with Data Grid configuration in XML or JSON format.
- Return to the Data Container view and verify your Data Grid cache.
11.4. Creating Caches with the Data Grid Command Line Interface (CLI)
Use the Data Grid CLI to add caches from templates or configuration files in XML or JSON format.
Prerequisites
Create a user and start at least one Data Grid server instance.
Procedure
- Create a CLI connection to Data Grid.
Add cache definitions with the
create cache
command.Add a cache definition from an XML or JSON file with the
--file
option.[//containers/default]> create cache --file=configuration.xml mycache
Add a cache definition from a template with the
--template
option.[//containers/default]> create cache --template=org.infinispan.DIST_SYNC mycache
TipPress the tab key after the
--template=
argument to list available cache templates.
Verify the cache exists with the
ls
command.[//containers/default]> ls caches mycache
Retrieve the cache configuration with the
describe
command.[//containers/default]> describe caches/mycache
11.5. Creating Remote Caches with Hot Rod Clients
When Hot Rod Java clients attempt to access caches that do not exist, they return null
for remoteCacheManager.getCache("myCache")
invocations. To avoid this scenario, you can configure Hot Rod clients to create caches on first access using cache configuration.
Procedure
-
Use the
remoteCache()
method in theConfigurationBuilder
or use theconfiguration
andconfiguration_uri
properties inhotrod-client.properties
.
ConfigurationBuilder
File file = new File("path/to/infinispan.xml") ConfigurationBuilder builder = new ConfigurationBuilder(); builder.remoteCache("another-cache") .configuration("<distributed-cache name=\"another-cache\"/>"); builder.remoteCache("my.other.cache") .configurationURI(file.toURI());
hotrod-client.properties
infinispan.client.hotrod.cache.another-cache.configuration=<distributed-cache name=\"another-cache\"/> infinispan.client.hotrod.cache.[my.other.cache].configuration_uri=file:///path/to/infinispan.xml
When using hotrod-client.properties
with cache names that contain the .
character, you must enclose the cache name in square brackets as in the preceding example.
You can also create remote caches through the RemoteCacheManager
API in other ways, such as the following example that adds a cache configuration with the XMLStringConfiguration()
method and then calls the getOrCreateCache()
method.
However, Data Grid does not recommend this approach because it can more difficult to ensure XML validity and is generally a more cumbersome way to create caches. If you are creating complex cache configurations, you should save them to separate files in your project and reference them in your Hot Rod client configuration.
String cacheName = "CacheWithXMLConfiguration"; String xml = String.format("<distributed-cache name=\"%s\" mode=\"SYNC\">" + "<encoding media-type=\"application/x-protostream\"/>" + "<locking isolation=\"READ_COMMITTED\"/>" + "<transaction mode=\"NON_XA\"/>" + "<expiration lifespan=\"60000\" interval=\"20000\"/>" + "</distributed-cache>" , cacheName); remoteCacheManager.administration().getOrCreateCache(cacheName, new XMLStringConfiguration(xml));
Hot Rod code examples
Try some Data Grid code tutorials that show you how to create remote caches in different ways with the Hot Rod Java client.
Visit Data Grid code examples.
11.6. Creating Data Grid Caches with HTTP Clients
Add cache definitions to Data Grid servers through the REST endpoint with any suitable HTTP client.
Prerequisites
Create a user and start at least one Data Grid server instance.
Procedure
-
Create caches with
POST
requests to/rest/v2/caches/$cacheName
.
Use XML or JSON configuration by including it in the request payload.
POST /rest/v2/caches/mycache
Use the ?template=
parameter to create caches from org.infinispan
templates.
POST /rest/v2/caches/mycache?template=org.infinispan.DIST_SYNC
11.7. Cache Configuration
You can provide cache configuration in XML or JSON format.
XML
<distributed-cache name="myCache" mode="SYNC"> <encoding media-type="application/x-protostream"/> <memory max-count="1000000" when-full="REMOVE"/> </distributed-cache>
JSON
{ "distributed-cache": { "name": "myCache", "mode": "SYNC", "encoding": { "media-type": "application/x-protostream" }, "memory": { "max-count": 1000000, "when-full": "REMOVE" } } }
JSON format
Cache configuration in JSON format must follow the structure of an XML configuration. * XML elements become JSON objects. * XML attributes become JSON fields.