/*
* 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.session.Session;
import org.apache.shiro.session.UnknownSessionException;
import java.io.Serializable;
import java.util.Collection;
/**
* Data Access Object design pattern specification to enable {@link Session} access to an
* EIS (Enterprise Information System). It provides your four typical CRUD methods:
* {@link #create}, {@link #readSession(java.io.Serializable)}, {@link #update(org.apache.shiro.session.Session)},
* and {@link #delete(org.apache.shiro.session.Session)}.
* <p/>
* The remaining {@link #getActiveSessions()} method exists as a support mechanism to pre-emptively orphaned sessions,
* typically by {@link org.apache.shiro.session.mgt.ValidatingSessionManager ValidatingSessionManager}s), and should
* be as efficient as possible, especially if there are thousands of active sessions. Large scale/high performance
* implementations will often return a subset of the total active sessions and perform validation a little more
* frequently, rather than return a massive set and infrequently validate.
*
* @since 0.1
*/
public interface SessionDAO {
/**
* Inserts a new Session record into the underling EIS (e.g. Relational database, file system, persistent cache,
* etc, depending on the DAO implementation).
* <p/>
* After this method is invoked, the {@link org.apache.shiro.session.Session#getId()}
* method executed on the argument must return a valid session identifier. That is, the following should
* always be true:
* <pre>
* Serializable id = create( session );
* id.equals( session.getId() ) == true</pre>
* <p/>
* Implementations are free to throw any exceptions that might occur due to
* integrity violation constraints or other EIS related errors.
*
* @param session the {@link org.apache.shiro.session.Session} object to create in the EIS.
* @return the EIS id (e.g. primary key) of the created {@code Session} object.
*/
Serializable create(Session session);
/**
* Retrieves the session from the EIS uniquely identified by the specified
* {@code sessionId}.
*
* @param sessionId the system-wide unique identifier of the Session object to retrieve from
* the EIS.
* @return the persisted session in the EIS identified by {@code sessionId}.
* @throws UnknownSessionException if there is no EIS record for any session with the
* specified {@code sessionId}
*/
Session readSession(Serializable sessionId) throws UnknownSessionException;
/**
* Updates (persists) data from a previously created Session instance in the EIS identified by
* {@code {@link Session#getId() session.getId()}}. This effectively propagates
* the data in the argument to the EIS record previously saved.
* <p/>
* In addition to UnknownSessionException, implementations are free to throw any other
* exceptions that might occur due to integrity violation constraints or other EIS related
* errors.
*
* @param session the Session to update
* @throws org.apache.shiro.session.UnknownSessionException
* if no existing EIS session record exists with the
* identifier of {@link Session#getId() session.getSessionId()}
*/
void update(Session session) throws UnknownSessionException;
/**
* Deletes the associated EIS record of the specified {@code session}. If there never
* existed a session EIS record with the identifier of
* {@link Session#getId() session.getId()}, then this method does nothing.
*
* @param session the session to delete.
*/
void delete(Session session);
/**
* Returns all sessions in the EIS that are considered active, meaning all sessions that
* haven't been stopped/expired. This is primarily used to validate potential orphans.
* <p/>
* If there are no active sessions in the EIS, this method may return an empty collection or {@code null}.
* <h4>Performance</h4>
* This method should be as efficient as possible, especially in larger systems where there might be
* thousands of active sessions. Large scale/high performance
* implementations will often return a subset of the total active sessions and perform validation a little more
* frequently, rather than return a massive set and validate infrequently. If efficient and possible, it would
* make sense to return the oldest unstopped sessions available, ordered by
* {@link org.apache.shiro.session.Session#getLastAccessTime() lastAccessTime}.
* <h4>Smart Results</h4>
* <em>Ideally</em> this method would only return active sessions that the EIS was certain should be invalided.
* Typically that is any session that is not stopped and where its lastAccessTimestamp is older than the session
* timeout.
* <p/>
* For example, if sessions were backed by a relational database or SQL-92 'query-able' enterprise cache, you might
* return something similar to the results returned by this query (assuming
* {@link org.apache.shiro.session.mgt.SimpleSession SimpleSession}s were being stored):
* <pre>
* select * from sessions s where s.lastAccessTimestamp < ? and s.stopTimestamp is null
* </pre>
* where the {@code ?} parameter is a date instance equal to 'now' minus the session timeout
* (e.g. now - 30 minutes).
*
* @return a Collection of {@code Session}s that are considered active, or an
* empty collection or {@code null} if there are no active sessions.
*/
Collection<Session> getActiveSessions();
}