Embedded global cache

Use the global cache that is supplied with IBM® Integration Bus to store data that you want to reuse.

The global cache is embedded in the integration node. By default, the cache is disabled; to use the cache, select an appropriate cache policy. The default cache policy creates a default topology of cache components in a single integration node. The alternatives to the default topology are to have no policy, so that you can control your own topology by setting cache properties on the integration servers, or to use an XML policy file to enable the cache across multiple integration nodes.

In IBM Integration Bus Version 10.0.0.2 or later, the embedded global cache can use a WebSphere® eXtreme Scale enterprise data grid. Enterprise data grids use the eXtreme data format (XDF) instead of Java™ object serialization. XDF allows for class evolution. With class evolution, you can evolve the class definitions that are used in the data grid without affecting older applications that are using previous versions of the class. For more information, see Enterprise data grid overview in the WebSphere eXtreme Scale product documentation. To enable the use of the enterprise data grid, an integration node must have the following configuration:

Integration node must be at IBM Integration Bus Version 10.0.0.2 or later.
Integration node must have a function level set to 10.0.0.2 or later.

For information about checking and setting function levels, see Changing the function level of your integration nodes.

Note: If you have a multiple integration node cache topology, all integration nodes must be configured to use the enterprise data grid, or all integration nodes must be configured to not use the enterprise data grid; see Multi-integration node cache topologies.

To find out more about the differences between the embedded cache and the external grid, see Differences between the embedded global cache and an external WebSphere eXtreme Scale grid.

The default topology

By default, one integration server in the integration node hosts a catalog server. The catalog server controls placement of data and monitors the health of container servers. Up to three other integration servers in that integration node host container servers. A container server is a component that is embedded in the integration server that holds a subset of the cache data. The catalog server and container servers are placed in integration servers dynamically when the integration node starts. All integration servers can communicate with the global cache, regardless of whether they are hosting catalog servers, container servers, or neither. Each integration server contains a cache manager, which manages the cache components that are embedded in that integration server. For a description of the cache components, see Data caching terminology.

Placement of the catalog server is reset when the integration node is restarted. By default, the integration node sets a range of ports to use, but you can specify a particular range of ports. If you stop the integration server that contains the catalog server, the global cache becomes unavailable. If you stop and restart integration servers that host container servers, the container servers are reassigned dynamically. Existing cache data is preserved and rebalanced automatically, unless you stop all container servers. Integration servers are configured in the following order:

The first integration server to start is a catalog server and a container server. This integration server uses the first four ports from the range.
The second integration server to start is a container server only; it uses the three ports in the range (ports 5 - 7).
The third and fourth integration servers to start are container servers only, and use ports 8 - 10 and 11 - 13 from the range.
If further integration server are started, they do not host global cache components. However, all integration servers can communicate with the global cache as clients.
If you stop the integration server that contains the catalog server, the global cache becomes unavailable.
If you stop the second, third, or fourth integration server, the container server of the stopped integration server is assigned to the next integration server that starts.

If you restart the integration server that hosts the catalog server, it can no longer communicate with the container servers in other integration servers. Although these container servers are still running, they are no longer part of the cache, and your data is lost. Therefore, you must also restart the integration servers that host the container servers. Alternatively, restart the integration node to reset all cache components.

When you use the default topology, the cache properties for individual integration servers are read only; an error is issued if you try to change them. When you use the default topology, you can specify the range of ports that the cache manager uses, and the listener host that is used by the cache components. If your computer has more than one host name, setting the listener host ensures that the cache components use the correct host name. To set specific properties for the integration server, you must first change the cache policy property to none. The integration server properties that were set most recently by the broker-level policy are retained as a starting point for customization.

Multi-integration node cache topologies

To share data across integration nodes, or enhance the availability of the cache, you must create a policy file. The policy file is an XML file that the cache manager uses to connect the caches of multiple integration nodes. Set the cache policy to the fully qualified name of the policy file. Use the policy file to specify the names of the integration nodes that will share the cache data, the number of catalog servers in each integration node, and the port range and listener host for each integration node to use. You can also use a policy file to configure a multi-instance integration node to host container servers. Some sample policy files are provided in the installation directory. You can copy and customize these policy files for your own system. The sample XML files describe the following configurations:

