<?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>Block Disk Cache</title>
		<author email="asmuts@apache.org">Aaron Smuts</author>
	</properties>

	<body>
		<section name="Block Disk Auxiliary Cache">
			<p>
				The Block Disk Cache stores cached values on disk. Like
				the Indexed Disk Cache, the Block Disk Cache keeps the
				keys in memory. The Block Disk Cache stores the values
				in a group of fixed size blocks, whereas the Indexed
				Disk Cache writes items to disk in one chunk.
			</p>
			<p>
				The Block Disk Cache has advantages over the normal
				indexed model for regions where the size of the items
				varies. Since all the blocks are the same size, the
				recycle bin is very simple. It is just a list of block
				numbers. Also, the Block Disk Cache will never need to
				be optimized. Once the maximum number of keys is
				reached, blocks will be reused.
			</p>
			
			<section name="Size limitation">
				<p>
					There are two ways to limit the cache size: using element
					count and element size. When using element count, in disk
					store there will be at most MaxKeySize elements (not disk 
					blocks). When using element size, there will be at most
					KeySize kB of elements stored in the data file. As the Block 
					Disk Cache doesn't need optimization, the data file 
					will be not longer than specified. The limit does not
					cover the key file size. The mode is chosen using DiskLimitType. 
					Allowed values are: COUNT and SIZE.
				</p>
			</section>

			<subsection name="Example cache.ccf">
				<source>
					<![CDATA[
##############################################################
##### DEFAULT REGION  ########################################

jcs.default=blockDiskCache
jcs.default.cacheattributes=org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.default.cacheattributes.MaxObjects=0
jcs.default.cacheattributes.MemoryCacheName=org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache

##############################################################
##### AUXILIARY CACHES  ######################################

# Block Disk Cache
jcs.auxiliary.blockDiskCache=org.apache.commons.jcs3.auxiliary.disk.block.BlockDiskCacheFactory
jcs.auxiliary.blockDiskCache.attributes=org.apache.commons.jcs3.auxiliary.disk.block.BlockDiskCacheAttributes
jcs.auxiliary.blockDiskCache.attributes.DiskPath=target/test-sandbox/block-disk-cache-huge
jcs.auxiliary.blockDiskCache.attributes.MaxPurgatorySize=300000
jcs.auxiliary.blockDiskCache.attributes.MaxKeySize=1000000
jcs.auxiliary.blockDiskCache.attributes.blockSizeBytes=500
jcs.auxiliary.blockDiskCache.attributes.EventQueueType=SINGLE
#jcs.auxiliary.blockDiskCache.attributes.EventQueuePoolName=disk_cache_event_queue

##############################################################
################## THREAD POOL CONFIGURATION #################

# Default thread pool config
thread_pool.default.boundarySize=2000
thread_pool.default.maximumPoolSize=150
thread_pool.default.minimumPoolSize=4
thread_pool.default.keepAliveTime=350000
#RUN ABORT WAIT BLOCK DISCARDOLDEST
thread_pool.default.whenBlockedPolicy=RUN
thread_pool.default.startUpSize=4

# Disk Cache pool
thread_pool.disk_cache_event_queue.useBoundary=false
thread_pool.disk_cache_event_queue.minimumPoolSize=2
thread_pool.disk_cache_event_queue.keepAliveTime=3500
thread_pool.disk_cache_event_queue.startUpSize=10
        ]]>
				</source>
			</subsection>
		</section>
	</body>
</document>