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