1 package org.apache.commons.jcs;
2
3 import java.util.Properties;
4
5 /*
6 * Licensed to the Apache Software Foundation (ASF) under one
7 * or more contributor license agreements. See the NOTICE file
8 * distributed with this work for additional information
9 * regarding copyright ownership. The ASF licenses this file
10 * to you under the Apache License, Version 2.0 (the
11 * "License"); you may not use this file except in compliance
12 * with the License. You may obtain a copy of the License at
13 *
14 * http://www.apache.org/licenses/LICENSE-2.0
15 *
16 * Unless required by applicable law or agreed to in writing,
17 * software distributed under the License is distributed on an
18 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19 * KIND, either express or implied. See the License for the
20 * specific language governing permissions and limitations
21 * under the License.
22 */
23
24 import org.apache.commons.jcs.access.CacheAccess;
25 import org.apache.commons.jcs.access.GroupCacheAccess;
26 import org.apache.commons.jcs.access.exception.CacheException;
27 import org.apache.commons.jcs.engine.behavior.ICompositeCacheAttributes;
28 import org.apache.commons.jcs.engine.behavior.IElementAttributes;
29 import org.apache.commons.jcs.engine.control.CompositeCache;
30 import org.apache.commons.jcs.engine.control.CompositeCacheManager;
31 import org.apache.commons.jcs.engine.control.group.GroupAttrName;
32
33 /**
34 * Simple class for using JCS. To use JCS in your application, you can use the static methods of
35 * this class to get access objects (instances of this class) for your cache regions. One CacheAccess
36 * object should be created for each region you want to access. If you have several regions, then
37 * get instances for each. For best performance the getInstance call should be made in an
38 * initialization method.
39 */
40 public abstract class JCS
41 {
42 /** cache.ccf alternative. */
43 private static String configFilename = null;
44
45 /** alternative configuration properties */
46 private static Properties configProps = null;
47
48 /** Cache manager use by the various forms of defineRegion and getAccess */
49 private static CompositeCacheManager cacheMgr;
50
51 /**
52 * Define a new cache region with the given name. In the oracle specification, these attributes
53 * are global and not region specific, regional overrides is a value add each region should be
54 * able to house both cache and element attribute sets. It is more efficient to define a cache
55 * in the props file and then strictly use the get access method. Use of the define region
56 * outside of an initialization block should be avoided.
57 * <p>
58 * @param name Name that will identify the region
59 * @return CacheAccess instance for the new region
60 * @throws CacheException
61 *
62 * @deprecated Duplicate of getInstance(String)
63 */
64 @Deprecated
65 public static <K, V> CacheAccess<K, V> defineRegion( String name )
66 throws CacheException
67 {
68 CompositeCache<K, V> cache = getCacheManager().getCache( name );
69 return new CacheAccess<K, V>( cache );
70 }
71
72 /**
73 * Define a new cache region with the specified name and attributes.
74 * <p>
75 * @param name Name that will identify the region
76 * @param cattr CompositeCacheAttributes for the region
77 * @return CacheAccess instance for the new region
78 * @throws CacheException
79 *
80 * @deprecated Duplicate of getInstance(String, ICompositeCacheAttributes)
81 */
82 @Deprecated
83 public static <K, V> CacheAccess<K, V> defineRegion( String name, ICompositeCacheAttributes cattr )
84 throws CacheException
85 {
86 CompositeCache<K, V> cache = getCacheManager().getCache( name, cattr );
87 return new CacheAccess<K, V>( cache );
88 }
89
90 /**
91 * Define a new cache region with the specified name and attributes and return a CacheAccess to
92 * it.
93 * <p>
94 * @param name Name that will identify the region
95 * @param cattr CompositeCacheAttributes for the region
96 * @param attr Attributes for the region
97 * @return CacheAccess instance for the new region
98 * @throws CacheException
99 *
100 * @deprecated Duplicate of getInstance(String, ICompositeCacheAttributes, IElementAttributes)
101 */
102 @Deprecated
103 public static <K, V> CacheAccess<K, V> defineRegion( String name, ICompositeCacheAttributes cattr, IElementAttributes attr )
104 throws CacheException
105 {
106 CompositeCache<K, V> cache = getCacheManager().getCache( name, cattr, attr );
107 return new CacheAccess<K, V>( cache );
108 }
109
110 /**
111 * Set the filename that the cache manager will be initialized with. Only matters before the
112 * instance is initialized.
113 * <p>
114 * @param configFilename
115 */
116 public static void setConfigFilename( String configFilename )
117 {
118 JCS.configFilename = configFilename;
119 }
120
121 /**
122 * Set the properties that the cache manager will be initialized with. Only
123 * matters before the instance is initialized.
124 *
125 * @param configProps
126 */
127 public static void setConfigProperties( Properties configProps )
128 {
129 JCS.configProps = configProps;
130 }
131
132 /**
133 * Shut down the cache manager and set the instance to null
134 */
135 public static void shutdown()
136 {
137 synchronized ( JCS.class )
138 {
139 if ( cacheMgr != null && cacheMgr.isInitialized())
140 {
141 cacheMgr.shutDown();
142 }
143
144 cacheMgr = null;
145 }
146 }
147
148 /**
149 * Helper method which checks to make sure the cacheMgr class field is set, and if not requests
150 * an instance from CacheManagerFactory.
151 *
152 * @throws CacheException if the configuration cannot be loaded
153 */
154 private static CompositeCacheManager getCacheManager() throws CacheException
155 {
156 synchronized ( JCS.class )
157 {
158 if ( cacheMgr == null || !cacheMgr.isInitialized())
159 {
160 if ( configProps != null )
161 {
162 cacheMgr = CompositeCacheManager.getUnconfiguredInstance();
163 cacheMgr.configure( configProps );
164 }
165 else if ( configFilename != null )
166 {
167 cacheMgr = CompositeCacheManager.getUnconfiguredInstance();
168 cacheMgr.configure( configFilename );
169 }
170 else
171 {
172 cacheMgr = CompositeCacheManager.getInstance();
173 }
174 }
175
176 return cacheMgr;
177 }
178 }
179
180 /**
181 * Get a CacheAccess which accesses the provided region.
182 * <p>
183 * @param region Region that return CacheAccess will provide access to
184 * @return A CacheAccess which provides access to a given region.
185 * @throws CacheException
186 */
187 public static <K, V> CacheAccess<K, V> getInstance( String region )
188 throws CacheException
189 {
190 CompositeCache<K, V> cache = getCacheManager().getCache( region );
191 return new CacheAccess<K, V>( cache );
192 }
193
194 /**
195 * Get a CacheAccess which accesses the provided region.
196 * <p>
197 * @param region Region that return CacheAccess will provide access to
198 * @param icca CacheAttributes for region
199 * @return A CacheAccess which provides access to a given region.
200 * @throws CacheException
201 */
202 public static <K, V> CacheAccess<K, V> getInstance( String region, ICompositeCacheAttributes icca )
203 throws CacheException
204 {
205 CompositeCache<K, V> cache = getCacheManager().getCache( region, icca );
206 return new CacheAccess<K, V>( cache );
207 }
208
209 /**
210 * Get a CacheAccess which accesses the provided region.
211 * <p>
212 * @param region Region that return CacheAccess will provide access to
213 * @param icca CacheAttributes for region
214 * @param eattr ElementAttributes for the region
215 * @return A CacheAccess which provides access to a given region.
216 * @throws CacheException
217 */
218 public static <K, V> CacheAccess<K, V> getInstance( String region, ICompositeCacheAttributes icca, IElementAttributes eattr )
219 throws CacheException
220 {
221 CompositeCache<K, V> cache = getCacheManager().getCache( region, icca, eattr );
222 return new CacheAccess<K, V>( cache );
223 }
224
225 /**
226 * Get a GroupCacheAccess which accesses the provided region.
227 * <p>
228 * @param region Region that return GroupCacheAccess will provide access to
229 * @return A GroupCacheAccess which provides access to a given region.
230 * @throws CacheException
231 */
232 public static <K, V> GroupCacheAccess<K, V> getGroupCacheInstance( String region )
233 throws CacheException
234 {
235 CompositeCache<GroupAttrName<K>, V> cache = getCacheManager().getCache( region );
236 return new GroupCacheAccess<K, V>( cache );
237 }
238
239 /**
240 * Get a GroupCacheAccess which accesses the provided region.
241 * <p>
242 * @param region Region that return GroupCacheAccess will provide access to
243 * @param icca CacheAttributes for region
244 * @return A GroupCacheAccess which provides access to a given region.
245 * @throws CacheException
246 */
247 public static <K, V> GroupCacheAccess<K, V> getGroupCacheInstance( String region, ICompositeCacheAttributes icca )
248 throws CacheException
249 {
250 CompositeCache<GroupAttrName<K>, V> cache = getCacheManager().getCache( region, icca );
251 return new GroupCacheAccess<K, V>( cache );
252 }
253
254 /**
255 * Get a GroupCacheAccess which accesses the provided region.
256 * <p>
257 * @param region Region that return CacheAccess will provide access to
258 * @param icca CacheAttributes for region
259 * @param eattr ElementAttributes for the region
260 * @return A GroupCacheAccess which provides access to a given region.
261 * @throws CacheException
262 */
263 public static <K, V> GroupCacheAccess<K, V> getGroupCacheInstance( String region, ICompositeCacheAttributes icca, IElementAttributes eattr )
264 throws CacheException
265 {
266 CompositeCache<GroupAttrName<K>, V> cache = getCacheManager().getCache( region, icca, eattr );
267 return new GroupCacheAccess<K, V>( cache );
268 }
269 }