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.session.mgt.eis; 020 021import org.apache.shiro.session.Session; 022import org.apache.shiro.session.UnknownSessionException; 023 024import java.io.Serializable; 025import java.util.Collection; 026 027 028/** 029 * Data Access Object design pattern specification to enable {@link Session} access to an 030 * EIS (Enterprise Information System). It provides your four typical CRUD methods: 031 * {@link #create}, {@link #readSession(java.io.Serializable)}, {@link #update(org.apache.shiro.session.Session)}, 032 * and {@link #delete(org.apache.shiro.session.Session)}. 033 * <p/> 034 * The remaining {@link #getActiveSessions()} method exists as a support mechanism to pre-emptively orphaned sessions, 035 * typically by {@link org.apache.shiro.session.mgt.ValidatingSessionManager ValidatingSessionManager}s), and should 036 * be as efficient as possible, especially if there are thousands of active sessions. Large scale/high performance 037 * implementations will often return a subset of the total active sessions and perform validation a little more 038 * frequently, rather than return a massive set and infrequently validate. 039 * 040 * @since 0.1 041 */ 042public interface SessionDAO { 043 044 /** 045 * Inserts a new Session record into the underling EIS (e.g. Relational database, file system, persistent cache, 046 * etc, depending on the DAO implementation). 047 * <p/> 048 * After this method is invoked, the {@link org.apache.shiro.session.Session#getId()} 049 * method executed on the argument must return a valid session identifier. That is, the following should 050 * always be true: 051 * <pre> 052 * Serializable id = create( session ); 053 * id.equals( session.getId() ) == true</pre> 054 * <p/> 055 * Implementations are free to throw any exceptions that might occur due to 056 * integrity violation constraints or other EIS related errors. 057 * 058 * @param session the {@link org.apache.shiro.session.Session} object to create in the EIS. 059 * @return the EIS id (e.g. primary key) of the created {@code Session} object. 060 */ 061 Serializable create(Session session); 062 063 /** 064 * Retrieves the session from the EIS uniquely identified by the specified 065 * {@code sessionId}. 066 * 067 * @param sessionId the system-wide unique identifier of the Session object to retrieve from 068 * the EIS. 069 * @return the persisted session in the EIS identified by {@code sessionId}. 070 * @throws UnknownSessionException if there is no EIS record for any session with the 071 * specified {@code sessionId} 072 */ 073 Session readSession(Serializable sessionId) throws UnknownSessionException; 074 075 /** 076 * Updates (persists) data from a previously created Session instance in the EIS identified by 077 * {@code {@link Session#getId() session.getId()}}. This effectively propagates 078 * the data in the argument to the EIS record previously saved. 079 * <p/> 080 * In addition to UnknownSessionException, implementations are free to throw any other 081 * exceptions that might occur due to integrity violation constraints or other EIS related 082 * errors. 083 * 084 * @param session the Session to update 085 * @throws org.apache.shiro.session.UnknownSessionException 086 * if no existing EIS session record exists with the 087 * identifier of {@link Session#getId() session.getSessionId()} 088 */ 089 void update(Session session) throws UnknownSessionException; 090 091 /** 092 * Deletes the associated EIS record of the specified {@code session}. If there never 093 * existed a session EIS record with the identifier of 094 * {@link Session#getId() session.getId()}, then this method does nothing. 095 * 096 * @param session the session to delete. 097 */ 098 void delete(Session session); 099 100 /** 101 * Returns all sessions in the EIS that are considered active, meaning all sessions that 102 * haven't been stopped/expired. This is primarily used to validate potential orphans. 103 * <p/> 104 * If there are no active sessions in the EIS, this method may return an empty collection or {@code null}. 105 * <h4>Performance</h4> 106 * This method should be as efficient as possible, especially in larger systems where there might be 107 * thousands of active sessions. Large scale/high performance 108 * implementations will often return a subset of the total active sessions and perform validation a little more 109 * frequently, rather than return a massive set and validate infrequently. If efficient and possible, it would 110 * make sense to return the oldest unstopped sessions available, ordered by 111 * {@link org.apache.shiro.session.Session#getLastAccessTime() lastAccessTime}. 112 * <h4>Smart Results</h4> 113 * <em>Ideally</em> this method would only return active sessions that the EIS was certain should be invalided. 114 * Typically that is any session that is not stopped and where its lastAccessTimestamp is older than the session 115 * timeout. 116 * <p/> 117 * For example, if sessions were backed by a relational database or SQL-92 'query-able' enterprise cache, you might 118 * return something similar to the results returned by this query (assuming 119 * {@link org.apache.shiro.session.mgt.SimpleSession SimpleSession}s were being stored): 120 * <pre> 121 * select * from sessions s where s.lastAccessTimestamp < ? and s.stopTimestamp is null 122 * </pre> 123 * where the {@code ?} parameter is a date instance equal to 'now' minus the session timeout 124 * (e.g. now - 30 minutes). 125 * 126 * @return a Collection of {@code Session}s that are considered active, or an 127 * empty collection or {@code null} if there are no active sessions. 128 */ 129 Collection<Session> getActiveSessions(); 130}