| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <document> |
| <properties> |
| <title>Lateral TCP Auxiliary Cache</title> |
| <author email="pete@kazmier.com">Pete Kazmier</author> |
| <author email="ASmuts@therealm.com">Aaron Smuts</author> |
| </properties> |
| |
| <body> |
| <section name="Lateral TCP Auxiliary Cache"> |
| <p> |
| The TCP Lateral Auxiliary Cache is an optional plug in for the |
| JCS. It is primarily intended to broadcast puts and removals to |
| other local caches, though it can also get cached objects. It |
| functions by opening up a <code>SocketServer</code> that |
| listens to a configurable port and by creating |
| <code>Socket</code> connections with other local cache |
| <code>SocketServers</code>. It can be configured to connect to |
| any number of servers. |
| </p> |
| <p> |
| If there is an error connecting to another server or if an error |
| occurs in transmission, it will move into a recovery mode. In |
| recovery mode the TCP Lateral Auxiliary Cache will continue to |
| communicate with healthy servers while it tries to restore the |
| connection with the server that is in error. |
| </p> |
| <p> |
| The cache hub communicates with a facade that implements a |
| zombie pattern (balking facade) to prevent blocking. Puts and |
| removals are queued and occur synchronously in the background. |
| Get requests are synchronous and can potentially block for a |
| configurable interval if there is a communication problem. |
| </p> |
| <subsection name="Non-UDP Discovery Configuration"> |
| <p> |
| The configuration is fairly straightforward and is done in the |
| auxiliary cache section of the <code>cache.ccf</code> |
| configuration file. In the example below, I created a TCP |
| Lateral Auxiliary Cache referenced by <code>LTCP</code>. It |
| connects to two servers defined in a comma separated list in |
| the <code>TcpServers</code> attribute. It listens to port |
| <code>1110</code> and does <code>AllowGet</code>. |
| Setting <code>AllowGet</code> |
| equal to <code>false</code> would cause the auxiliary cache to |
| return <code>null</code> from any get request. In most cases this |
| attribute should be set to <code>false</code>, since if the |
| lateral caches were properly configured, the elements in one |
| would be present in all. |
| </p> |
| <source><![CDATA[ |
| jcs.auxiliary.LTCP=org.apache.commons.jcs.auxiliary.lateral.socket.tcp.LateralTCPCacheFactory |
| jcs.auxiliary.LTCP.attributes=org.apache.commons.jcs.auxiliary.lateral.socket.tcp.TCPLateralCacheAttributes |
| jcs.auxiliary.LTCP.attributes.TcpServers=localhost:1111,localhost:1112 |
| jcs.auxiliary.LTCP.attributes.TcpListenerPort=1110 |
| jcs.auxiliary.LTCP.attributes.AllowGet=true |
| ]]></source> |
| <p> |
| A mostly configurationless mode is available for the TCP |
| lateral cache if you use the <a href="LateralUDPDiscovery.html">UDP Discovery</a> |
| mechanism. |
| </p> |
| </subsection> |
| <subsection name="Send Only Configuration"> |
| <p> |
| You can configure the TCP lateral cache to operate |
| in send only mode by setting the <code>Receive</code> attribute |
| to false. By default the receive attribute is true. |
| When it is set to false, the lateral cache will not |
| establish a socket server. |
| </p> |
| <p> |
| Setting receive to false allows you to broadcast puts |
| and removes, but not receive any. This is useful for |
| nodes of an application that produce data, but are not |
| involved in data retrieval. |
| </p> |
| <p> |
| The configuration below is the same as above, except the |
| <code>Receive</code> attribute is set to false. It also uses UDP |
| discovery to find the servers, rather than listing them in the |
| servers attribute. |
| </p> |
| <source><![CDATA[ |
| jcs.auxiliary.LTCP=org.apache.commons.jcs.auxiliary.lateral.socket.tcp.LateralTCPCacheFactory |
| jcs.auxiliary.LTCP.attributes=org.apache.commons.jcs.auxiliary.lateral.socket.tcp.TCPLateralCacheAttributes |
| #jcs.auxiliary.LTCP.attributes.TcpServers= |
| jcs.auxiliary.LTCP.attributes.TcpListenerPort=1118 |
| jcs.auxiliary.LTCP.attributes.UdpDiscoveryAddr=228.5.6.8 |
| jcs.auxiliary.LTCP.attributes.UdpDiscoveryPort=6780 |
| jcs.auxiliary.LTCP.attributes.UdpDiscoveryEnabled=true |
| jcs.auxiliary.LTCP.attributes.Receive=true |
| jcs.auxiliary.LTCP.attributes.AllowGet=false |
| jcs.auxiliary.LTCP.attributes.IssueRemoveOnPut=false |
| jcs.auxiliary.LTCP.attributes.FilterRemoveByHashCode=false |
| ]]></source> |
| </subsection> |
| |
| <subsection name="Potential Issues"> |
| <p> |
| The TCP Lateral Auxiliary Cache can provide a high level of |
| consistency but it does not guarantee consistency between |
| caches. A put for the same object could be issued in two |
| different local caches. Since the transmission is queued, a |
| situation could occur where the item put last in one cache is |
| overridden by a put request from another local cache. The two |
| local caches could potentially have different versions of the |
| same item. Like most caches, this is intended for high get |
| and low put utilization, and this occurrence would hint at |
| improper usage. The RMI Remote cache makes this situation a |
| bit less likely to occur, since the default behavior is to |
| remove local copies on put operations. If either local cache |
| needed the item put in the above situation, it would have to |
| go remote to retrieve it. Both local copies would have been |
| expired and would end up using the same version, though it is |
| possible that the version stored remotely would not be the |
| last version created. The OCS4J tries to implement a locking |
| system to prevent this from occurring, but the locking system |
| itself could suffer from similar problems (when granting locks |
| from two roughly simultaneous lock requests) and it would |
| create a significant burden on all the caches involved. Since |
| this situation would be extremely rare and is nearly |
| impossible to solve practically, for now JCS will not offer |
| any type of locking. |
| </p> |
| </subsection> |
| <subsection name="Recent"> |
| <p> |
| I added a <code>IssueRemoveOnPut</code> attribute that |
| causes the lateral cache to remove an element from the |
| cache rather than inserting it when a put. This allows the local caches to |
| dictate their own memory usage pattern. |
| </p> |
| </subsection> |
| </section> |
| </body> |
| </document> |
