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