xdocs/RemoteAuxCache.xml - commons-jcs - Git at Google

 <?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>Remote Auxiliary Cache Client / Server</title>
 		<author email="pete@kazmier.com">Pete Kazmier</author>
 		<author email="ASmuts@apache.org">Aaron Smuts</author>
 	</properties>

 	<body>
 		<section name="Remote Auxiliary Cache Client / Server">
 			<p>
 				The Remote Auxiliary Cache is an optional plug in for
 				JCS. It is intended for use in multi-tiered systems to
 				maintain cache consistency. It uses a highly reliable
 				RMI client server framework that currently allows for
 				any number of clients. Using a listener id allows
 				multiple clients running on the same machine to connect
 				to the remote cache server. All cache regions on one
 				client share a listener per auxiliary, but register
 				separately. This minimizes the number of connections
 				necessary and still avoids unnecessary updates for
 				regions that are not configured to use the remote cache.
 			</p>
 			<p>
 				Local remote cache clients connect to the remote cache
 				on a configurable port and register a listener to
 				receive cache update callbacks at a configurable port.
 			</p>
 			<p>
 				If there is an error connecting to the remote server or
 				if an error occurs in transmission, the client will
 				retry for a configurable number of tries before moving
 				into a failover-recovery mode. If failover servers are
 				configured the remote cache clients will try to register
 				with other failover servers in a sequential order. If a
 				connection is made, the client will broadcast all
 				relevant cache updates to the failover server while
 				trying periodically to reconnect with the primary
 				server. If there are no failovers configured the client
 				will move into a zombie mode while it tries to
 				re-establish the connection. By default, the cache
 				clients run in an optimistic mode and the failure of the
 				communication channel is detected by an attempted update
 				to the server. A pessimistic mode is configurable so
 				that the clients will engage in active status checks.
 			</p>
 			<p>
 				The remote cache server broadcasts updates to listeners
 				other than the originating source. If the remote cache
 				fails to propagate an update to a client, it will retry
 				for a configurable number of tries before de-registering
 				the client.
 			</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 asynchronously in
 				the background. Get requests are synchronous and can
 				potentially block if there is a communication problem.
 			</p>
 			<p>
 				By default client updates are light weight. The client
 				listeners are configured to remove elements form the
 				local cache when there is a put order from the remote.
 				This allows the client memory store to control the
 				memory size algorithm from local usage, rather than
 				having the usage patterns dictated by the usage patterns
 				in the system at large.
 			</p>
 			<p>
 				When using a remote cache the local cache hub will
 				propagate elements in regions configured for the remote
 				cache if the element attributes specify that the item to
 				be cached can be sent remotely. By default there are no
 				remote restrictions on elements and the region will
 				dictate the behavior. The order of auxiliary requests is
 				dictated by the order in the configuration file. The
 				examples are configured to look in memory, then disk,
 				then remote caches. Most elements will only be retrieved
 				from the remote cache once, when they are not in memory
 				or disk and are first requested, or after they have been
 				invalidated.
 			</p>
 			<subsection name="Client 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 Remote Auxiliary Cache Client referenced by
 					<code>RFailover</code>
 					.
 				</p>
 				<p>
 					This auxiliary cache will use
 					<code>localhost:1102</code>
 					as its primary remote cache server and will attempt
 					to failover to
 					<code>localhost:1103</code>
 					if the primary is down.
 				</p>
 				<p>
 					Setting
 					<code>RemoveUponRemotePut</code>
 					to
 					<code>false</code>
 					would cause remote puts to be translated into put
 					requests to the client region. By default it is
 					<code>true</code>
 					, causing remote put requests to be issued as
 					removes at the client level. For groups the put
 					request functions slightly differently: the item
 					will be removed, since it is no longer valid in its
 					current form, but the list of group elements will be
 					updated. This way the client can maintain the
 					complete list of group elements without the burden
 					of storing all of the referenced elements. Session
 					distribution works in this half-lazy replication
 					mode.
 				</p>
 				<p>
 					Setting
 					<code>GetOnly</code>
 					to
 					<code>true</code>
 					would cause the remote cache client to stop
 					propagating updates to the remote server, while
 					continuing to get items from the remote store.
 				</p>
 				<source>
 					<![CDATA[
 # Remote RMI Cache set up to failover
 jcs.auxiliary.RFailover=
     org.apache.commons.jcs3.auxiliary.remote.RemoteCacheFactory
 jcs.auxiliary.RFailover.attributes=
     org.apache.commons.jcs3.auxiliary.remote.RemoteCacheAttributes
 jcs.auxiliary.RFailover.attributes.FailoverServers=
     localhost:1102,localhost:1103
 jcs.auxiliary.RFailover.attributes.RemoveUponRemotePut=true
 jcs.auxiliary.RFailover.attributes.GetOnly=false
         ]]>
 				</source>
 				<p>
 					This cache region is setup to use a disk cache and
 					the remote cache configured above:
 				</p>
 				<source>
 					<![CDATA[
 #Regions preconfigured for caching
 jcs.region.testCache1=DC,RFailover
 jcs.region.testCache1.cacheattributes=
     org.apache.commons.jcs3.engine.CompositeCacheAttributes
 jcs.region.testCache1.cacheattributes.MaxObjects=1000
 jcs.region.testCache1.cacheattributes.MemoryCacheName=
     org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache
         ]]>
 				</source>
 			</subsection>
 			<subsection name="Server Configuration">
 				<p>
 					The remote cache configuration is growing. For now,
 					the configuration is done at the top of the
 					<code>remote.cache.ccf</code>
 					file. The
 					<code>startRemoteCache</code>
 					script passes the configuration file name to the
 					server when it starts up. The configuration
 					parameters below will create a remote cache server
 					that listens to port
 					<code>1102</code>
 					and performs call backs on the
 					<code>jcs.remotecache.serverattributes.servicePort</code>
 					, also specified as port
 					<code>1102</code>
 					.
 				</p>
 				<source>
 					<![CDATA[
 # Registry used to register and provide the
 # IRemoteCacheService service.
 registry.host=localhost
 registry.port=1102
 # call back port to local caches.
 jcs.remotecache.serverattributes.servicePort=1102
 # rmi socket factory timeout
 jcs.remotecache.serverattributes.rmiSocketFactoryTimeoutMillis=5000
 # cluster setting
 jcs.remotecache.serverattributes.LocalClusterConsistency=true
 jcs.remotecache.serverattributes.AllowClusterGet=true
         ]]>
 				</source>
 				<p>
 					Remote servers can be chained (or clustered). This
 					allows gets from local caches to be distributed
 					between multiple remote servers. Since gets are the
 					most common operation for caches, remote server
 					chaining can help scale a caching solution.
 				</p>
 				<p>
 					The
 					<code>LocalClusterConsistency</code>
 					setting tells the remote cache server if it should
 					broadcast updates received from other cluster
 					servers to registered local caches.
 				</p>
 				<p>
 					The
 					<code>AllowClusterGet</code>
 					setting tells the remote cache server whether it
 					should allow the cache to look in non-local
 					auxiliaries for items if they are not present.
 					Basically, if the get request is not from a cluster
 					server, the cache will treat it as if it originated
 					locally. If the get request originated from a
 					cluster client, then the get will be restricted to
 					local (i.e. memory and disk) auxiliaries. Hence,
 					cluster gets can only go one server deep. They
 					cannot be chained.  By default this setting is true.
 				</p>
 				<p>
 					To use remote server clustering, the remote cache
 					will have to be told what regions to cluster. The
 					configuration below will cluster all
 					non-preconfigured regions with
 					<code>RCluster1</code>
 					.
 				</p>
 				<source>
 					<![CDATA[
 # sets the default aux value for any non configured caches
 jcs.default=DC,RCluster1
 jcs.default.cacheattributes=
     org.apache.commons.jcs3.engine.CompositeCacheAttributes
 jcs.default.cacheattributes.MaxObjects=1000

 jcs.auxiliary.RCluster1=
     org.apache.commons.jcs3.auxiliary.remote.RemoteCacheFactory
 jcs.auxiliary.RCluster1.attributes=
     org.apache.commons.jcs3.auxiliary.remote.RemoteCacheAttributes
 jcs.auxiliary.RCluster1.attributes.RemoteTypeName=CLUSTER
 jcs.auxiliary.RCluster1.attributes.RemoveUponRemotePut=false
 jcs.auxiliary.RCluster1.attributes.ClusterServers=localhost:1103
 jcs.auxiliary.RCluster1.attributes.GetOnly=false
         ]]>
 				</source>
 				<p>
 					RCluster1 is configured to talk to a remote server
 					at
 					<code>localhost:1103</code>
 					. Additional servers can be added in a comma
 					separated list.
 				</p>
 				<p>
 					If we startup another remote server listening to
 					port 1103, (ServerB) then we can have that server
 					talk to the server we have been configuring,
 					listening at 1102 (ServerA). This would allow us to
 					set some local caches to talk to ServerA and some to
 					talk to ServerB. The two remote servers will
 					broadcast all puts and removes between themselves,
 					and the get requests from local caches could be
 					divided. The local caches do not need to know
 					anything about the server chaining configuration,
 					unless you want to use a standby, or failover
 					server.
 				</p>
 				<p>
 					We could also use ServerB as a hot standby. This can
 					be done in two ways. You could have all local caches
 					point to ServerA as a primary and ServerB as a
 					secondary. Alternatively, you can set ServerA as the
 					primary for some local caches and ServerB for the
 					primary for some others.
 				</p>
 				<p>
 					The local cache configuration below uses ServerA as
 					a primary and ServerB as a backup. More than one
 					backup can be defined, but only one will be used at
 					a time. If the cache is connected to any server
 					except the primary, it will try to restore the
 					primary connection indefinitely, at 20 second
 					intervals.
 				</p>
 				<source>
 					<![CDATA[
 	# Remote RMI Cache set up to failover
 	jcs.auxiliary.RFailover=
 	    org.apache.commons.jcs3.auxiliary.remote.RemoteCacheFactory
 	jcs.auxiliary.RFailover.attributes=
 	    org.apache.commons.jcs3.auxiliary.remote.RemoteCacheAttributes
 	jcs.auxiliary.RFailover.attributes.FailoverServers=
 	    localhost:1102,localhost:1103
 	jcs.auxiliary.RC.attributes.RemoveUponRemotePut=true
 	jcs.auxiliary.RFailover.attributes.GetOnly=false
 	        ]]>
 				</source>
 			</subsection>
 			<subsection name="Server Startup / Shutdown">
 				<p>
 					It is highly recommended that you embed the Remote
 					Cache Server in a Servlet container such as Tomcat.
 					Running inside Tomcat allows you to use the
 					JCSAdmin.jsp page. It also takes care of the
 					complexity of creating working startup and shutdown
 					scripts.
 				</p>
 				<p>
 					JCS provides a convenient startup servlet for this
 					purpose. It will start the registry and bind the
 					JCS server to the registry. To use the startup
 					servlet, add the following to the web.xml file and
 					make sure you have the cache.ccf file in the
 					WEB-INF/classes directly of your war file.
 				</p>
 				<source>
 					<![CDATA[
     <servlet>
         <servlet-name>JCSRemoteCacheStartupServlet</servlet-name>
         <servlet-class>
              org.apache.commons.jcs3.auxiliary.remote.server.RemoteCacheStartupServlet
         </servlet-class>
         <load-on-startup>1</load-on-startup>
     </servlet>


     <servlet-mapping>
         <servlet-name>JCSRemoteCacheStartupServlet</servlet-name>
         <url-pattern>/jcs</url-pattern>
     </servlet-mapping>
 ]]>
 				</source>

 			</subsection>
 		</section>

 	</body>
 </document>
	<?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>Remote Auxiliary Cache Client / Server</title>
	<author email="pete@kazmier.com">Pete Kazmier</author>
	<author email="ASmuts@apache.org">Aaron Smuts</author>
	</properties>

	<body>
	<section name="Remote Auxiliary Cache Client / Server">
	<p>
	The Remote Auxiliary Cache is an optional plug in for
	JCS. It is intended for use in multi-tiered systems to
	maintain cache consistency. It uses a highly reliable
	RMI client server framework that currently allows for
	any number of clients. Using a listener id allows
	multiple clients running on the same machine to connect
	to the remote cache server. All cache regions on one
	client share a listener per auxiliary, but register
	separately. This minimizes the number of connections
	necessary and still avoids unnecessary updates for
	regions that are not configured to use the remote cache.
	</p>
	<p>
	Local remote cache clients connect to the remote cache
	on a configurable port and register a listener to
	receive cache update callbacks at a configurable port.
	</p>
	<p>
	If there is an error connecting to the remote server or
	if an error occurs in transmission, the client will
	retry for a configurable number of tries before moving
	into a failover-recovery mode. If failover servers are
	configured the remote cache clients will try to register
	with other failover servers in a sequential order. If a
	connection is made, the client will broadcast all
	relevant cache updates to the failover server while
	trying periodically to reconnect with the primary
	server. If there are no failovers configured the client
	will move into a zombie mode while it tries to
	re-establish the connection. By default, the cache
	clients run in an optimistic mode and the failure of the
	communication channel is detected by an attempted update
	to the server. A pessimistic mode is configurable so
	that the clients will engage in active status checks.
	</p>
	<p>
	The remote cache server broadcasts updates to listeners
	other than the originating source. If the remote cache
	fails to propagate an update to a client, it will retry
	for a configurable number of tries before de-registering
	the client.
	</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 asynchronously in
	the background. Get requests are synchronous and can
	potentially block if there is a communication problem.
	</p>
	<p>
	By default client updates are light weight. The client
	listeners are configured to remove elements form the
	local cache when there is a put order from the remote.
	This allows the client memory store to control the
	memory size algorithm from local usage, rather than
	having the usage patterns dictated by the usage patterns
	in the system at large.
	</p>
	<p>
	When using a remote cache the local cache hub will
	propagate elements in regions configured for the remote
	cache if the element attributes specify that the item to
	be cached can be sent remotely. By default there are no
	remote restrictions on elements and the region will
	dictate the behavior. The order of auxiliary requests is
	dictated by the order in the configuration file. The
	examples are configured to look in memory, then disk,
	then remote caches. Most elements will only be retrieved
	from the remote cache once, when they are not in memory
	or disk and are first requested, or after they have been
	invalidated.
	</p>
	<subsection name="Client 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 Remote Auxiliary Cache Client referenced by
	<code>RFailover</code>
	.
	</p>
	<p>
	This auxiliary cache will use
	<code>localhost:1102</code>
	as its primary remote cache server and will attempt
	to failover to
	<code>localhost:1103</code>
	if the primary is down.
	</p>
	<p>
	Setting
	<code>RemoveUponRemotePut</code>
	to
	<code>false</code>
	would cause remote puts to be translated into put
	requests to the client region. By default it is
	<code>true</code>
	, causing remote put requests to be issued as
	removes at the client level. For groups the put
	request functions slightly differently: the item
	will be removed, since it is no longer valid in its
	current form, but the list of group elements will be
	updated. This way the client can maintain the
	complete list of group elements without the burden
	of storing all of the referenced elements. Session
	distribution works in this half-lazy replication
	mode.
	</p>
	<p>
	Setting
	<code>GetOnly</code>
	to
	<code>true</code>
	would cause the remote cache client to stop
	propagating updates to the remote server, while
	continuing to get items from the remote store.
	</p>
	<source>
	<![CDATA[
	# Remote RMI Cache set up to failover
	jcs.auxiliary.RFailover=
	org.apache.commons.jcs3.auxiliary.remote.RemoteCacheFactory
	jcs.auxiliary.RFailover.attributes=
	org.apache.commons.jcs3.auxiliary.remote.RemoteCacheAttributes
	jcs.auxiliary.RFailover.attributes.FailoverServers=
	localhost:1102,localhost:1103
	jcs.auxiliary.RFailover.attributes.RemoveUponRemotePut=true
	jcs.auxiliary.RFailover.attributes.GetOnly=false
	]]>
	</source>
	<p>
	This cache region is setup to use a disk cache and
	the remote cache configured above:
	</p>
	<source>
	<![CDATA[
	#Regions preconfigured for caching
	jcs.region.testCache1=DC,RFailover
	jcs.region.testCache1.cacheattributes=
	org.apache.commons.jcs3.engine.CompositeCacheAttributes
	jcs.region.testCache1.cacheattributes.MaxObjects=1000
	jcs.region.testCache1.cacheattributes.MemoryCacheName=
	org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache
	]]>
	</source>
	</subsection>
	<subsection name="Server Configuration">
	<p>
	The remote cache configuration is growing. For now,
	the configuration is done at the top of the
	<code>remote.cache.ccf</code>
	file. The
	<code>startRemoteCache</code>
	script passes the configuration file name to the
	server when it starts up. The configuration
	parameters below will create a remote cache server
	that listens to port
	<code>1102</code>
	and performs call backs on the
	<code>jcs.remotecache.serverattributes.servicePort</code>
	, also specified as port
	<code>1102</code>
	.
	</p>
	<source>
	<![CDATA[
	# Registry used to register and provide the
	# IRemoteCacheService service.
	registry.host=localhost
	registry.port=1102
	# call back port to local caches.
	jcs.remotecache.serverattributes.servicePort=1102
	# rmi socket factory timeout
	jcs.remotecache.serverattributes.rmiSocketFactoryTimeoutMillis=5000
	# cluster setting
	jcs.remotecache.serverattributes.LocalClusterConsistency=true
	jcs.remotecache.serverattributes.AllowClusterGet=true
	]]>
	</source>
	<p>
	Remote servers can be chained (or clustered). This
	allows gets from local caches to be distributed
	between multiple remote servers. Since gets are the
	most common operation for caches, remote server
	chaining can help scale a caching solution.
	</p>
	<p>
	The
	<code>LocalClusterConsistency</code>
	setting tells the remote cache server if it should
	broadcast updates received from other cluster
	servers to registered local caches.
	</p>
	<p>
	The
	<code>AllowClusterGet</code>
	setting tells the remote cache server whether it
	should allow the cache to look in non-local
	auxiliaries for items if they are not present.
	Basically, if the get request is not from a cluster
	server, the cache will treat it as if it originated
	locally. If the get request originated from a
	cluster client, then the get will be restricted to
	local (i.e. memory and disk) auxiliaries. Hence,
	cluster gets can only go one server deep. They
	cannot be chained. By default this setting is true.
	</p>
	<p>
	To use remote server clustering, the remote cache
	will have to be told what regions to cluster. The
	configuration below will cluster all
	non-preconfigured regions with
	<code>RCluster1</code>
	.
	</p>
	<source>
	<![CDATA[
	# sets the default aux value for any non configured caches
	jcs.default=DC,RCluster1
	jcs.default.cacheattributes=
	org.apache.commons.jcs3.engine.CompositeCacheAttributes
	jcs.default.cacheattributes.MaxObjects=1000

	jcs.auxiliary.RCluster1=
	org.apache.commons.jcs3.auxiliary.remote.RemoteCacheFactory
	jcs.auxiliary.RCluster1.attributes=
	org.apache.commons.jcs3.auxiliary.remote.RemoteCacheAttributes
	jcs.auxiliary.RCluster1.attributes.RemoteTypeName=CLUSTER
	jcs.auxiliary.RCluster1.attributes.RemoveUponRemotePut=false
	jcs.auxiliary.RCluster1.attributes.ClusterServers=localhost:1103
	jcs.auxiliary.RCluster1.attributes.GetOnly=false
	]]>
	</source>
	<p>
	RCluster1 is configured to talk to a remote server
	at
	<code>localhost:1103</code>
	. Additional servers can be added in a comma
	separated list.
	</p>
	<p>
	If we startup another remote server listening to
	port 1103, (ServerB) then we can have that server
	talk to the server we have been configuring,
	listening at 1102 (ServerA). This would allow us to
	set some local caches to talk to ServerA and some to
	talk to ServerB. The two remote servers will
	broadcast all puts and removes between themselves,
	and the get requests from local caches could be
	divided. The local caches do not need to know
	anything about the server chaining configuration,
	unless you want to use a standby, or failover
	server.
	</p>
	<p>
	We could also use ServerB as a hot standby. This can
	be done in two ways. You could have all local caches
	point to ServerA as a primary and ServerB as a
	secondary. Alternatively, you can set ServerA as the
	primary for some local caches and ServerB for the
	primary for some others.
	</p>
	<p>
	The local cache configuration below uses ServerA as
	a primary and ServerB as a backup. More than one
	backup can be defined, but only one will be used at
	a time. If the cache is connected to any server
	except the primary, it will try to restore the
	primary connection indefinitely, at 20 second
	intervals.
	</p>
	<source>
	<![CDATA[
	# Remote RMI Cache set up to failover
	jcs.auxiliary.RFailover=
	org.apache.commons.jcs3.auxiliary.remote.RemoteCacheFactory
	jcs.auxiliary.RFailover.attributes=
	org.apache.commons.jcs3.auxiliary.remote.RemoteCacheAttributes
	jcs.auxiliary.RFailover.attributes.FailoverServers=
	localhost:1102,localhost:1103
	jcs.auxiliary.RC.attributes.RemoveUponRemotePut=true
	jcs.auxiliary.RFailover.attributes.GetOnly=false
	]]>
	</source>
	</subsection>
	<subsection name="Server Startup / Shutdown">
	<p>
	It is highly recommended that you embed the Remote
	Cache Server in a Servlet container such as Tomcat.
	Running inside Tomcat allows you to use the
	JCSAdmin.jsp page. It also takes care of the
	complexity of creating working startup and shutdown
	scripts.
	</p>
	<p>
	JCS provides a convenient startup servlet for this
	purpose. It will start the registry and bind the
	JCS server to the registry. To use the startup
	servlet, add the following to the web.xml file and
	make sure you have the cache.ccf file in the
	WEB-INF/classes directly of your war file.
	</p>
	<source>
	<![CDATA[
	<servlet>
	<servlet-name>JCSRemoteCacheStartupServlet</servlet-name>
	<servlet-class>
	org.apache.commons.jcs3.auxiliary.remote.server.RemoteCacheStartupServlet
	</servlet-class>
	<load-on-startup>1</load-on-startup>
	</servlet>


	<servlet-mapping>
	<servlet-name>JCSRemoteCacheStartupServlet</servlet-name>
	<url-pattern>/jcs</url-pattern>
	</servlet-mapping>
	]]>
	</source>

	</subsection>
	</section>

	</body>
	</document>