View Javadoc
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 }