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.session.mgt.eis; 20 21 import org.apache.shiro.session.Session; 22 import org.apache.shiro.session.UnknownSessionException; 23 24 import java.io.Serializable; 25 import java.util.Collection; 26 27 28 /** 29 * Data Access Object design pattern specification to enable {@link Session} access to an 30 * EIS (Enterprise Information System). It provides your four typical CRUD methods: 31 * {@link #create}, {@link #readSession(java.io.Serializable)}, {@link #update(org.apache.shiro.session.Session)}, 32 * and {@link #delete(org.apache.shiro.session.Session)}. 33 * <p/> 34 * The remaining {@link #getActiveSessions()} method exists as a support mechanism to pre-emptively orphaned sessions, 35 * typically by {@link org.apache.shiro.session.mgt.ValidatingSessionManager ValidatingSessionManager}s), and should 36 * be as efficient as possible, especially if there are thousands of active sessions. Large scale/high performance 37 * implementations will often return a subset of the total active sessions and perform validation a little more 38 * frequently, rather than return a massive set and infrequently validate. 39 * 40 * @since 0.1 41 */ 42 public interface SessionDAO { 43 44 /** 45 * Inserts a new Session record into the underling EIS (e.g. Relational database, file system, persistent cache, 46 * etc, depending on the DAO implementation). 47 * <p/> 48 * After this method is invoked, the {@link org.apache.shiro.session.Session#getId()} 49 * method executed on the argument must return a valid session identifier. That is, the following should 50 * always be true: 51 * <pre> 52 * Serializable id = create( session ); 53 * id.equals( session.getId() ) == true</pre> 54 * <p/> 55 * Implementations are free to throw any exceptions that might occur due to 56 * integrity violation constraints or other EIS related errors. 57 * 58 * @param session the {@link org.apache.shiro.session.Session} object to create in the EIS. 59 * @return the EIS id (e.g. primary key) of the created {@code Session} object. 60 */ 61 Serializable create(Session session); 62 63 /** 64 * Retrieves the session from the EIS uniquely identified by the specified 65 * {@code sessionId}. 66 * 67 * @param sessionId the system-wide unique identifier of the Session object to retrieve from 68 * the EIS. 69 * @return the persisted session in the EIS identified by {@code sessionId}. 70 * @throws UnknownSessionException if there is no EIS record for any session with the 71 * specified {@code sessionId} 72 */ 73 Session readSession(Serializable sessionId) throws UnknownSessionException; 74 75 /** 76 * Updates (persists) data from a previously created Session instance in the EIS identified by 77 * {@code {@link Session#getId() session.getId()}}. This effectively propagates 78 * the data in the argument to the EIS record previously saved. 79 * <p/> 80 * In addition to UnknownSessionException, implementations are free to throw any other 81 * exceptions that might occur due to integrity violation constraints or other EIS related 82 * errors. 83 * 84 * @param session the Session to update 85 * @throws org.apache.shiro.session.UnknownSessionException 86 * if no existing EIS session record exists with the 87 * identifier of {@link Session#getId() session.getSessionId()} 88 */ 89 void update(Session session) throws UnknownSessionException; 90 91 /** 92 * Deletes the associated EIS record of the specified {@code session}. If there never 93 * existed a session EIS record with the identifier of 94 * {@link Session#getId() session.getId()}, then this method does nothing. 95 * 96 * @param session the session to delete. 97 */ 98 void delete(Session session); 99 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 }