1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
|
<?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>Getting Started -- Introduction</title>
<author email="asmuts@apache.org">Aaron Smuts</author>
</properties>
<body>
<section name="Getting Started">
<p>
To start using JCS you need to (1) understand the core
concepts, (2) download JCS, (3) get the required
dependencies, (4) configure JCS, and (5) then start
programming to it. The purpose of the getting started
guide is to help you get up and running with JCS as
quickly as possible. In depth documentation on the
various features of JCS is provided in the User's Guide.
</p>
</section>
<section name="STEP 1: Understand the Core Concepts">
<p>
In order to use JCS, you must understand a few core
concepts, most importantly you need to know the
difference between "elements," "regions," and
"auxiliaries".
</p>
<p>
JCS is an object cache. You can put objects, or
"elements," into JCS and reference them via a key, much
like a hashtable.
</p>
<p>
You can think of JCS as a collection of hashtables that
you reference by name. Each of these hashtables is
called a "region," and each region can be configured
independently of the others. For instance, I may have a
region called Cities where I cache City objects that
change infrequently. I may also define a region called
Products where I cache product data that changes more
frequently. I would configure the volatile Product
region to expire elements more quickly than the City
region.
</p>
<p>
"Auxiliaries" are optional plugins that a region can
use. The core auxiliaries are the Indexed Disk Cache,
the TCP Lateral Cache, and the Remote Cache Server. The
Disk Cache, for example, allows you to swap items onto
disk when a memory threshold is reached. You can read
more about the available auxiliaries
<a href="../JCSPlugins.html">HERE</a>
.
</p>
</section>
<section name="STEP 2: Download JCS">
<p>
Download the latest version of JCS. The latest JCS
builds are located
<a
href="http://www.apache.org/dist/commons/jcs/">
HERE
</a>
</p>
<p>
If you would like to build JCS yourself, check it out
from Subversion and build it as you would any other
project built by Maven. The location of the
repository is documented in the project info pages that
are linked via the left nav.
</p>
</section>
<section name="STEP 3: Get the Required Dependencies">
<p>
Beginning with version 2.0 the core of JCS (the LRU memory
cache, the indexed disk cache, the TCP lateral, and the
RMI remote server) requires only commons-logging.
</p>
<p>
Beginning with version 1.2.7.0 and up to version 1.3, 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>
</section>
<section name="STEP 4: Configure JCS">
<p>
JCS is configured from a properties file called
"cache.ccf". There are alternatives to using this file,
but they are beyond the scope of the getting started
guide.
</p>
<p>
The cache configuration has three parts: default,
regions, and auxiliaries. You can think of the
auxiliaries as log4j appenders and the regions as log4j
categories. For each region (or category) you can
specify and auxiliary (or appender to use). If you don't
define a region in the cache.ccf, then the default
settings are used. The difference between JCS and log4j
is that in JCS, pre-defined regions do not inherent
auxiliaries from the default region.
</p>
<p>
The following cache.ccf file defines one region called
"testCache1" and uses the Indexed Disk Cache, here
called "DC" by default. The LRU Memory Cache is selected
as the memory manager.
</p>
<source>
<![CDATA[
# DEFAULT CACHE REGION
jcs.default=DC
jcs.default.cacheattributes=
org.apache.commons.jcs.engine.CompositeCacheAttributes
jcs.default.cacheattributes.MaxObjects=1000
jcs.default.cacheattributes.MemoryCacheName=
org.apache.commons.jcs.engine.memory.lru.LRUMemoryCache
jcs.default.cacheattributes.UseMemoryShrinker=false
jcs.default.cacheattributes.MaxMemoryIdleTime=3600
jcs.default.cacheattributes.ShrinkerInterval=60
jcs.default.elementattributes=org.apache.commons.jcs.engine.ElementAttributes
jcs.default.elementattributes.IsEternal=false
jcs.default.elementattributes.MaxLife=21600
jcs.default.elementattributes.IdleTime=1800
jcs.default.elementattributes.IsSpool=true
jcs.default.elementattributes.IsRemote=true
jcs.default.elementattributes.IsLateral=true
# PRE-DEFINED CACHE REGIONS
jcs.region.testCache1=DC
jcs.region.testCache1.cacheattributes=
org.apache.commons.jcs.engine.CompositeCacheAttributes
jcs.region.testCache1.cacheattributes.MaxObjects=1000
jcs.region.testCache1.cacheattributes.MemoryCacheName=
org.apache.commons.jcs.engine.memory.lru.LRUMemoryCache
jcs.region.testCache1.cacheattributes.UseMemoryShrinker=false
jcs.region.testCache1.cacheattributes.MaxMemoryIdleTime=3600
jcs.region.testCache1.cacheattributes.ShrinkerInterval=60
jcs.region.testCache1.cacheattributes.MaxSpoolPerRun=500
jcs.region.testCache1.elementattributes=org.apache.commons.jcs.engine.ElementAttributes
jcs.region.testCache1.elementattributes.IsEternal=false
# AVAILABLE AUXILIARY CACHES
jcs.auxiliary.DC=
org.apache.commons.jcs.auxiliary.disk.indexed.IndexedDiskCacheFactory
jcs.auxiliary.DC.attributes=
org.apache.commons.jcs.auxiliary.disk.indexed.IndexedDiskCacheAttributes
jcs.auxiliary.DC.attributes.DiskPath=${user.dir}/jcs_swap
jcs.auxiliary.DC.attributes.MaxPurgatorySize=10000000
jcs.auxiliary.DC.attributes.MaxKeySize=1000000
jcs.auxiliary.DC.attributes.MaxRecycleBinSize=5000
jcs.auxiliary.DC.attributes.OptimizeAtRemoveCount=300000
jcs.auxiliary.DC.attributes.ShutdownSpoolTimeLimit=60
]]>
</source>
<p>
Basic JCS configuration is described in more detail
<a href="../BasicJCSConfiguration.html">HERE</a>
</p>
<p>
Element level configuration is described in more detail
<a href="../ElementAttributes.html">HERE</a>
</p>
<p>
For more information on advanced configuration options
and the available plugins, see the User's Guide.
</p>
</section>
<section name="STEP 5: Programming to JCS">
<p>
JCS provides a few convenient classes that should meet all
your needs.
</p>
<p>
To get a cache region you simply ask JCS for the region
by name. If you wanted to use JCS for City objects, you
would do something like this:
</p>
<source>
<![CDATA[
import org.apache.commons.jcs.JCS;
import org.apache.commons.jcs.access.CacheAccess;
import org.apache.commons.jcs.access.exception.CacheException;
. . .
private static final String cacheRegionName = "city";
private CacheAccess<String, City> cache = null;
. . .
// in your constructor you might do this
try
{
CacheAccess<String, City> c = JCS.getInstance( this.getCacheRegionName() );
setCache( c );
}
catch ( CacheException e )
{
log.error( "Problem initializing cache for region name ["
+ this.getCacheRegionName() + "].", e );
}
. . .
// to get a city out of the cache by id you might do this:
String key = "cityId:" + String.valueOf( id );
City city = cache.get( key );
. . .
// to put a city object in the cache, you could do this:
try
{
// if it isn't null, insert it
if ( city != null )
{
cache.put( key, city );
}
}
catch ( CacheException e )
{
log.error( "Problem putting "
+ city + " in the cache, for key " + key, e );
}
]]>
</source>
</section>
</body>
</document>
|
