hunt.shiro.session.mgt.eis.SessionDAO source code

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 module hunt.shiro.session.mgt.eis.SessionDAO;
20 
21 import hunt.shiro.session.Session;
22 import hunt.shiro.Exceptions;
23 
24 import hunt.util.Common;
25 import hunt.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(hunt.shiro.session.Session)},
32  * and {@link #remove(hunt.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 hunt.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  */
41 interface SessionDAO {
42 
43     /**
44      * Inserts a new Session record into the underling EIS (e.g. Relational database, file system, persistent cache,
45      * etc, depending on the DAO implementation).
46      * <p/>
47      * After this method is invoked, the {@link hunt.shiro.session.Session#getId()}
48      * method executed on the argument must return a valid session identifier.  That is, the following should
49      * always be true:
50      * <pre>
51      * Serializable id = create( session );
52      * id.equals( session.getId() ) == true</pre>
53      * <p/>
54      * Implementations are free to throw any exceptions that might occur due to
55      * integrity violation constraints or other EIS related errors.
56      *
57      * @param session the {@link hunt.shiro.session.Session} object to create in the EIS.
58      * @return the EIS id (e.g. primary key) of the created {@code Session} object.
59      */
60     string create(Session session);
61 
62     /**
63      * Retrieves the session from the EIS uniquely identified by the specified
64      * {@code sessionId}.
65      *
66      * @param sessionId the system-wide unique identifier of the Session object to retrieve from
67      *                  the EIS.
68      * @return the persisted session in the EIS identified by {@code sessionId}.
69      * @throws UnknownSessionException if there is no EIS record for any session with the
70      *                                 specified {@code sessionId}
71      */
72     Session readSession(string sessionId);
73 
74     /**
75      * Updates (persists) data from a previously created Session instance in the EIS identified by
76      * {@code {@link Session#getId() session.getId()}}.  This effectively propagates
77      * the data in the argument to the EIS record previously saved.
78      * <p/>
79      * In addition to UnknownSessionException, implementations are free to throw any other
80      * exceptions that might occur due to integrity violation constraints or other EIS related
81      * errors.
82      *
83      * @param session the Session to update
84      * @throws hunt.shiro.session.UnknownSessionException
85      *          if no existing EIS session record exists with the
86      *          identifier of {@link Session#getId() session.getSessionId()}
87      */
88     void update(Session session);
89 
90     /**
91      * Deletes the associated EIS record of the specified {@code session}.  If there never
92      * existed a session EIS record with the identifier of
93      * {@link Session#getId() session.getId()}, then this method does nothing.
94      *
95      * @param session the session to remove.
96      */
97     void remove(Session session);
98 
99     /**
100      * Returns all sessions in the EIS that are considered active, meaning all sessions that
101      * haven't been stopped/expired.  This is primarily used to validate potential orphans.
102      * <p/>
103      * If there are no active sessions in the EIS, this method may return an empty collection or {@code null}.
104      * <h4>Performance</h4>
105      * This method should be as efficient as possible, especially in larger systems where there might be
106      * thousands of active sessions.  Large scale/high performance
107      * implementations will often return a subset of the total active sessions and perform validation a little more
108      * frequently, rather than return a massive set and validate infrequently.  If efficient and possible, it would
109      * make sense to return the oldest unstopped sessions available, ordered by
110      * {@link hunt.shiro.session.Session#getLastAccessTime() lastAccessTime}.
111      * <h4>Smart Results</h4>
112      * <em>Ideally</em> this method would only return active sessions that the EIS was certain should be invalided.
113      * Typically that is any session that is not stopped and where its lastAccessTimestamp is older than the session
114      * timeout.
115      * <p/>
116      * For example, if sessions were backed by a relational database or SQL-92 'query-able' enterprise cache, you might
117      * return something similar to the results returned by this query (assuming
118      * {@link hunt.shiro.session.mgt.SimpleSession SimpleSession}s were being stored):
119      * <pre>
120      * select * from sessions s where s.lastAccessTimestamp < ? and s.stopTimestamp is null
121      * </pre>
122      * where the {@code ?} parameter is a date instance equal to 'now' minus the session timeout
123      * (e.g. now - 30 minutes).
124      *
125      * @return a Collection of {@code Session}s that are considered active, or an
126      *         empty collection or {@code null} if there are no active sessions.
127      */
128     Session[] getActiveSessions();
129 }