<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
      "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
  <title>WSO2 ESB - Cache Mediator </title>
  <link href="css/esb-docs.css" rel="stylesheet" />
  <link href="styles/dist-docs.css" rel="stylesheet" type="text/css"
  media="all" />
</head>

<body>
<h2>Cache Mediator</h2>

<p>When a message comes to the Cache mediator, it checks weather an equivalent message is
seen before. If the message is seen before it will execute a specified
sequence. It uses message hashes for checking the equivalence of messages. Once the Cache 
meditor finds that the message is a cached message, it will fetch
the cached response and prepare ESB for sending the response. If a
sequence is specified for a cache hit, user can send back the response message
within this sequence using a send mediator. If a sequence is not specified
cached response is sent back to the requestor. </p>

<h3>Syntax</h3>
<pre xml:space="preserve"> &lt;cache [id="string"] [hashGenerator="class"] [timeout="seconds"] [scope=(per-host | per-mediator)]
     collector=(true | false) [maxMessageSize="in-bytes"]&gt;
   &lt;onCacheHit [sequence="key"]&gt;
     (mediator)+
   &lt;/onCacheHit&gt;?
   &lt;implementation type=(memory | disk) maxSize="int"/&gt;
 &lt;/cache&gt;</pre>

<p>The cache mediator will evaluate the hash value of an incoming message as
described in the optional hash generator implementation (which should be a
class implementing the org.wso2.caching.digest.DigestGenerator interface). The
default hash generator is 'org.wso2.caching.digest.DOMHashGenerator'. If the
generated hash value has been found in the cache then the cache mediator will
execute the onCacheHit sequence which can be specified inline or referenced.
The cache mediator must be specified with an 'id' and two instances with this
same 'id' that correlates the response message into the cache for the request
message hash. The optional 'timeout' specifies the valid duration for cached
elements, and the scope defines if mediator instances share a common cache per
every host instance, or per every cache mediator pair (i.e. 'id') instance. The
'collector' attribute 'true' specifies that the mediator instance is a response
collection instance, and 'false' specifies that its a cache serving instance.
The maximum size of a message to be cached could be specified with the optional
'maxMessageSize' attributes in bytes and defaults to unlimited. Finally the
'implementation' element may define if the cache is disk or memory based, and
the 'maxSize' attribute defines the maximum number of elements to be cached.
</p>

<p></p>

<h3>UI Configuration</h3>
<img src="../cache-mediator/docs/images/cache_mediator_screenshot.jpg" alt=""
/> 
<ul>
  <li>Cache Id: Id for the cache configuration. You should have same id for a
    cache mediator instance in incoming path and the corresponding mediator
    instance in outgoing message path. </li>
  <li>Cache Scope: Scope of the cache. This is important if the service is
    deployed in a cluster. 
    <ul>
      <li>Per-Host: The cache is kept only for the current host in a cluster.
      </li>
      <li>Per-Mediator: The cache is kept once for the whole cluster. </li>
    </ul>
  </li>
  <li>Cache Type: Whether the mediator is in the incoming path (check request)
    or the outgoing path (cache the response). 
    <ul>
      <li>Finder: Set if the message is incoming path. This indicate the
        mediator find for the request hash of each incoming message. </li>
      <li>Collector: Set if the message is in outgoing path. This indicate the
        mediator collect the response message in the cache. </li>
    </ul>
  </li>
  <li>Hash Generator: The logic for finding the hash which check against each
    incoming message. Default to org.wso2.caching.digest.DOMHASHGenerator </li>
  <li>Cache Timeout: The cache timeout(The time to keep the cache before
    expiring) in seconds. </li>
  <li>Maximum Message Size: The limit of the message to cache in bytes. </li>
  <li>Implementation Type: Currently only "In-Memory" is available. </li>
  <li>On Cache Hit: Specify the sequence to follow when the cache mediator is
    hit. You can either specify it as anonymous where you can define child
    mediators for the Cache mediator or you can refer a named sequence of
    mediators from the registry. </li>
</ul>

<h3>Example</h3>
<pre xml:space="preserve">&lt;definitions xmlns="http://ws.apache.org/ns/synapse"&gt;
  &lt;in&gt;
    &lt;cache timeout="20" scope="per-host" collector="false"
      hashGenerator="org.wso2.caching.digest.DOMHASHGenerator"&gt;
      &lt;implementation type="memory" maxSize="100"/&gt;
    &lt;/cache&gt;

    &lt;send&gt;
      &lt;endpoint&gt;
        &lt;address uri="http://localhost:9000/services/SimpleStockQuoteService"/&gt;
      &lt;/endpoint&gt;
    &lt;/send&gt;
  &lt;/in&gt;
  
  &lt;out&gt;
    &lt;cache collector="true"/&gt;
    &lt;send/&gt;
  &lt;/out&gt;
&lt;/definitions&gt;</pre>

<p>In this example, first message will be sent to the endpoint specified as
cache is not hit. The responce will come to the cache mediator inside the out
meduator and this will cache the response. The second equal message will match
the cache and response will be directly fetch from the cache and sent to the
requestor. This happens because no onCacheHit sequence is defined. </p>
</body>
</html>