A single integration node that hosts two catalog servers; if one catalog server fails, the global cache switches to the other one.
Two integration nodes that share a catalog server that is hosted by the first integration node.
Two integration nodes that each host a catalog server; if one catalog server fails, the global cache switches to the catalog server in the other integration node.
Three integration nodes in a high availability scenario. Two integration nodes each host a catalog server, and a multi-instance integration node hosts two container servers. If the active instance of the multi-instance integration node fails, the global cache switches to the container servers in the standby instance.

For more information, see Configuring the global cache for multiple integration nodes and Configuring the global cache for multi-instance integration nodes.

In IBM Integration Bus Version 10.0.0.2, the global cache can use a WebSphere eXtreme Scale enterprise data grid. If you have a multiple integration node cache topology, all integration nodes must be configured to use the enterprise data grid, or all integration nodes must be configured to not use the enterprise data grid. If you do not want the global cache to use enterprise data grids, all integration nodes must have no function level set, or a function level set to 10.0.0.1 or earlier. For information about checking and setting function levels, see Changing the function level of your integration nodes.

Customizing the embedded topology

You can set properties explicitly for each integration server. For example, you might want to specify particular integration servers to host the catalog and container servers so that you can tune integration node performance. When the cache policy is set to none, the cache manager in each integration server uses the values that you set. The integration server properties that were set most recently by the integration node-level policy are retained as a starting point for customization.

If you stop the integration server that contains the catalog server, the cache becomes unavailable and the data in the cache is lost. Therefore, if you switch off the default topology, ensure that you place the catalog server appropriately. If you restart the integration server that hosts the catalog server, it can no longer communicate with the container servers in other integration servers. Although these container servers are still running, they are no longer part of the cache, and your data is lost. Therefore, you must also restart the integration servers that host the container servers. Alternatively, restart the integration node to reset all cache components.

When you use multiple catalog servers, you can improve performance by taking the following steps:

Provide other integration servers that host container servers only, rather than having only integration servers that host both catalog and container servers.
Start and stop integration servers in sequence, rather than using the mqsistart or mqsistop commands to start or stop all integration servers at once. For example, start the integration servers that host catalog servers before you start the integration servers that host only container servers.

When you use a global cache that spans multiple integration nodes, ensure that all WebSphere eXtreme Scale servers that are clustered in one embedded grid use the same domain name. Only servers with the same domain name can participate in the same grid. WebSphere eXtreme Scale clients use the domain name to identify and distinguish between embedded grids. If you do not specify a domain name in the integration server or integration node-level policy file, the integration node creates a name that is based on the server names of the catalog servers.

By default, each server starts with a domain name that is derived by the integration node. In previous versions of IBM Integration Bus, the domain name for all servers in all embedded caches was an empty string. Servers in different domains cannot collaborate in the same grid. Therefore, for a cache that spans multiple integration nodes, migrate these integration nodes at the same time.

You can configure the global cache by using IBM Integration Bus commands or the IBM Integration API. For more information, see Configuring the embedded global cache.

You can disable all cache components in the integration node by setting the cache policy property to disabled. The cache policy is set to disabled by default.

Interaction with the global cache

You can use Mapping nodes or JavaCompute nodes to store and retrieve data in a map in the global cache. When you get a global map from an external grid, the getGlobalMap method makes a connection to the grid if one does not exist. For more information, see Accessing the global cache by using a Mapping node or Accessing the global cache by using a JavaCompute node.

When you get an MbGlobalMap object, you can also specify how long the data remains in the global cache before it is removed automatically. This time is known as the time to live and is counted from when that map entry is last updated. The value applies to all cache entries that are created by using that MbGlobalMap object in that instance of the message flow. Data that is already in the map that you specify, or that is created by another MbGlobalMap object, is not affected by the time to live value. You can create multiple MbGlobalMap objects in different flows, integration servers, or integration nodes, all resolving to the same map in the global cache, but with different time to live values.

By default, the time to live is set to zero so that the data is never removed. To set a specific time to live, create a session policy, which you can reference from the MbGlobalMap object. For detailed instructions, see Specifying how long data remains in the global cache by using the JavaCompute node.