core/src/main/java/org/apache/shiro/session/mgt/eis/CachingSessionDAO.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.shiro.session.mgt.eis;

import org.apache.shiro.cache.Cache;
import org.apache.shiro.cache.CacheManager;
import org.apache.shiro.cache.CacheManagerAware;
import org.apache.shiro.session.Session;
import org.apache.shiro.session.UnknownSessionException;
import org.apache.shiro.session.mgt.ValidatingSession;

import java.io.Serializable;
import java.util.Collection;
import java.util.Collections;

/**
 * An CachingSessionDAO is a SessionDAO that provides a transparent caching layer between the components that
 * use it and the underlying EIS (Enterprise Information System) session backing store (for example, filesystem,
 * database, enterprise grid/cloud, etc.).
 * <p/>
 * This implementation caches all active sessions in a configured
 * {@link #getActiveSessionsCache() activeSessionsCache}.  This property is {@code null} by default and if one is
 * not explicitly set, a {@link #setCacheManager cacheManager} is expected to be configured which will in turn be used
 * to acquire the {@code Cache} instance to use for the {@code activeSessionsCache}.
 * <p/>
 * All {@code SessionDAO} methods are implemented by this class to employ
 * caching behavior and delegates the actual EIS operations to respective do* methods to be implemented by
 * subclasses (doCreate, doRead, etc.).
 *
 * @since 0.2
 */
public abstract class CachingSessionDAO extends AbstractSessionDAO implements CacheManagerAware {

    /**
     * The default active sessions cache name, equal to {@code shiro-activeSessionCache}.
     */
    public static final String ACTIVE_SESSION_CACHE_NAME = "shiro-activeSessionCache";

    /**
     * The CacheManager to use to acquire the Session cache.
     */
    private CacheManager cacheManager;

    /**
     * The Cache instance responsible for caching Sessions.
     */
    private Cache<Serializable, Session> activeSessions;

    /**
     * The name of the session cache, defaults to {@link #ACTIVE_SESSION_CACHE_NAME}.
     */
    private String activeSessionsCacheName = ACTIVE_SESSION_CACHE_NAME;

    /**
     * Default no-arg constructor.
     */
    public CachingSessionDAO() {
    }

    /**
     * Sets the cacheManager to use for acquiring the {@link #getActiveSessionsCache() activeSessionsCache} if
     * one is not configured.
     *
     * @param cacheManager the manager to use for constructing the session cache.
     */
    public void setCacheManager(CacheManager cacheManager) {
        this.cacheManager = cacheManager;
    }

    /**
     * Returns the CacheManager to use for acquiring the {@link #getActiveSessionsCache() activeSessionsCache} if
     * one is not configured.  That is, the {@code CacheManager} will only be used if the
     * {@link #getActiveSessionsCache() activeSessionsCache} property is {@code null}.
     *
     * @return the CacheManager used by the implementation that creates the activeSessions Cache.
     */
    public CacheManager getCacheManager() {
        return cacheManager;
    }

    /**
     * Returns the name of the actives sessions cache to be returned by the {@code CacheManager}.  Unless
     * overridden by {@link #setActiveSessionsCacheName(String)}, defaults to {@link #ACTIVE_SESSION_CACHE_NAME}.
     *
     * @return the name of the active sessions cache.
     */
    public String getActiveSessionsCacheName() {
        return activeSessionsCacheName;
    }

    /**
     * Sets the name of the active sessions cache to be returned by the {@code CacheManager}.  Defaults to
     * {@link #ACTIVE_SESSION_CACHE_NAME}.
     *
     * @param activeSessionsCacheName the name of the active sessions cache to be returned by the {@code CacheManager}.
     */
    public void setActiveSessionsCacheName(String activeSessionsCacheName) {
        this.activeSessionsCacheName = activeSessionsCacheName;
    }

