001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.shiro.hazelcast.cache;
020
021import com.hazelcast.config.Config;
022import com.hazelcast.core.Hazelcast;
023import com.hazelcast.core.HazelcastInstance;
024import org.apache.shiro.ShiroException;
025import org.apache.shiro.cache.Cache;
026import org.apache.shiro.cache.CacheException;
027import org.apache.shiro.cache.CacheManager;
028import org.apache.shiro.cache.MapCache;
029import org.apache.shiro.util.Destroyable;
030import org.apache.shiro.util.Initializable;
031import org.slf4j.Logger;
032import org.slf4j.LoggerFactory;
033
034import java.util.Map;
035
036/**
037 * A {@code CacheManager} implementation backed by <a href="http://www.hazelcast.com/">Hazelcast</a>,
038 * &quot;an open source clustering and highly scalable data distribution platform for Java&quot;
039 * <p/>
040 * This implementation interacts with a {@link HazelcastInstance} to
041 * {@link HazelcastInstance#getMap(String) acquire} named {@link java.util.concurrent.ConcurrentMap ConcurrentMap}
042 * instances.  Those clustered/distributed Map instances are then wrapped and made available to {@code CacheManager}
043 * callers as {@link MapCache} instances via {@link #getCache(String)}.
044 * <h2>Configuration</h2>
045 * This implementation's backing {@code HazelcastInstance} can be configured in one of three ways:
046 * <ol>
047 * <li>Doing nothing and leveraging default Hazelcast configuration mechanisms</li>
048 * <li>Supplying an already-existing {@code HazelcastInstance}</li>
049 * <li>Supplying a {@link Config} instance and using that to create a new {@code HazelcastInstance}</li>
050 * </ol>
051 * <h3>Default Configuration</h3>
052 * If you simply instantiate a {@code HazelcastCacheManager} and do nothing further, its backing
053 * {@link HazelcastInstance} instance will be created automatically by calling
054 * {@link Hazelcast#newHazelcastInstance(com.hazelcast.config.Config) Hazelcast.newHazelcastInstance(null)}.
055 * <p/>
056 * The null argument instructs Hazelcast to use whatever default configuration mechanism it has at its disposal,
057 * usually a {@code hazelcast.xml} file at the root of the classpath, or if that is not present, the
058 * {@code hazelcast-default.xml} file contained in the Hazelcast {@code .jar} file itself.
059 * <p/>
060 * <h3>An existing {@code HazelcastInstance}</h3>
061 * If you have created a {@code HazelcastInstance} outside of Shiro's knowledge/control, you can simply configure it
062 * to be used by calling {@link #setHazelcastInstance(com.hazelcast.core.HazelcastInstance) setHazelcastInstance}.
063 * <p/>
064 * <h3>A {@link Config} instance</h3>
065 * If you do not want to use the above two options, you can have programmatic control over all of Hazelcast's
066 * configuration by <a href="http://www.hazelcast.com/docs/2.5/manual/multi_html/ch12.html">creating and configuring a
067 * Config instance</a>.
068 * <p/>
069 * Once constructed, you can set it via {@link #setConfig(com.hazelcast.config.Config) setConfig(config)}. This config
070 * instance will be used to acquire a new Hazelcast instance by calling
071 * {@link Hazelcast#newHazelcastInstance(Config) Hazelcast.newHazelcastInstance(config)}
072 *
073 * @see <a href="http://www.hazelcast.com/docs/2.5/manual/multi_html/ch12.html">Hazelcast Configuration Documentation</a>
074 * @since 1.3
075 */
076public class HazelcastCacheManager implements CacheManager, Initializable, Destroyable {
077
078    public static final Logger log = LoggerFactory.getLogger(HazelcastCacheManager.class);
079
080    private boolean implicitlyCreated = false;
081    private HazelcastInstance hazelcastInstance;
082    private Config config;
083
084    /**
085     * Returns a {@link MapCache} instance representing the named Hazelcast-managed
086     * {@link com.hazelcast.core.IMap IMap}.  The Hazelcast Map is obtained by calling
087     * {@link HazelcastInstance#getMap(String) hazelcastInstance.getMap(name)}.
088     *
089     * @param name the name of the cache to acquire.
090     * @param <K> the type of map key
091     * @param <V> the type of map value
092     * @return a {@link MapCache} instance representing the named Hazelcast-managed {@link com.hazelcast.core.IMap IMap}.
093     * @throws CacheException
094     * @see HazelcastInstance#getMap(String)
095     * @see #ensureHazelcastInstance()
096     *
097     */
098    public <K, V> Cache<K, V> getCache(String name) throws CacheException {
099        Map<K, V> map = ensureHazelcastInstance().getMap(name); //returned map is a ConcurrentMap
100        return new MapCache<K, V>(name, map);
101    }
102
103    /**
104     * Ensures that this implementation has a backing {@link HazelcastInstance}, and if not, implicitly creates one
105     * via {@link #createHazelcastInstance()}.
106     *
107     * @return the backing (potentially newly created) {@code HazelcastInstance}.
108     * @see #createHazelcastInstance()
109     * @see HazelcastInstance
110     */
111    protected HazelcastInstance ensureHazelcastInstance() {
112        if (this.hazelcastInstance == null) {
113            this.hazelcastInstance = createHazelcastInstance();
114            this.implicitlyCreated = true;
115        }
116        return this.hazelcastInstance;
117    }
118
119    /**
120     * Initializes this instance by {@link #ensureHazelcastInstance() ensuring} there is a backing
121     * {@link HazelcastInstance}.
122     *
123     * @throws ShiroException
124     * @see #ensureHazelcastInstance()
125     * @see HazelcastInstance
126     */
127    public void init() throws ShiroException {
128        ensureHazelcastInstance();
129    }
130
131    /**
132     * Implicitly creates and returns a new {@link HazelcastInstance} that will be used to back this implementation.
133     * This implementation calls:
134     * <pre>
135     * return Hazelcast.newHazelcastInstance(this.config);
136     * </pre>
137     * using any {@link #setConfig(com.hazelcast.config.Config) configured} {@code Config} object.  If no config
138     * object has been specified, {@code this.config} will be {@code null}, thereby using Hazelcast's
139     * <a href="http://www.hazelcast.com/docs/2.5/manual/multi_html/ch12.html">default configuration mechanism</a>.
140     * <p/>
141     * Can be overridden by subclasses for custom creation behavior.
142     *
143     * @return a new {@link HazelcastInstance} that will be used to back this implementation
144     * @see Hazelcast#newHazelcastInstance(com.hazelcast.config.Config)
145     * @see Config
146     */
147    protected HazelcastInstance createHazelcastInstance() {
148        return Hazelcast.newHazelcastInstance(this.config);
149    }
150
151    //needed for unit tests only - not part of Shiro's public API
152
153    /**
154     * NOT PART OF SHIRO'S ACCESSIBLE API.  DO NOT DEPEND ON THIS.  This method was added for testing purposes only.
155     * <p/>
156     * Returns {@code true} if this {@code HazelcastCacheManager} instance implicitly created the backing
157     * {@code HazelcastInstance}, or {@code false} if one was externally provided via
158     * {@link #setHazelcastInstance(com.hazelcast.core.HazelcastInstance) setHazelcastInstance}.
159     *
160     * @return {@code true} if this {@code HazelcastCacheManager} instance implicitly created the backing
161     *         {@code HazelcastInstance}, or {@code false} if one was externally provided via
162     *         {@link #setHazelcastInstance(com.hazelcast.core.HazelcastInstance) setHazelcastInstance}.
163     */
164    protected final boolean isImplicitlyCreated() {
165        return this.implicitlyCreated;
166    }
167
168    /**
169     * Destroys any {@link #ensureHazelcastInstance() implicitly created} backing {@code HazelcastInstance}.  If the
170     * backing Hazelcast was not implicitly created (i.e. because it was configured externally and supplied via
171     * {@link #setHazelcastInstance(com.hazelcast.core.HazelcastInstance) setHazelcastInstance}), this method does
172     * nothing.
173     *
174     * @throws Exception if there is a problem shutting down
175     */
176    public void destroy() throws Exception {
177        if (this.implicitlyCreated) {
178            try {
179                this.hazelcastInstance.getLifecycleService().shutdown();
180            } catch (Throwable t) {
181                if (log.isWarnEnabled()) {
182                    log.warn("Unable to cleanly shutdown implicitly created HazelcastInstance.  " +
183                            "Ignoring (shutting down)...", t);
184                }
185            } finally {
186                this.hazelcastInstance = null;
187                this.implicitlyCreated = false;
188            }
189        }
190    }
191
192    /**
193     * Returns the {@code HazelcastInstance} from which named {@link java.util.concurrent.ConcurrentMap ConcurrentMap}
194     * instances will be acquired to create {@link MapCache} instances.
195     *
196     * @return the {@code HazelcastInstance} from which named {@link java.util.concurrent.ConcurrentMap ConcurrentMap}
197     *         instances will be acquired to create {@link MapCache} instances.
198     */
199    public HazelcastInstance getHazelcastInstance() {
200        return hazelcastInstance;
201    }
202
203    /**
204     * Sets the {@code HazelcastInstance} from which named {@link java.util.concurrent.ConcurrentMap ConcurrentMap}
205     * instances will be acquired to create {@link MapCache} instances.
206     *
207     * @param hazelcastInstance the {@code HazelcastInstance} from which named
208     *                          {@link java.util.concurrent.ConcurrentMap ConcurrentMap} instances will be acquired to create
209     *                          {@link MapCache} instances.
210     */
211    public void setHazelcastInstance(HazelcastInstance hazelcastInstance) {
212        this.hazelcastInstance = hazelcastInstance;
213    }
214
215    /**
216     * Returns the Hazelcast {@code Config} object to use to create a backing {@code HazelcastInstance} if one is not
217     * {@link #setHazelcastInstance(com.hazelcast.core.HazelcastInstance) supplied}, or {@code null} if the
218     * default <a href="http://www.hazelcast.com/docs/2.5/manual/multi_html/ch12.html">Hazelcast configuration
219     * mechanisms</a> will be used.
220     *
221     * @return the Hazelcast {@code Config} object to use to create a backing {@code HazelcastInstance} if one is not
222     *         {@link #setHazelcastInstance(com.hazelcast.core.HazelcastInstance) supplied}, or {@code null} if the
223     *         default <a href="http://www.hazelcast.com/docs/2.5/manual/multi_html/ch12.html">Hazelcast configuration
224     *         mechanisms</a> will be used.
225     * @see Hazelcast#newHazelcastInstance(com.hazelcast.config.Config)
226     */
227    public Config getConfig() {
228        return config;
229    }
230
231    /**
232     * Sets the Hazelcast {@code Config} object to use to create a backing {@code HazelcastInstance} if one is not
233     * {@link #setHazelcastInstance(com.hazelcast.core.HazelcastInstance) supplied}.  {@code null} can be set if the
234     * default <a href="http://www.hazelcast.com/docs/2.5/manual/multi_html/ch12.html">Hazelcast configuration
235     * mechanisms</a> will be used.
236     *
237     * @param config the Hazelcast {@code Config} object to use to create a backing {@code HazelcastInstance} if one is not
238     *               {@link #setHazelcastInstance(com.hazelcast.core.HazelcastInstance) supplied}, or {@code null} if the
239     *               default <a href="http://www.hazelcast.com/docs/2.5/manual/multi_html/ch12.html">Hazelcast configuration
240     *               mechanisms</a> will be used.
241     */
242    public void setConfig(Config config) {
243        this.config = config;
244    }
245}