xdocs/faq.fml

<?xml version="1.0" encoding="UTF-8"?>
<!-- 
	/*
	* Copyright 2001-2004 The Apache Software Foundation.
	* 
	* Licensed 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.
	*/
-->

<faqs title="Frequently Asked Questions">

	<part id="configuration">
		<title>Configuration</title>

		<faq id="required-jars">
			<question>What jars are required by JCS?</question>
			<answer>
				<p>
					As of verison 1.2.7.0, the core of JCS (the LRU
					memory cache, the indexed disk cache, the TCP
					lateral, and the RMI remote server) requires only
					two other jars.
				</p>
				<p>
					<a
						href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html">
						concurrent
					</a>
				</p>
				<p>commons-logging</p>

				<p>
					Versions 1.2.6.9 and below also require the
					following two additional jars:
				</p>

				<p>commons-collections</p>
				<p>commons-lang</p>
				<p>
					All of the other dependencies listed on the project
					info page are for optional plugins.
				</p>
			</answer>
		</faq>

		<faq id="configuration-file">
			<question>How do I configure JCS?</question>
			<answer>
				<p>
					By default JCS looks for a cache.ccf file in the
					classpath. You must have a configuration file on the
					classpath to use JCS. The documentation describes
					how to configure the cache.
				</p>
			</answer>
		</faq>

		<faq id="manual-configuration">
			<question>
				How can I configure JCS with my own properties?
			</question>

			<answer>
				<p>
					You don't have to put the cache.ccf file in the
					classpath; instead you can do the following:
				</p>
				<code>
					CompositeCacheManager ccm =
					CompositeCacheManager.getUnconfiguredInstance();

					Properties props = new Properties();

					props.load(/* load properties from some location
					defined by your app */);

					ccm.configure(props);
				</code>
			</answer>
		</faq>

		<faq id="configuration-system-properties">
			<question>
				Can JCS use system properties during configuration?
			</question>
			<answer>
				<p>
					Yes. JCS will look for a system property for any
					name inside the delimiters ${}. Also, JCS will check
					to see if any property key in the cache.ccf is
					defined in the system properties. If so, the system
					value will be used.
				</p>
			</answer>
		</faq>
	</part>

	<part id="general-questions">
		<title>General Questions</title>

		<faq id="jcs-vs-ehcache">
			<question>Is JCS faster than EHCache?</question>
			<answer>
				<p>
					Yes. JCS is almost twice as fast as EHCache. JCS
					1.2.7.0, using the default LRU Memory Cache, has
					proven to be nearly twice as fast as EHCache
					1.2-beta4 at gets and puts. The EHCache benchmark
					data is unsubstantiated and very old. As such the
					EHCache site benchmark data is completely
					inaccurate.
					<a href="JCSvsEHCache.html">Read More</a>
				</p>
			</answer>
		</faq>

		<faq id="admin-jsp">
			<question>Where can I get the admin jsp?</question>
			<answer>
				<p>
					You can download the admin jsp
					<a
						href="http://svn.apache.org/viewcvs.cgi/jakarta/jcs/trunk/src/java/org/apache/jcs/admin/JCSAdmin.jsp">
						here
					</a>
					.
				</p>
			</answer>
		</faq>

		<faq id="source-code">
			<question>Where can I get the source?</question>
			<answer>
				<p>
					You can view the source
					<a
						href="http://svn.apache.org/viewcvs.cgi/jakarta/jcs/trunk/">
						here
					</a>
					or get the source code from subversion with <code>svn co
					http://svn.apache.org/repos/asf/jakarta/jcs/trunk</code>.
					The tagged releases are available with <code>svn co.</code> ex.
					http://svn.apache.org/repos/asf/jakarta/jcs/tags/jcs_1_2_7_0
				</p>
			</answer>
		</faq>
		<faq id="compiling-source">
			<question>How do I compile the source?</question>
			<answer>
				<p>
					You first need to install
					<a href="http://maven.apache.org/">Maven 1.0.2</a>
					The download is available at
					http://maven.apache.org/maven-1.x/start/download.html.
					Maven 2.0 is not supported yet. After installing run
					"maven" which compiles and tests the entire package.
					To build a jar run "maven jar".
				</p>
			</answer>
		</faq>
	</part>

	<part id="elements">
		<title>Elements</title>

		<faq id="element-attributes">
			<question>How do I set the element attributes?</question>
			<answer>
				<p>
					Every element put into the cache has its own set of
					attributes. By default elements are given a copy of
					the default element attributes associated with a
					region. You can also specify the attributes to use
					for an element when you put it in the cache. See
					<a href="ElementAttributes.html">
						Element Attributes
					</a>
					for more information on the attributes that are
					available.
				</p>
			</answer>
		</faq>

		<faq id="element-events">
			<question>How do I register an element event?</question>
			<answer>
				<p>
					Element event handlers must be added to the element
					attributes. See
					<a href="ElementEventHandling.html">
						Element Event Handling
					</a>
					for more information on how to handle element
					events.
				</p>
			</answer>
		</faq>

		<faq id="hierarchical-removal">
			<question>
				Can I remove all items beginning with part of a key?
			</question>
			<answer>
				<p>
					Yes, but it is somewhat expensive, since some of the
					auxiliaries will have to iterate over their keysets.
					Although all the auxiliaries honor this, it is not
					part of the auxiliary API. There is no method along
					the lines of "removeStartingWith", but all the remove
					methods can do it.
				</p>
				<p>
					By default, the hierarchical key delimiter used in
					JCS is a colon. You cannot add a String key that
					ends with a colon. If you call remove with a String
					key that ends in a colon, everything that has a key
					that starts with the argument will be removed.
				</p>
				<p>If your keys are in this format</p>
				<p>TYPE:SOURCE:OBJECT</p>
				<p>
					And you put n objects int he cache with keys like
					this
				</p>
				<p>"ABC:123:0" to "ABC:123:n"</p>
				<p>then you could remove all the obejcts by calling</p>
				<p>jcs.remove( "ABC:123:" );</p>
			</answer>
		</faq>
	</part>

	<part id="indexed-disk-cache">
		<title>Indexed Disk Cache</title>

		<faq id="thread-pool">
			<question>
				How do I limit the number of threads used by the disk
				cache?
			</question>
			<answer>
				<p>
					The indexed disk cache uses an event queue for each
					region. By default these queues are worked by their
					own dedicated threads. Hence, you will have one
					thread per disk cache region. Although the queues
					kill off idle threads, you may want to limit the
					overall number of threads used by the queues. You
					can do this by telling the disk cache to use a
					thread pool. The configuration is described
					<a href="IndexedDiskAuxCache.html">
						on the disk cache configuration page
					</a>
					.
				</p>
			</answer>
		</faq>
	</part>

	<part id="remote-cache-server">
		<title>Remote Cache Server</title>

		<faq id="classes">
			<question>
				Do I need to put my jars in the classpath of the remote
				server?
			</question>
			<answer>
				<p>
					No. The remote server never deserializes your
					classes.
				</p>
			</answer>
		</faq>
	</part>

</faqs>