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.realm;
020
021import org.apache.shiro.authc.LogoutAware;
022import org.apache.shiro.cache.CacheManager;
023import org.apache.shiro.cache.CacheManagerAware;
024import org.apache.shiro.subject.PrincipalCollection;
025import org.apache.shiro.util.CollectionUtils;
026import org.apache.shiro.lang.util.Nameable;
027import org.slf4j.Logger;
028import org.slf4j.LoggerFactory;
029
030import java.util.Collection;
031import java.util.concurrent.atomic.AtomicInteger;
032
033
034/**
035 * A very basic abstract extension point for the {@link Realm} interface that provides caching support for subclasses.
036 * <p/>
037 * It also provides a convenience method,
038 * {@link #getAvailablePrincipal(org.apache.shiro.subject.PrincipalCollection)}, which is useful across all
039 * realm subclasses for obtaining a realm-specific principal/identity.
040 * <p/>
041 * All actual Realm method implementations are left to subclasses.
042 *
043 * @see #clearCache(org.apache.shiro.subject.PrincipalCollection)
044 * @see #onLogout(org.apache.shiro.subject.PrincipalCollection)
045 * @see #getAvailablePrincipal(org.apache.shiro.subject.PrincipalCollection)
046 * @since 0.9
047 */
048public abstract class CachingRealm implements Realm, Nameable, CacheManagerAware, LogoutAware {
049
050    private static final Logger LOGGER = LoggerFactory.getLogger(CachingRealm.class);
051
052    private static final AtomicInteger INSTANCE_COUNT = new AtomicInteger();
053
054    /*--------------------------------------------
055    |    I N S T A N C E   V A R I A B L E S    |
056    ============================================*/
057    private String name;
058    private boolean cachingEnabled;
059    private CacheManager cacheManager;
060
061    /**
062     * Default no-argument constructor that defaults
063     * {@link #isCachingEnabled() cachingEnabled} (for general caching) to {@code true} and sets a
064     * default {@link #getName() name} based on the class name.
065     * <p/>
066     * Note that while in general, caching may be enabled by default, subclasses have control over
067     * if specific caching is enabled.
068     */
069    public CachingRealm() {
070        this.cachingEnabled = true;
071        this.name = getClass().getName() + "_" + INSTANCE_COUNT.getAndIncrement();
072    }
073
074    /**
075     * Returns the <tt>CacheManager</tt> used for data caching to reduce EIS round trips, or <tt>null</tt> if
076     * caching is disabled.
077     *
078     * @return the <tt>CacheManager</tt> used for data caching to reduce EIS round trips, or <tt>null</tt> if
079     * caching is disabled.
080     */
081    public CacheManager getCacheManager() {
082        return this.cacheManager;
083    }
084
085    /**
086     * Sets the <tt>CacheManager</tt> to be used for data caching to reduce EIS round trips.
087     * <p/>
088     * This property is <tt>null</tt> by default, indicating that caching is turned off.
089     *
090     * @param cacheManager the <tt>CacheManager</tt> to use for data caching, or <tt>null</tt> to disable caching.
091     */
092    public void setCacheManager(CacheManager cacheManager) {
093        this.cacheManager = cacheManager;
094        afterCacheManagerSet();
095    }
096
097    /**
098     * Returns {@code true} if caching should be used if a {@link CacheManager} has been
099     * {@link #setCacheManager(org.apache.shiro.cache.CacheManager) configured}, {@code false} otherwise.
100     * <p/>
101     * The default value is {@code true} since the large majority of Realms will benefit from caching if a CacheManager
102     * has been configured.  However, memory-only realms should set this value to {@code false} since they would
103     * manage account data in memory already lookups would already be as efficient as possible.
104     *
105     * @return {@code true} if caching will be globally enabled if a {@link CacheManager} has been
106     * configured, {@code false} otherwise
107     */
108    public boolean isCachingEnabled() {
109        return cachingEnabled;
110    }
111
112    /**
113     * Sets whether or not caching should be used if a {@link CacheManager} has been
114     * {@link #setCacheManager(org.apache.shiro.cache.CacheManager) configured}.
115     *
116     * @param cachingEnabled whether or not to globally enable caching for this realm.
117     */
118    public void setCachingEnabled(boolean cachingEnabled) {
119        this.cachingEnabled = cachingEnabled;
120    }
121
122    public String getName() {
123        return name;
124    }
125
126    public void setName(String name) {
127        this.name = name;
128    }
129
130    /**
131     * Template method that may be implemented by subclasses should they wish to react to a
132     * {@link CacheManager} instance being set on the realm instance via the
133     * {@link #setCacheManager(org.apache.shiro.cache.CacheManager)} mutator.
134     */
135    protected void afterCacheManagerSet() {
136    }
137
138    /**
139     * If caching is enabled, this will clear any cached data associated with the specified account identity.
140     * Subclasses are free to override for additional behavior, but be sure to call {@code super.onLogout} first.
141     * <p/>
142     * This default implementation merely calls {@link #clearCache(org.apache.shiro.subject.PrincipalCollection)}.
143     *
144     * @param principals the application-specific Subject/user identifier that is logging out.
145     * @see #clearCache(org.apache.shiro.subject.PrincipalCollection)
146     * @see #getAvailablePrincipal(org.apache.shiro.subject.PrincipalCollection)
147     * @since 1.2
148     */
149    public void onLogout(PrincipalCollection principals) {
150        clearCache(principals);
151    }
152
153    private static boolean isEmpty(PrincipalCollection pc) {
154        return pc == null || pc.isEmpty();
155    }
156
157    /**
158     * Clears out any cached data associated with the specified account identity/identities.
159     * <p/>
160     * This implementation will return quietly if the principals argument is null or empty.  Otherwise it delegates
161     * to {@link #doClearCache(org.apache.shiro.subject.PrincipalCollection)}.
162     *
163     * @param principals the principals of the account for which to clear any cached data.
164     * @since 1.2
165     */
166    protected void clearCache(PrincipalCollection principals) {
167        if (!isEmpty(principals)) {
168            doClearCache(principals);
169            LOGGER.trace("Cleared cache entries for account with principals [{}]", principals);
170        }
171    }
172
173    /**
174     * This implementation does nothing - it is a template to be overridden by subclasses if necessary.
175     *
176     * @param principals principals the principals of the account for which to clear any cached data.
177     * @since 1.2
178     */
179    protected void doClearCache(PrincipalCollection principals) {
180    }
181
182    /**
183     * A utility method for subclasses that returns the first available principal of interest to this particular realm.
184     * The heuristic used to acquire the principal is as follows:
185     * <ul>
186     * <li>Attempt to get <em>this particular Realm's</em> 'primary' principal in the {@code PrincipalCollection} via a
187     * <code>principals.{@link PrincipalCollection#fromRealm(String) fromRealm}({@link #getName() getName()})</code>
188     * call.</li>
189     * <li>If the previous call does not result in any principals, attempt to get the overall 'primary' principal
190     * from the PrincipalCollection via {@link org.apache.shiro.subject.PrincipalCollection#getPrimaryPrincipal()}.</li>
191     * <li>If there are no principals from that call (or the PrincipalCollection argument was null to begin with),
192     * return {@code null}</li>
193     * </ul>
194     *
195     * @param principals the PrincipalCollection holding all principals (from all realms) associated with a single Subject.
196     * @return the 'primary' principal attributed to this particular realm, or the fallback 'master' principal if it
197     * exists, or if not {@code null}.
198     * @since 1.2
199     */
200    protected Object getAvailablePrincipal(PrincipalCollection principals) {
201        Object primary = null;
202        if (!isEmpty(principals)) {
203            Collection thisPrincipals = principals.fromRealm(getName());
204            if (!CollectionUtils.isEmpty(thisPrincipals)) {
205                primary = thisPrincipals.iterator().next();
206            } else {
207                //no principals attributed to this particular realm.  Fall back to the 'master' primary:
208                primary = principals.getPrimaryPrincipal();
209            }
210        }
211
212        return primary;
213    }
214}