View Javadoc

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.realm;
20  
21  import org.apache.shiro.authc.LogoutAware;
22  import org.apache.shiro.cache.CacheManager;
23  import org.apache.shiro.cache.CacheManagerAware;
24  import org.apache.shiro.subject.PrincipalCollection;
25  import org.apache.shiro.util.CollectionUtils;
26  import org.apache.shiro.util.Nameable;
27  import org.slf4j.Logger;
28  import org.slf4j.LoggerFactory;
29  
30  import java.util.Collection;
31  import java.util.concurrent.atomic.AtomicInteger;
32  
33  
34  /**
35   * A very basic abstract extension point for the {@link Realm} interface that provides caching support for subclasses.
36   * <p/>
37   * It also provides a convenience method,
38   * {@link #getAvailablePrincipal(org.apache.shiro.subject.PrincipalCollection)}, which is useful across all
39   * realm subclasses for obtaining a realm-specific principal/identity.
40   * <p/>
41   * All actual Realm method implementations are left to subclasses.
42   *
43   * @see #clearCache(org.apache.shiro.subject.PrincipalCollection)
44   * @see #onLogout(org.apache.shiro.subject.PrincipalCollection)
45   * @see #getAvailablePrincipal(org.apache.shiro.subject.PrincipalCollection)
46   * @since 0.9
47   */
48  public abstract class CachingRealm implements Realm, Nameable, CacheManagerAware, LogoutAware {
49  
50      private static final Logger log = LoggerFactory.getLogger(CachingRealm.class);
51  
52      //TODO - complete JavaDoc
53  
54      private static final AtomicInteger INSTANCE_COUNT = new AtomicInteger();
55  
56      /*--------------------------------------------
57      |    I N S T A N C E   V A R I A B L E S    |
58      ============================================*/
59      private String name;
60      private boolean cachingEnabled;
61      private CacheManager cacheManager;
62  
63      /**
64       * Default no-argument constructor that defaults
65       * {@link #isCachingEnabled() cachingEnabled} (for general caching) to {@code true} and sets a
66       * default {@link #getName() name} based on the class name.
67       * <p/>
68       * Note that while in general, caching may be enabled by default, subclasses have control over
69       * if specific caching is enabled.
70       */
71      public CachingRealm() {
72          this.cachingEnabled = true;
73          this.name = getClass().getName() + "_" + INSTANCE_COUNT.getAndIncrement();
74      }
75  
76      /**
77       * Returns the <tt>CacheManager</tt> used for data caching to reduce EIS round trips, or <tt>null</tt> if
78       * caching is disabled.
79       *
80       * @return the <tt>CacheManager</tt> used for data caching to reduce EIS round trips, or <tt>null</tt> if
81       *         caching is disabled.
82       */
83      public CacheManager getCacheManager() {
84          return this.cacheManager;
85      }
86  
87      /**
88       * Sets the <tt>CacheManager</tt> to be used for data caching to reduce EIS round trips.
89       * <p/>
90       * This property is <tt>null</tt> by default, indicating that caching is turned off.
91       *
92       * @param cacheManager the <tt>CacheManager</tt> to use for data caching, or <tt>null</tt> to disable caching.
93       */
94      public void setCacheManager(CacheManager cacheManager) {
95          this.cacheManager = cacheManager;
96          afterCacheManagerSet();
97      }
98  
99      /**
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 }