    /**
     * Returns the cache instance to use for storing active sessions.  If one is not available (it is {@code null}),
     * it will be {@link CacheManager#getCache(String) acquired} from the {@link #setCacheManager configured}
     * {@code CacheManager} using the {@link #getActiveSessionsCacheName() activeSessionsCacheName}.
     *
     * @return the cache instance to use for storing active sessions or {@code null} if the {@code Cache} instance
     *         should be retrieved from the
     */
    public Cache<Serializable, Session> getActiveSessionsCache() {
        return this.activeSessions;
    }

    /**
     * Sets the cache instance to use for storing active sessions.  If one is not set (it remains {@code null}),
     * it will be {@link CacheManager#getCache(String) acquired} from the {@link #setCacheManager configured}
     * {@code CacheManager} using the {@link #getActiveSessionsCacheName() activeSessionsCacheName}.
     *
     * @param cache the cache instance to use for storing active sessions or {@code null} if the cache is to be
     *              acquired from the {@link #setCacheManager configured} {@code CacheManager}.
     */
    public void setActiveSessionsCache(Cache<Serializable, Session> cache) {
        this.activeSessions = cache;
    }

    /**
     * Returns the active sessions cache, but if that cache instance is null, first lazily creates the cache instance
     * via the {@link #createActiveSessionsCache()} method and then returns the instance.
     * <p/>
     * Note that this method will only return a non-null value code if the {@code CacheManager} has been set.  If
     * not set, there will be no cache.
     *
     * @return the active sessions cache instance.
     */
    private Cache<Serializable, Session> getActiveSessionsCacheLazy() {
        if (this.activeSessions == null) {
            this.activeSessions = createActiveSessionsCache();
        }
        return activeSessions;
    }

    /**
     * Creates a cache instance used to store active sessions.  Creation is done by first
     * {@link #getCacheManager() acquiring} the {@code CacheManager}.  If the cache manager is not null, the
     * cache returned is that resulting from the following call:
     * <pre>       String name = {@link #getActiveSessionsCacheName() getActiveSessionsCacheName()};
     * cacheManager.getCache(name);</pre>
     *
     * @return a cache instance used to store active sessions, or {@code null} if the {@code CacheManager} has
     *         not been set.
     */
    protected Cache<Serializable, Session> createActiveSessionsCache() {
        Cache<Serializable, Session> cache = null;
        CacheManager mgr = getCacheManager();
        if (mgr != null) {
            String name = getActiveSessionsCacheName();
            cache = mgr.getCache(name);
        }
        return cache;
    }

    /**
     * Calls {@code super.create(session)}, then caches the session keyed by the returned {@code sessionId}, and then
     * returns this {@code sessionId}.
     *
     * @param session Session object to create in the EIS and then cache.
     */
    public Serializable create(Session session) {
        Serializable sessionId = super.create(session);
        cache(session, sessionId);
        return sessionId;
    }

    /**
     * Returns the cached session with the corresponding {@code sessionId} or {@code null} if there is
     * no session cached under that id (or if there is no Cache).
     *
     * @param sessionId the id of the cached session to acquire.
     * @return the cached session with the corresponding {@code sessionId}, or {@code null} if the session
     *         does not exist or is not cached.
     */
    protected Session getCachedSession(Serializable sessionId) {
        Session cached = null;
        if (sessionId != null) {
            Cache<Serializable, Session> cache = getActiveSessionsCacheLazy();
            if (cache != null) {
                cached = getCachedSession(sessionId, cache);
            }
        }
        return cached;
    }

    /**
     * Returns the Session with the specified id from the specified cache.  This method simply calls
     * {@code cache.get(sessionId)} and can be overridden by subclasses for custom acquisition behavior.
     *
     * @param sessionId the id of the session to acquire.
     * @param cache     the cache to acquire the session from
     * @return the cached session, or {@code null} if the session wasn't in the cache.
     */
    protected Session getCachedSession(Serializable sessionId, Cache<Serializable, Session> cache) {
        return cache.get(sessionId);
    }

