Source code

001package org.apache.commons.jcs;
002
003import java.util.Properties;
004
005/*
006 * Licensed to the Apache Software Foundation (ASF) under one
007 * or more contributor license agreements.  See the NOTICE file
008 * distributed with this work for additional information
009 * regarding copyright ownership.  The ASF licenses this file
010 * to you under the Apache License, Version 2.0 (the
011 * "License"); you may not use this file except in compliance
012 * with the License.  You may obtain a copy of the License at
013 *
014 *   http://www.apache.org/licenses/LICENSE-2.0
015 *
016 * Unless required by applicable law or agreed to in writing,
017 * software distributed under the License is distributed on an
018 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
019 * KIND, either express or implied.  See the License for the
020 * specific language governing permissions and limitations
021 * under the License.
022 */
023
024import org.apache.commons.jcs.access.CacheAccess;
025import org.apache.commons.jcs.access.GroupCacheAccess;
026import org.apache.commons.jcs.access.exception.CacheException;
027import org.apache.commons.jcs.engine.behavior.ICompositeCacheAttributes;
028import org.apache.commons.jcs.engine.behavior.IElementAttributes;
029import org.apache.commons.jcs.engine.control.CompositeCache;
030import org.apache.commons.jcs.engine.control.CompositeCacheManager;
031import org.apache.commons.jcs.engine.control.group.GroupAttrName;
032
033/**
034 * Simple class for using JCS. To use JCS in your application, you can use the static methods of
035 * this class to get access objects (instances of this class) for your cache regions. One CacheAccess
036 * object should be created for each region you want to access. If you have several regions, then
037 * get instances for each. For best performance the getInstance call should be made in an
038 * initialization method.
039 */
040public abstract class JCS
041{
042    /** cache.ccf alternative. */
043    private static String configFilename = null;
044
045    /** alternative configuration properties */
046    private static Properties configProps = null;
047
048    /** Cache manager use by the various forms of defineRegion and getAccess */
049    private static CompositeCacheManager cacheMgr;
050
051    /**
052     * Define a new cache region with the given name. In the oracle specification, these attributes
053     * are global and not region specific, regional overrides is a value add each region should be
054     * able to house both cache and element attribute sets. It is more efficient to define a cache
055     * in the props file and then strictly use the get access method. Use of the define region
056     * outside of an initialization block should be avoided.
057     * <p>
058     * @param name Name that will identify the region
059     * @return CacheAccess instance for the new region
060     * @throws CacheException
061     * 
062     * @deprecated Duplicate of getInstance(String)
063     */
064    @Deprecated
065        public static <K, V> CacheAccess<K, V> defineRegion( String name )
066        throws CacheException
067    {
068        CompositeCache<K, V> cache = getCacheManager().getCache( name );
069        return new CacheAccess<K, V>( cache );
070    }
071
072    /**
073     * Define a new cache region with the specified name and attributes.
074     * <p>
075     * @param name Name that will identify the region
076     * @param cattr CompositeCacheAttributes for the region
077     * @return CacheAccess instance for the new region
078     * @throws CacheException
079     * 
080     * @deprecated Duplicate of getInstance(String, ICompositeCacheAttributes)
081     */
082    @Deprecated
083        public static <K, V> CacheAccess<K, V> defineRegion( String name, ICompositeCacheAttributes cattr )
084        throws CacheException
085    {
086        CompositeCache<K, V> cache = getCacheManager().getCache( name, cattr );
087        return new CacheAccess<K, V>( cache );
088    }
089
090    /**
091     * Define a new cache region with the specified name and attributes and return a CacheAccess to
092     * it.
093     * <p>
094     * @param name Name that will identify the region
095     * @param cattr CompositeCacheAttributes for the region
096     * @param attr Attributes for the region
097     * @return CacheAccess instance for the new region
098     * @throws CacheException
099     * 
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}