1 /*
2 * Copyright 2008 Les Hazlewood
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.apache.shiro.session.mgt;
17
18 import org.apache.shiro.session.InvalidSessionException;
19
20 import java.util.Collection;
21 import java.util.Date;
22
23 /**
24 * A {@code Native} session manager is one that manages sessions natively - that is, it is directly responsible
25 * for the creation, persistence and removal of {@link org.apache.shiro.session.Session Session} instances and their
26 * lifecycles.
27 *
28 * @since 1.0
29 */
30 public interface NativeSessionManager extends SessionManager {
31
32 /**
33 * Returns the time the associated {@code Session} started (was created).
34 *
35 * @param key the session key to use to look up the target session.
36 * @return the time the specified {@code Session} started (was created).
37 * @see org.apache.shiro.session.Session#getStartTimestamp()
38 */
39 Date getStartTimestamp(SessionKey key);
40
41 /**
42 * Returns the time the associated {@code Session} last interacted with the system.
43 *
44 * @param key the session key to use to look up the target session.
45 * @return time the session last accessed the system
46 * @see org.apache.shiro.session.Session#getLastAccessTime()
47 * @see org.apache.shiro.session.Session#touch()
48 */
49 Date getLastAccessTime(SessionKey key);
50
51 /**
52 * Returns {@code true} if the associated session is valid (it exists and is not stopped nor expired),
53 * {@code false} otherwise.
54 *
55 * @param key the session key to use to look up the target session.
56 * @return {@code true} if the session is valid (exists and is not stopped or expired), {@code false} otherwise.
57 */
58 boolean isValid(SessionKey key);
59
60 /**
61 * Returns quietly if the associated session is valid (it exists and is not stopped or expired) or throws
62 * an {@link org.apache.shiro.session.InvalidSessionException} indicating that the session id is invalid. This
63 * might be preferred to be used instead of {@link #isValid} since any exception thrown will definitively explain
64 * the reason for invalidation.
65 *
66 * @param key the session key to use to look up the target session.
67 * @throws org.apache.shiro.session.InvalidSessionException
68 * if the session id is invalid (it does not exist or it is stopped or expired).
69 */
70 void checkValid(SessionKey key) throws InvalidSessionException;
71
72 /**
73 * Returns the time in milliseconds that the associated session may remain idle before expiring.
74 * <ul>
75 * <li>A negative return value means the session will never expire.</li>
76 * <li>A non-negative return value (0 or greater) means the session expiration will occur if idle for that
77 * length of time.</li>
78 * </ul>
79 *
80 * @param key the session key to use to look up the target session.
81 * @return the time in milliseconds that the associated session may remain idle before expiring.
82 * @throws org.apache.shiro.session.InvalidSessionException
83 * if the session has been stopped or expired prior to calling this method.
84 */
85 long getTimeout(SessionKey key) throws InvalidSessionException;
86
87 /**
88 * Sets the time in milliseconds that the associated session may remain idle before expiring.
89 * <ul>
90 * <li>A negative return value means the session will never expire.</li>
91 * <li>A non-negative return value (0 or greater) means the session expiration will occur if idle for that
92 * length of time.</li>
93 * </ul>
94 *
95 * @param key the session key to use to look up the target session.
96 * @param maxIdleTimeInMillis the time in milliseconds that the associated session may remain idle before expiring.
97 * @throws org.apache.shiro.session.InvalidSessionException
98 * if the session has been stopped or expired prior to calling this method.
99 */
100 void setTimeout(SessionKey key, long maxIdleTimeInMillis) throws InvalidSessionException;
101
102 /**
103 * Updates the last accessed time of the session identified by <code>sessionId</code>. This
104 * can be used to explicitly ensure that a session does not time out.
105 *
106 * @param key the session key to use to look up the target session.
107 * @throws org.apache.shiro.session.InvalidSessionException
108 * if the session has been stopped or expired prior to calling this method.
109 * @see org.apache.shiro.session.Session#touch
110 */
111 void touch(SessionKey key) throws InvalidSessionException;
112
113 /**
114 * Returns the host name or IP string of the host where the session was started, if known. If
115 * no host name or IP was specified when starting the session, this method returns {@code null}
116 *
117 * @param key the session key to use to look up the target session.
118 * @return the host name or ip address of the host where the session originated, if known. If unknown,
119 * this method returns {@code null}.
120 */
121 String getHost(SessionKey key);
122
123 /**
124 * Explicitly stops the associated session, thereby releasing all of its resources.
125 *
126 * @param key the session key to use to look up the target session.
127 * @throws InvalidSessionException if the session has stopped or expired prior to calling this method.
128 * @see org.apache.shiro.session.Session#stop
129 */
130 void stop(SessionKey key) throws InvalidSessionException;
131
132 /**
133 * Returns all attribute keys maintained by the target session or an empty collection if there are no attributes.
134 *
135 * @param sessionKey the session key to use to look up the target session.
136 * @return all attribute keys maintained by the target session or an empty collection if there are no attributes.
137 * @throws InvalidSessionException if the associated session has stopped or expired prior to calling this method.
138 * @see org.apache.shiro.session.Session#getAttributeKeys()
139 */
140 Collection<Object> getAttributeKeys(SessionKey sessionKey);
141
142 /**
143 * Returns the object bound to the associated session identified by the specified attribute key. If there
144 * is no object bound under the attribute key for the given session, {@code null} is returned.
145 *
146 * @param sessionKey session key to use to look up the target session.
147 * @param attributeKey the unique name of the object bound to the associated session
148 * @return the object bound under the {@code attributeKey} or {@code null} if there is no object bound.
149 * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
150 * @see org.apache.shiro.session.Session#getAttribute(Object key)
151 */
152 Object getAttribute(SessionKey sessionKey, Object attributeKey) throws InvalidSessionException;
153
154 /**
155 * Binds the specified {@code value} to the associated session uniquely identified by the {@code attributeKey}.
156 * If there is already a session attribute bound under the {@code attributeKey}, that existing object will be
157 * replaced by the new {@code value}.
158 * <p/>
159 * If the {@code value} parameter is null, it has the same effect as if the
160 * {@link #removeAttribute(SessionKey sessionKey, Object attributeKey)} method was called.
161 *
162 * @param sessionKey the session key to use to look up the target session.
163 * @param attributeKey the key under which the {@code value} object will be bound in this session
164 * @param value the object to bind in this session.
165 * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
166 * @see org.apache.shiro.session.Session#setAttribute(Object key, Object value)
167 */
168 void setAttribute(SessionKey sessionKey, Object attributeKey, Object value) throws InvalidSessionException;
169
170 /**
171 * Removes (unbinds) the object bound to associated {@code Session} under the given {@code attributeKey}.
172 *
173 * @param sessionKey session key to use to look up the target session.
174 * @param attributeKey the key uniquely identifying the object to remove
175 * @return the object removed or {@code null} if there was no object bound under the specified {@code attributeKey}.
176 * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
177 * @see org.apache.shiro.session.Session#removeAttribute(Object key)
178 */
179 Object removeAttribute(SessionKey sessionKey, Object attributeKey) throws InvalidSessionException;
180
181 }