    /**
     * Caches the specified session under the cache entry key of {@code sessionId}.
     *
     * @param session   the session to cache
     * @param sessionId the session id, to be used as the cache entry key.
     * @since 1.0
     */
    protected void cache(Session session, Serializable sessionId) {
        if (session == null || sessionId == null) {
            return;
        }
        Cache<Serializable, Session> cache = getActiveSessionsCacheLazy();
        if (cache == null) {
            return;
        }
        cache(session, sessionId, cache);
    }

    /**
     * Caches the specified session in the given cache under the key of {@code sessionId}.  This implementation
     * simply calls {@code cache.put(sessionId,session)} and can be overridden for custom behavior.
     *
     * @param session   the session to cache
     * @param sessionId the id of the session, expected to be the cache key.
     * @param cache     the cache to store the session
     */
    protected void cache(Session session, Serializable sessionId, Cache<Serializable, Session> cache) {
        cache.put(sessionId, session);
    }

    /**
     * Attempts to acquire the Session from the cache first using the session ID as the cache key.  If no session
     * is found, {@code super.readSession(sessionId)} is called to perform the actual retrieval.
     *
     * @param sessionId the id of the session to retrieve from the EIS.
     * @return the session identified by {@code sessionId} in the EIS.
     * @throws UnknownSessionException if the id specified does not correspond to any session in the cache or EIS.
     */
    public Session readSession(Serializable sessionId) throws UnknownSessionException {
        Session s = getCachedSession(sessionId);
        if (s == null) {
            s = super.readSession(sessionId);
        }
        return s;
    }

    /**
     * Updates the state of the given session to the EIS by first delegating to
     * {@link #doUpdate(org.apache.shiro.session.Session)}.  If the session is a {@link ValidatingSession}, it will
     * be added to the cache only if it is {@link ValidatingSession#isValid()} and if invalid, will be removed from the
     * cache.  If it is not a {@code ValidatingSession} instance, it will be added to the cache in any event.
     *
     * @param session the session object to update in the EIS.
     * @throws UnknownSessionException if no existing EIS session record exists with the
     *                                 identifier of {@link Session#getId() session.getId()}
     */
    public void update(Session session) throws UnknownSessionException {
        doUpdate(session);
        if (session instanceof ValidatingSession) {
            if (((ValidatingSession) session).isValid()) {
                cache(session, session.getId());
            } else {
                uncache(session);
            }
        } else {
            cache(session, session.getId());
        }
    }

    /**
     * Subclass implementation hook to actually persist the {@code Session}'s state to the underlying EIS.
     *
     * @param session the session object whose state will be propagated to the EIS.
     */
    protected abstract void doUpdate(Session session);

    /**
     * Removes the specified session from any cache and then permanently deletes the session from the EIS by
     * delegating to {@link #doDelete}.
     *
     * @param session the session to remove from caches and permanently delete from the EIS.
     */
    public void delete(Session session) {
        uncache(session);
        doDelete(session);
    }

    /**
     * Subclass implementation hook to permanently delete the given Session from the underlying EIS.
     *
     * @param session the session instance to permanently delete from the EIS.
     */
    protected abstract void doDelete(Session session);

    /**
     * Removes the specified Session from the cache.
     *
     * @param session the session to remove from the cache.
     */
    protected void uncache(Session session) {
        if (session == null) {
            return;
        }
        Serializable id = session.getId();
        if (id == null) {
            return;
        }
        Cache<Serializable, Session> cache = getActiveSessionsCacheLazy();
        if (cache != null) {
            cache.remove(id);
        }
    }

    /**
     * Returns all active sessions in the system.
     * <p/>
     * <p>This implementation merely returns the sessions found in the activeSessions cache.  Subclass implementations
     * may wish to override this method to retrieve them in a different way, perhaps by an RDBMS query or by other
     * means.
     *
     * @return the sessions found in the activeSessions cache.
     */
    public Collection<Session> getActiveSessions() {
        Cache<Serializable, Session> cache = getActiveSessionsCacheLazy();
        if (cache != null) {
            return cache.values();
        } else {
            return Collections.emptySet();
        }
    }
}