# Global Caches

## Contents
Overview Local Caches Distributed Caches Cache Settings Example of Caching Response Messages

## Overview
In cases where a Web Service is serving the same request (and generating the same response) over and over again, it makes sense to use a caching mechanism. When a cache is employed, a unique identifier for the request is cached together with the corresponding response for this request. If an identical request is received, the response can be retrieved from the cache instead of forcing the Web Service to reprocess the identical request and generate the same response. The use of caching in this way helps divert unnecessary traffic from the Web Service and makes it more responsive to new requests. For example, assume you have deployed a Web Service that returns a list of cities in the USA from an external database, which is then used by a variety of Web-based applications. Because the names and quantity of cities in the USA are relatively constant, if the Web Service is handling hundreds or thousands of requests every day, this represents a serious waste of processing time and effort, especially considering that the database that contains the relatively fixed list of city names is hosted on a separate machine to the service. If you assume that the list of cities in the database does not change very often, it makes sense to use Oracle Enterprise Gateway to cache the response from the Web Service that contains the list of cities. Then when a request for this Web Service is identified by the Enterprise Gateway, the cached response can be returned to the client. This approach results in the following performance improvements: The Enterprise Gateway does not have to route the message on to the Web Service, therefore saving the processing effort required, and perhaps more importantly, saving the time it takes for the round trip. The Web Service does not have to waste processing power on generating the same list over and over again, therefore making it more responsive to requests for other services. Assuming a naive implementation of database retrieval and caching, the Web Service does not have to query the database (over the network) and collate the results over and over again for every request. The caching mechanism used in the Enterprise Gateway offers full control over the size of the cache, the lifetime of objects in the cache, whether objects are cached to disk or not, and even whether caches can be replicated across multiple instances of Enterprise Gateways. The following sections describe how to configure both local and distributed caches in the Enterprise Gateway, concluding with a detailed example of how to configure a circuit to cache responses.
## Local Caches
Local caches are used where a single Enterprise Gateway instance has been deployed. In such cases, you do not need to replicate caches across multiple running instances of the Enterprise Gateway. In the Policy Studio, you can add a local cache, by selecting the top-level Caches tree item on the External Connections tab, and clicking the Add button at the bottom right of the screen. Select Add Local Cache from the menu. You can configure the following fields on the Configure Local Cache dialog: Cache Name: Enter a name for the cache. Maximum Elements in Memory: Enter the maximum number of objects that can be in memory at any one time. Maximum Elements on Disk: Sets the maximum number of objects that can be stored in the disk store at any one time. A value of zero indicates an unlimited number of objects. Eternal: If this option is selected, objects stored in the caches never expire and timeouts have no effect. Overflow to Disk: Select this option if you want the cache to overflow to disk when the number of objects in memory has reached the amount set in the Maximum Elements in Memory field above. Note: The following fields are optional: Time to Idle: Determines the maximum amount of time (in seconds) between accesses that an object can remain idle before it expires. A value of zero indicates that objects can idle for infinity, which is the default value. Note that if the Eternal field is selected, this setting is ignored. Time to Live: Sets the maximum time between when an object is created and when it expires. The default value is zero, which means that the object can live for infinity. Note that if the Eternal field is selected, this setting is ignored. Persist to Disk: If selected, the disk store is persisted between JVM restarts. This option is disabled by default. Disk Expiry Interval: Configures the number of seconds between runs of the disk expiry thread. The default is 120 seconds. Disk Spool Buffer Size: Indicates the size of memory (in MBs) to allocate the disk store for a spool buffer. Writes are made to this memory and then asynchronously written to disk. The default size is 30 MB. If you get `OutOfMemory` exceptions, you may consider lowering this value. However, if you notice poor performance, you should increase the value. Eviction Policy: Select the eviction policy that the cache uses to evict objects from the cache. The default policy is Least Recently Used. However, you can also use First in First Out and Less Frequently Used.
## Distributed Caches
If you have deployed several Enterprise Gateways throughout your network, you need to employ a distributed cache. In this scenario, each Enterprise Gateway has its own local copy of the cache but registers a cache event listener that replicates messages to the other caches so that put, remove, expiry, and delete events on a single cache are duplicated across all other caches. You can configure a distributed cache by selecting the top-level Caches tree item on the External Connections tab, and clicking the Add button at the bottom right of the screen. Select Add Distributed Cache from the menu, and configure the following fields on the Configure Distributed Cache dialog: Note: Many of the settings for the distributed cache are identical to those for the local cache. For details on how to configure these fields, see the Local Caches section. The following information refers to fields that are not displayed on both dialogs. Event Listener Class Name: Enter the name of the listener factory class that enables this cache to register listeners for cache events, such as put, remove, delete, and expire. Properties Separator: Specify the character to use to separate the list of properties. Properties: Specify the properties to pass to the `RMICacheReplicatorFactory`. The following properties are available: `replicatePuts=true | false` Determines whether new elements placed in a cache are replicated to other caches. Default is `true`. `replicateUpdates=true | false` Determines whether new elements that override (update) existing elements with the same key in a cache are replicated. Default is `true`. `replicateRemovals=true` Determines whether element removals are replicated. Default is `true`. `replicateAsynchronously=true | false` Determines whether replications are asynchronous (true) or synchronous (false). Default is `false`. `replicateUpdatesViaCopy=true | false` Determines whether new elements are copied to other caches (true) or a remove message is sent (false). Default is `true`. `asynchronousReplicationIntervalMillis=[number of ms]` The asynchronous replicator runs at a set interval of milliseconds. The default is 1000 and the minimum is 10. This property is only applicable if `replicateAsynchronously=true`. Cache Bootstrap Class Name: Specifies a `BootstrapCacheLoader` factory that the cache can call on initialization to pre-populate itself. The `RMIBootstrapCacheLoader` bootstraps caches in clusters where `RMICacheReplicator`s are used. Properties Separator: The character entered here is used to separate the list of properties listed in the field below. Properties: The properties listed here are used to initialize the `RMIBootstrapCacheLoaderFactory`. The following properties are recognized: `bootstrapAsynchronously=true | false` Determines whether the bootstrap happens in the background after the cache has started (true), or if bootstrapping must complete before the cache is made available (false). Default is `true`. `maximumChunkSizeBytes=[integer]` Caches can potentially grow larger than the memory limits on the JVM. This property enables the bootstrapper to fetch elements in chunks. The default chunk size is 5000000 (5 MB).
## Cache Settings
In a distributed cache, there is no master cache controlling all caches in the group. Instead, each cache is a peer in the group and needs to know where all the other peers in the group are located. Peer Discovery and Peer Listeners are two essential parts of any distributed cache system. You can configure these by right-clicking the top-level Caches tree item on the External Connections tab, and selecting Edit Cache Settings. Configure the following fields on the Cache Settings dialog: Peer Provider Class: By default, the built-in peer discovery class factory is used: `net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory` Properties Separator: Specify the token used as the separator for the list of properties in the next field. Properties: The properties listed here specify whether the peer discovery mechanism is automatic or manual. If the automatic mechanism is used, each peer uses TCP multicast to establish and maintain a multicast group. This is the default option because it requires minimal configuration and peers can be automatically added and removed from the group. Each peer pings the group every second. If a peer has not pinged any of the other peers after 5 seconds, it is dropped from the group, while a new peer is admitted to the group if it starts pinging the other peers. To use automatic peer discovery, ensure that the `peerDiscovery` setting is set to `automatic`. You can specify the multicast address and port using the `multicastGroupAddress` and `multicastGroupPort` settings. You can specify the time to live for multicast datagrams using the `timeToLive` setting. Alternatively, you can configure a manual peer discovery mechanism, whereby each peer definitively lists the peers that it wants to communicate with. This should only be used in networks where there are problems propagating multicast datagrams. To use a manual peer discovery mechanism, make sure the `peerDiscovery` setting is set to `manual`. The list of RMI URLs of the other peers in the group must also be specified, for example: `rmiUrls=//server2:40001/sampleCache1|//server2:40001/sampleCache2` . Peer Listener Class: The peer listener class specified is responsible for listening for messages from peers in the group. Properties Separator: Specify the token used to separate the list of properties. Properties: The properties entered configure the way the listener behaves. Valid properties are as follows: hostname (optional) Hostname of the machine on which the listener is listening. Note that, by default, this is set to `localhost`, which maps to the local loopback address of `127.0.0.1`, which is not addressable from another machine on the network. If you intend this cache to be used over the network, you should change this address to the IP address of the network interface on which the listener is listening. port (mandatory) Specify the port on which the listener is listening, which by default is 4001. This setting is mandatory. socketTimeoutMillis (optional) Enter the number of seconds that client sockets wait when sending messages to this listener until they give up. The default is 2000 ms. Notify replicators of removal of items during refresh: A server refresh automatically purges all items from the cache (for example, when configuration updates are deployed to the Enterprise Gateway). If this checkbox is selected, the contents of each peer in the group are also purged. This avoids a situation where a single peer is refreshed (and has its contents purged), but the other peers in the group are not purged. If this option is not selected, the refreshed peer attempts to bootstrap itself to the other peers in the group, resulting in the cache items becoming replicated in the refreshed cache. This effectively negates the effect of the server refresh and may result in inconsistent behavior.
## Example of Caching Response Messages
This simple example shows how to construct a circuit that caches responses from the Web Service. It uses the request body to identify identical successive requests. In other words, if the Enterprise Gateway receives two successive requests with an identical message body, it returns the corresponding response from the cache instead of routing the request to the Web Service. The following diagram illustrates the complete circuit:
Caching Response Messages
The logic of the circuit is summarized as follows: The purpose of the first filter is to configure what part of the request you want to use to identify unique requests. This example uses the request body as the unique key, which is then used to look up the appropriate response message from the cache. The second filter looks up the request body in the response cache to see if it contains the request body. If it does, the response message that corresponds to this request is returned to the client. If it does not, the request is routed to the Web Service, which processes it (by connecting to a database over the network and running a SQL statement) and returns a response to the Enterprise Gateway. The Enterprise Gateway then returns the response to the client and caches it in the response cache. When the next identical request is received by the Enterprise Gateway, the corresponding response is located in the responses cache and returned immediately to the client. You must configure the following caching filters to achieve this circuit. For convenience, the routing filters will not be included because the configuration options depend on your target Web Service. Create Key Filter: This filter is used to decide what part of the request is used in order for a request to be considered unique. Different parts of the request can be identified internally using Oracle message attributes, for example, `content.body` contains the request body. The following fields must be configured for this filter: Name: Use request body to create unique key Attribute Name: content.body Is Cached?: This filter looks up the cache to see if a response has been stored for the current request. It looks up the cache using a message attribute, which is `message.key` by default. The `message.key` attribute contains a hash of the request message, and can be used as the key for objects in the cache. If the key is found in the cache, the value of the key (cached response for this request) is written to the `content.body` attribute, which can be returned to the client using the Reflect filter. You must configure the following fields: Name: Is a response for this request already cached? Cache containing key: Response Cache (assuming you have created a cache of this name) Attribute Containing Key: `message.key` Overwrite attribute name if found: `content.body` Reflect: If the Is Cached? filter passes, it retrieves the response from the cache and stores it in the `content.body` message attribute. The Reflect filter is used to return the cached response to the client. Routing: If a response for this request could not be located in the cache, the Enterprise Gateway routes the request to the Web Service, and waits for a response. For more details on how to route messages, see the Routing Configuration tutorial. Cache Attribute: When the response has been received from the Web Service, it should be cached for future use. The Cache Attribute filter is used to configure the key used to look up the cache and which aspect of the response message is stored as the key value in the cache. Note that this example specifies the value of the `content.body` attribute to cache. Because this filter is configured after the routing filters, this attribute contains the response message. Note also that the value entered in the Attribute Key field should match that entered in the Attribute containing key field in the Is Cached? filter. You must configure the following fields: Name: Cache response body Cache to use: Response Cache Attribute key: `message.key` Attribute name to store: `content.body` For more information on these filters, see the following topics:
Filter | Topic
Create Key | Create Key
Is Cached? | Is Cached?
Cache Attribute | Cache Attribute
Remove Cached Attribute | Remove Cached Attribute