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     */
019    package org.apache.shiro.realm;
020    
021    import org.apache.shiro.authc.LogoutAware;
022    import org.apache.shiro.cache.CacheManager;
023    import org.apache.shiro.cache.CacheManagerAware;
024    import org.apache.shiro.subject.PrincipalCollection;
025    import org.apache.shiro.util.CollectionUtils;
026    import org.apache.shiro.util.Nameable;
027    import org.slf4j.Logger;
028    import org.slf4j.LoggerFactory;
029    
030    import java.util.Collection;
031    import 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     */
048    public 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    }