1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 package org.apache.shiro.hazelcast.cache; 20 21 import com.hazelcast.config.Config; 22 import com.hazelcast.core.Hazelcast; 23 import com.hazelcast.core.HazelcastInstance; 24 import org.apache.shiro.ShiroException; 25 import org.apache.shiro.cache.Cache; 26 import org.apache.shiro.cache.CacheException; 27 import org.apache.shiro.cache.CacheManager; 28 import org.apache.shiro.cache.MapCache; 29 import org.apache.shiro.util.Destroyable; 30 import org.apache.shiro.util.Initializable; 31 import org.slf4j.Logger; 32 import org.slf4j.LoggerFactory; 33 34 import java.util.Map; 35 36 /** 37 * A {@code CacheManager} implementation backed by <a href="http://www.hazelcast.com/">Hazelcast</a>, 38 * "an open source clustering and highly scalable data distribution platform for Java" 39 * <p/> 40 * This implementation interacts with a {@link HazelcastInstance} to 41 * {@link HazelcastInstance#getMap(String) acquire} named {@link java.util.concurrent.ConcurrentMap ConcurrentMap} 42 * instances. Those clustered/distributed Map instances are then wrapped and made available to {@code CacheManager} 43 * callers as {@link MapCache} instances via {@link #getCache(String)}. 44 * <h2>Configuration</h2> 45 * This implementation's backing {@code HazelcastInstance} can be configured in one of three ways: 46 * <ol> 47 * <li>Doing nothing and leveraging default Hazelcast configuration mechanisms</li> 48 * <li>Supplying an already-existing {@code HazelcastInstance}</li> 49 * <li>Supplying a {@link Config} instance and using that to create a new {@code HazelcastInstance}</li> 50 * </ol> 51 * <h3>Default Configuration</h3> 52 * If you simply instantiate a {@code HazelcastCacheManager} and do nothing further, its backing 53 * {@link HazelcastInstance} instance will be created automatically by calling 54 * {@link Hazelcast#newHazelcastInstance(com.hazelcast.config.Config) Hazelcast.newHazelcastInstance(null)}. 55 * <p/> 56 * The null argument instructs Hazelcast to use whatever default configuration mechanism it has at its disposal, 57 * usually a {@code hazelcast.xml} file at the root of the classpath, or if that is not present, the 58 * {@code hazelcast-default.xml} file contained in the Hazelcast {@code .jar} file itself. 59 * <p/> 60 * <h3>An existing {@code HazelcastInstance}</h3> 61 * If you have created a {@code HazelcastInstance} outside of Shiro's knowledge/control, you can simply configure it 62 * to be used by calling {@link #setHazelcastInstance(com.hazelcast.core.HazelcastInstance) setHazelcastInstance}. 63 * <p/> 64 * <h3>A {@link Config} instance</h3> 65 * If you do not want to use the above two options, you can have programmatic control over all of Hazelcast's 66 * configuration by <a href="http://www.hazelcast.com/docs/2.5/manual/multi_html/ch12.html">creating and configuring a 67 * Config instance</a>. 68 * <p/> 69 * Once constructed, you can set it via {@link #setConfig(com.hazelcast.config.Config) setConfig(config)}. This config 70 * instance will be used to acquire a new Hazelcast instance by calling 71 * {@link Hazelcast#newHazelcastInstance(Config) Hazelcast.newHazelcastInstance(config)} 72 * 73 * @see <a href="http://www.hazelcast.com/docs/2.5/manual/multi_html/ch12.html">Hazelcast Configuration Documentation</a> 74 * @since 1.3 75 */ 76 public class HazelcastCacheManager implements CacheManager, Initializable, Destroyable { 77 78 public static final Logger log = LoggerFactory.getLogger(HazelcastCacheManager.class); 79 80 private boolean implicitlyCreated = false; 81 private HazelcastInstance hazelcastInstance; 82 private Config config; 83 84 /** 85 * Returns a {@link MapCache} instance representing the named Hazelcast-managed 86 * {@link com.hazelcast.core.IMap IMap}. The Hazelcast Map is obtained by calling 87 * {@link HazelcastInstance#getMap(String) hazelcastInstance.getMap(name)}. 88 * 89 * @param name the name of the cache to acquire. 90 * @param <K> the type of map key 91 * @param <V> the type of map value 92 * @return a {@link MapCache} instance representing the named Hazelcast-managed {@link com.hazelcast.core.IMap IMap}. 93 * @throws CacheException 94 * @see HazelcastInstance#getMap(String) 95 * @see #ensureHazelcastInstance() 96 * 97 */ 98 public <K, V> Cache<K, V> getCache(String name) throws CacheException { 99 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 }