001 /*
002 * Copyright 2008 Les Hazlewood
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.apache.shiro.session.mgt;
017
018 import org.apache.shiro.session.InvalidSessionException;
019
020 import java.util.Collection;
021 import java.util.Date;
022
023 /**
024 * A {@code Native} session manager is one that manages sessions natively - that is, it is directly responsible
025 * for the creation, persistence and removal of {@link org.apache.shiro.session.Session Session} instances and their
026 * lifecycles.
027 *
028 * @author Les Hazlewood
029 * @since 1.0
030 */
031 public interface NativeSessionManager extends SessionManager {
032
033 /**
034 * Returns the time the associated {@code Session} started (was created).
035 *
036 * @param key the session key to use to look up the target session.
037 * @return the time the specified {@code Session} started (was created).
038 * @see org.apache.shiro.session.Session#getStartTimestamp()
039 */
040 Date getStartTimestamp(SessionKey key);
041
042 /**
043 * Returns the time the associated {@code Session} last interacted with the system.
044 *
045 * @param key the session key to use to look up the target session.
046 * @return time the session last accessed the system
047 * @see org.apache.shiro.session.Session#getLastAccessTime()
048 * @see org.apache.shiro.session.Session#touch()
049 */
050 Date getLastAccessTime(SessionKey key);
051
052 /**
053 * Returns {@code true} if the associated session is valid (it exists and is not stopped nor expired),
054 * {@code false} otherwise.
055 *
056 * @param key the session key to use to look up the target session.
057 * @return {@code true} if the session is valid (exists and is not stopped or expired), {@code false} otherwise.
058 */
059 boolean isValid(SessionKey key);
060
061 /**
062 * Returns quietly if the associated session is valid (it exists and is not stopped or expired) or throws
063 * an {@link org.apache.shiro.session.InvalidSessionException} indicating that the session id is invalid. This
064 * might be preferred to be used instead of {@link #isValid} since any exception thrown will definitively explain
065 * the reason for invalidation.
066 *
067 * @param key the session key to use to look up the target session.
068 * @throws org.apache.shiro.session.InvalidSessionException
069 * if the session id is invalid (it does not exist or it is stopped or expired).
070 */
071 void checkValid(SessionKey key) throws InvalidSessionException;
072
073 /**
074 * Returns the time in milliseconds that the associated session may remain idle before expiring.
075 * <ul>
076 * <li>A negative return value means the session will never expire.</li>
077 * <li>A non-negative return value (0 or greater) means the session expiration will occur if idle for that
078 * length of time.</li>
079 * </ul>
080 *
081 * @param key the session key to use to look up the target session.
082 * @return the time in milliseconds that the associated session may remain idle before expiring.
083 * @throws org.apache.shiro.session.InvalidSessionException
084 * if the session has been stopped or expired prior to calling this method.
085 */
086 long getTimeout(SessionKey key) throws InvalidSessionException;
087
088 /**
089 * Sets the time in milliseconds that the associated session may remain idle before expiring.
090 * <ul>
091 * <li>A negative return value means the session will never expire.</li>
092 * <li>A non-negative return value (0 or greater) means the session expiration will occur if idle for that
093 * length of time.</li>
094 * </ul>
095 *
096 * @param key the session key to use to look up the target session.
097 * @param maxIdleTimeInMillis the time in milliseconds that the associated session may remain idle before expiring.
098 * @throws org.apache.shiro.session.InvalidSessionException
099 * if the session has been stopped or expired prior to calling this method.
100 */
101 void setTimeout(SessionKey key, long maxIdleTimeInMillis) throws InvalidSessionException;
102
103 /**
104 * Updates the last accessed time of the session identified by <code>sessionId</code>. This
105 * can be used to explicitly ensure that a session does not time out.
106 *
107 * @param key the session key to use to look up the target session.
108 * @throws org.apache.shiro.session.InvalidSessionException
109 * if the session has been stopped or expired prior to calling this method.
110 * @see org.apache.shiro.session.Session#touch
111 */
112 void touch(SessionKey key) throws InvalidSessionException;
113
114 /**
115 * Returns the host name or IP string of the host where the session was started, if known. If
116 * no host name or IP was specified when starting the session, this method returns {@code null}
117 *
118 * @param key the session key to use to look up the target session.
119 * @return the host name or ip address of the host where the session originated, if known. If unknown,
120 * this method returns {@code null}.
121 */
122 String getHost(SessionKey key);
123
124 /**
125 * Explicitly stops the associated session, thereby releasing all of its resources.
126 *
127 * @param key the session key to use to look up the target session.
128 * @throws InvalidSessionException if the session has stopped or expired prior to calling this method.
129 * @see org.apache.shiro.session.Session#stop
130 */
131 void stop(SessionKey key) throws InvalidSessionException;
132
133 /**
134 * Returns all attribute keys maintained by the target session or an empty collection if there are no attributes.
135 *
136 * @param sessionKey the session key to use to look up the target session.
137 * @return all attribute keys maintained by the target session or an empty collection if there are no attributes.
138 * @throws InvalidSessionException if the associated session has stopped or expired prior to calling this method.
139 * @see org.apache.shiro.session.Session#getAttributeKeys()
140 */
141 Collection<Object> getAttributeKeys(SessionKey sessionKey);
142
143 /**
144 * Returns the object bound to the associated session identified by the specified attribute key. If there
145 * is no object bound under the attribute key for the given session, {@code null} is returned.
146 *
147 * @param sessionKey session key to use to look up the target session.
148 * @param attributeKey the unique name of the object bound to the associated session
149 * @return the object bound under the {@code attributeKey} or {@code null} if there is no object bound.
150 * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
151 * @see org.apache.shiro.session.Session#getAttribute(Object key)
152 */
153 Object getAttribute(SessionKey sessionKey, Object attributeKey) throws InvalidSessionException;
154
155 /**
156 * Binds the specified {@code value} to the associated session uniquely identified by the {@code attributeKey}.
157 * If there is already a session attribute bound under the {@code attributeKey}, that existing object will be
158 * replaced by the new {@code value}.
159 * <p/>
160 * If the {@code value} parameter is null, it has the same effect as if the
161 * {@link #removeAttribute(SessionKey sessionKey, Object attributeKey)} method was called.
162 *
163 * @param sessionKey the session key to use to look up the target session.
164 * @param attributeKey the key under which the {@code value} object will be bound in this session
165 * @param value the object to bind in this session.
166 * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
167 * @see org.apache.shiro.session.Session#setAttribute(Object key, Object value)
168 */
169 void setAttribute(SessionKey sessionKey, Object attributeKey, Object value) throws InvalidSessionException;
170
171 /**
172 * Removes (unbinds) the object bound to associated {@code Session} under the given {@code attributeKey}.
173 *
174 * @param sessionKey session key to use to look up the target session.
175 * @param attributeKey the key uniquely identifying the object to remove
176 * @return the object removed or {@code null} if there was no object bound under the specified {@code attributeKey}.
177 * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
178 * @see org.apache.shiro.session.Session#removeAttribute(Object key)
179 */
180 Object removeAttribute(SessionKey sessionKey, Object attributeKey) throws InvalidSessionException;
181
182 }