001package org.apache.commons.jcs3;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import java.util.Properties;
023
024import org.apache.commons.jcs3.access.CacheAccess;
025import org.apache.commons.jcs3.access.GroupCacheAccess;
026import org.apache.commons.jcs3.access.exception.CacheException;
027import org.apache.commons.jcs3.engine.behavior.ICompositeCacheAttributes;
028import org.apache.commons.jcs3.engine.behavior.IElementAttributes;
029import org.apache.commons.jcs3.engine.control.CompositeCache;
030import org.apache.commons.jcs3.engine.control.CompositeCacheManager;
031import org.apache.commons.jcs3.engine.control.group.GroupAttrName;
032import org.apache.commons.jcs3.log.LogManager;
033
034/**
035 * Simple class for using JCS. To use JCS in your application, you can use the static methods of
036 * this class to get access objects (instances of this class) for your cache regions. One CacheAccess
037 * object should be created for each region you want to access. If you have several regions, then
038 * get instances for each. For best performance the getInstance call should be made in an
039 * initialization method.
040 */
041public abstract class JCS
042{
043    /** cache.ccf alternative. */
044    private static String configFilename;
045
046    /** alternative configuration properties */
047    private static Properties configProps;
048
049    /** Cache manager use by the various forms of defineRegion and getAccess */
050    private static CompositeCacheManager cacheMgr;
051
052    /**
053     * Set the filename that the cache manager will be initialized with. Only matters before the
054     * instance is initialized.
055     * <p>
056     * @param configFilename
057     */
058    public static void setConfigFilename( final String configFilename )
059    {
060        JCS.configFilename = configFilename;
061    }
062
063    /**
064     * Set the properties that the cache manager will be initialized with. Only
065     * matters before the instance is initialized.
066     *
067     * @param configProps
068     */
069    public static void setConfigProperties( final Properties configProps )
070    {
071        JCS.configProps = configProps;
072    }
073
074    /**
075     * Set the log system. Must be called before getInstance is called
076     * Predefined Log systems are {@link LogManager#LOGSYSTEM_JAVA_UTIL_LOGGING}
077     * and {@link LogManager#LOGSYSTEM_LOG4J2}
078     *
079     * @param logSystem the logSystem to set
080     */
081    public static void setLogSystem(final String logSystem)
082    {
083        LogManager.setLogSystem(logSystem);
084    }
085
086    /**
087     * Shut down the cache manager and set the instance to null
088     */
089    public static void shutdown()
090    {
091        synchronized ( JCS.class )
092        {
093            if ( cacheMgr != null && cacheMgr.isInitialized())
094            {
095                cacheMgr.shutDown();
096            }
097
098            cacheMgr = null;
099        }
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}