This cache loader allows to delegate loads and stores to another instance of JBossCache, which could reside (a)in the same address space, (b) in a different process on the same host, or (c) in a different process on a different host. Option (a) is mostly used for unit testing, and the envisaged use is (b) and (c).

A TcpDelegatingCacheLoader talks to a remote TcpCacheServer, which can be a standalone process, or embedded as an MBean inside JBoss. The TcpCacheServer has a reference to another JBossCache, which it can create itself, or which is given to it (e.g. by JBoss, using dependency injection).

The TcpDelegatingCacheLoader is configured with the host and port of the remote TcpCacheServer, and uses this to communicate to it.

An example set of a TcpCacheServer running inside of JBoss is shown below:

<server>

   <classpath codebase="./lib" archives="jboss-cache.jar"/>

   <mbean code="org.jboss.cache.loader.tcp.TcpCacheServer" 
       name="jboss.cache:service=TcpCacheServer">
      <depends optional-attribute-name="Cache"
               proxy-type="attribute">jboss.cache:service=TreeCache</depends>
      <attribute name="BindAddress">${jboss.bind.address:localhost}</attribute>
      <attribute name="Port">7500</attribute>
      <attribute name="MBeanServerName"></attribute>
      <!--<attribute name="CacheName">jboss.cache:service=TreeCache</attribute>-->
   </mbean>

</server>         

The BindAddress and Port define where its server socket is listening on, and an existing JBossCache MBean is injected into it (assigned to 'Cache'). This means that all requests from the TcpDelegatingCacheLoader will be received by this instance and forwarded to the JBossCache MBean.

Note that there is also a 'Config' attribute which points to a config XML file for JBossCache. If it is set, then the TcpCacheServer will create its own instance of JBossCache and configure it according to the Config attribute.

The client side looks as follow:

<attribute name="CacheLoaderConfiguration">
   <config>
       <cacheloader>
           <class>org.jboss.cache.loader.tcp.TcpDelegatingCacheLoader</class>
               <properties>
                   host=localhost
                   port=7500
               </properties>
       </cacheloader>
   </config>
</attribute>

This means this instance of JBossCache will delegate all load and store requests to the remote TcpCacheServer running at localhost:7500.

A typical use case could be multiple replicated instance of JBossCache in the same cluster, all delegating to the same TcpCacheServer instance. The TcpCacheServer might itself delegate to a database via JDBCCacheLoader, but the point here is that - if we have 5 nodes all accessing the same dataset - they will load the data from the TcpCacheServer, which has do execute one SQL statement per unloaded data set. If the nodes went directly to the database, then we'd have the same SQL executed multiple times. So TcpCacheServer serves as a natural cache in front of the DB (assuming that a network round trip is faster than a DB access (which usually also include a network round trip)).

To alleviate single point of failure, we could combine this with a ChainingCacheLoader, where the first CacheLoader is a ClusteredCacheLoader, the second a TcpDelegatingCacheLoader, and the last a JDBCacheLoader, effectively defining our cost of access to a cache in increasing order of cost.