Cache Mediator

When a message comes to the Cache mediator, it checks whether an equivalent message has been seen before based on message hashes. If such a message has existed before, the Cache mediator executes the onCacheHit sequence (if specified), fetches the cached response, and prepares the ESB to send the response. The onCacheHit sequence can send back the response message using a Send Mediator. If the onCacheHit sequence is not specified, the cached response is sent back to the requester.

The Cache mediator does not cache the response status code of the HTTP response in the cache table. Instead, it returns the "200 OK" status code on a cache hit, which is the default request success status response. If you want to return a different status code when the request gets a cache hit, you can update the response status code in the onCacheHit sequence.

The Cache mediator is a content-aware mediator.

Syntax

<cache [id="string"] [hashGenerator="class"] [timeout="seconds"] [scope=(per-host | per-mediator)]
     collector=(true | false) [maxMessageSize="in-bytes"]>
   <onCacheHit [sequence="key"]>
     (mediator)+
   </onCacheHit>?
   <implementation type=(memory | disk) maxSize="int"/>
</cache>

UI Configuration

Click on the relevant tab to view the UI configuration depending on whether the cache type of the cache mediator is Finder or Collector.

cache mediator properties

The parameters available to configure the Cache mediator are as follows.

Parameter Name	Description
Cache ID	The ID of the cache configuration.
Cache Scope	The scope of the cache. Possible values are as follows. Per-Host: The cache is kept only for the current host in a cluster. Per-Mediator: The cache is kept once for the whole cluster.
Cache Type	This parameter specifies whether the mediator should be in the incoming path (to check the request) or in the outgoing path (to cache the response). Possible values are as follows. Finder: If this is selected, the mediator is used to search for the request hash of incoming messages. Collector: If this is selected, the mediator is used to collect response messages in the cache.
Hash Generator	This parameter is used to define the logic used by the mediator to evaluate the has values of incoming messages. The value should be a class implementing the `org.wso2.carbon.mediator.cache.digest.DigestGenerator` class interface. The default hash generator is `org.wso2.carbon.mediator.cache.digest.DOMHASHGenerator`. If the generated hash value is found in the cache, then the cache mediator will execute the onCacheHit sequence which can be specified inline or referenced. `org.wso2.carbon.mediator.cache.digest.DOMHASHGenerator` uses only the message body to generate the hash value. However,`org.wso2.carbon.mediator.cache.digest.REQUESTHASHGenerator` considers the recipient (To) address of the request, HTTP headers and XML Payload in generating the hash value. Therefore, this uniquely identifies the HTTP request with the same recipient (To) address, headers and payload.
Cache Timeout (seconds)	The time duration for which the cache is kept. The cache expires once this time duration elapses.
Maximum Message Size	The maximum size of the messages to be cached. This is specified in bytes.
Implementation Type	This parameter is used to specify whether the cache is memory-based or disk-based. Currently, In-Memory is the only value available to be selected.
Maximum Size	The maximum number of elements to be cached. The default size is 1000.
Anonymous	If this option is selected, an anonymous sequence is executed when an incoming message is identified as an equivalent to a previously received message based on the value defined for the Hash Generator field.
Sequence Reference	The reference to the `onCacheHit` sequence to be executed when an incoming message is identified as an equivalent to a previously received message based on the value defined for the Hash Generator field. This sequence should be specified in the Registry in order to be selected for this field. You can click either Configuration Registry or Governance Registry as relevant to select the sequence from the resource tree.

The parameters available to configure the Cache mediator are as follows.

Parameter Name

Description

Cache ID

The ID of the cache configuration.

Cache Scope

The scope of the cache. Possible values are as follows.

Per-Host: The cache is kept only for the current host in a cluster.
Per-Mediator: The cache is kept once for the whole cluster.

Cache Type

This parameter specifies whether the mediator should be in the incoming path (to check the request) or in the outgoing path (to cache the response). Possible values are as follows.

Finder: If this is selected, the mediator is used to search for the request hash of incoming messages.
Collector: If this is selected, the mediator is used to collect response messages in the cache.

Note

You can configure the mediator using XML. Click switch to source view in the Mediator window.

Examples

In this example, the first message sent to the endpoint, and the cache is not hit. The Cache mediator configured in the Out sequence caches the response to this message. When a similar message is sent to the second time, the previous response will be directly fetched from the cache and sent to the requester. This happens because no onCacheHit sequence is defined.

<sequence name="SEQ_CACHE">
  <in>
    <cache scope="per-host"
      collector="false"
      hashGenerator="org.wso2.carbon.mediator.cache.digest.DOMHASHGenerator"
      timeout="20">
      <implementation type="memory" maxSize="100"/>
    </cache>

    <send>
      <endpoint>
        <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
      </endpoint>
    </send>
  </in>

  <out>
    <cache scope="per-host" collector="true"/>
    <send/>
  </out>
</sequence>

According to this example configuration, if you define a cache collector using the cache mediator in the in sequence, you need to add the RESPONSE property to consider the message as a response message.

<api xmlns="http://ws.apache.org/ns/synapse" name="cacheAPI" context="/cache">
   <resource methods="POST GET" uri-template="/headerapi/*">
      <inSequence>
         <cache id="cache-sample" scope="per-host" collector="false" hashGenerator="org.wso2.carbon.mediator.cache.digest.DOMHASHGenerator" timeout="5000">
            <implementation type="memory" maxSize="1000"/>
         </cache>
         <call>
            <endpoint>
               <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
            </endpoint>
         </call>
         <property name="RESPONSE" value="true" scope="default" type="STRING"/>
         <enrich>
            <source type="inline" clone="true">
               <ax21:newvalue xmlns:ax21="http://services.samples/xsd">testsamplevalue                </ax21:newvalue>
            </source>
            <target xmlns:ax21="http://services.samples/xsd" xmlns:ns="http://services.samples" action="sibling" xpath="//ns:getQuoteResponse/ns:return/ax21:volume"/>
         </enrich>
         <cache scope="per-host" collector="true"/>
         <respond/>
      </inSequence>
   </resource>
</api>

Samples

Sample 420: Simple Cache Implemented on ESB for the Actual Service.

Invalidating Cached Responses Remotely

You can invalidate all cached response remotely by using any JMX monitoring tool such as Jconsole using the exposed MBeans. You can use the Invalidatemediatocache()operation of the org.wso2.carbon.mediation MBean for this as shown below.

JMX monitoring through JConsole