Coverage Report

Coverage Report - org.apache.shiro.session.mgt.NativeSessionManager

Classes in this File

 /*
  * Copyright 2008 Les Hazlewood
  *
  * Licensed 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;
 
 import org.apache.shiro.session.InvalidSessionException;
 
 import java.util.Collection;
 import java.util.Date;
 
 /**
  * A {@code Native} session manager is one that manages sessions natively - that is, it is directly responsible
  * for the creation, persistence and removal of {@link org.apache.shiro.session.Session Session} instances and their
  * lifecycles.
  *
  * @since 1.0
  */
 public interface NativeSessionManager extends SessionManager {
 
     /**
      * Returns the time the associated {@code Session} started (was created).
      *
      * @param key the session key to use to look up the target session.
      * @return the time the specified {@code Session} started (was created).
      * @see org.apache.shiro.session.Session#getStartTimestamp()
      */
     Date getStartTimestamp(SessionKey key);
 
     /**
      * Returns the time the associated {@code Session} last interacted with the system.
      *
      * @param key the session key to use to look up the target session.
      * @return time the session last accessed the system
      * @see org.apache.shiro.session.Session#getLastAccessTime()
      * @see org.apache.shiro.session.Session#touch()
      */
     Date getLastAccessTime(SessionKey key);
 
     /**
      * Returns {@code true} if the associated session is valid (it exists and is not stopped nor expired),
      * {@code false} otherwise.
      *
      * @param key the session key to use to look up the target session.
      * @return {@code true} if the session is valid (exists and is not stopped or expired), {@code false} otherwise.
      */
     boolean isValid(SessionKey key);
 
     /**
      * Returns quietly if the associated session is valid (it exists and is not stopped or expired) or throws
      * an {@link org.apache.shiro.session.InvalidSessionException} indicating that the session id is invalid.  This
      * might be preferred to be used instead of {@link #isValid} since any exception thrown will definitively explain
      * the reason for invalidation.
      *
      * @param key the session key to use to look up the target session.
      * @throws org.apache.shiro.session.InvalidSessionException
      *          if the session id is invalid (it does not exist or it is stopped or expired).
      */
     void checkValid(SessionKey key) throws InvalidSessionException;
 
     /**
      * Returns the time in milliseconds that the associated session may remain idle before expiring.
      * <ul>
      * <li>A negative return value means the session will never expire.</li>
      * <li>A non-negative return value (0 or greater) means the session expiration will occur if idle for that
      * length of time.</li>
      * </ul>
      *
      * @param key the session key to use to look up the target session.
      * @return the time in milliseconds that the associated session may remain idle before expiring.
      * @throws org.apache.shiro.session.InvalidSessionException
      *          if the session has been stopped or expired prior to calling this method.
      */
     long getTimeout(SessionKey key) throws InvalidSessionException;
 
     /**
      * Sets the time in milliseconds that the associated session may remain idle before expiring.
      * <ul>
      * <li>A negative return value means the session will never expire.</li>
      * <li>A non-negative return value (0 or greater) means the session expiration will occur if idle for that
      * length of time.</li>
      * </ul>
      *
      * @param key                 the session key to use to look up the target session.
      * @param maxIdleTimeInMillis the time in milliseconds that the associated session may remain idle before expiring.
      * @throws org.apache.shiro.session.InvalidSessionException
      *          if the session has been stopped or expired prior to calling this method.
      */
     void setTimeout(SessionKey key, long maxIdleTimeInMillis) throws InvalidSessionException;
 
     /**
      * Updates the last accessed time of the session identified by <code>sessionId</code>.  This
      * can be used to explicitly ensure that a session does not time out.
      *
      * @param key the session key to use to look up the target session.
      * @throws org.apache.shiro.session.InvalidSessionException
      *          if the session has been stopped or expired prior to calling this method.
      * @see org.apache.shiro.session.Session#touch
      */
     void touch(SessionKey key) throws InvalidSessionException;
 
     /**
      * Returns the host name or IP string of the host where the session was started, if known.  If
      * no host name or IP was specified when starting the session, this method returns {@code null}
      *
      * @param key the session key to use to look up the target session.
      * @return the host name or ip address of the host where the session originated, if known.  If unknown,
      *         this method returns {@code null}.
      */
     String getHost(SessionKey key);
 
     /**
      * Explicitly stops the associated session, thereby releasing all of its resources.
      *
      * @param key the session key to use to look up the target session.
      * @throws InvalidSessionException if the session has stopped or expired prior to calling this method.
      * @see org.apache.shiro.session.Session#stop
      */
     void stop(SessionKey key) throws InvalidSessionException;
 
     /**
      * Returns all attribute keys maintained by the target session or an empty collection if there are no attributes.
      *
      * @param sessionKey the session key to use to look up the target session.
      * @return all attribute keys maintained by the target session or an empty collection if there are no attributes.
      * @throws InvalidSessionException if the associated session has stopped or expired prior to calling this method.
      * @see org.apache.shiro.session.Session#getAttributeKeys()
      */
     Collection<Object> getAttributeKeys(SessionKey sessionKey);
 
     /**
      * Returns the object bound to the associated session identified by the specified attribute key.  If there
      * is no object bound under the attribute key for the given session, {@code null} is returned.
      *
      * @param sessionKey   session key to use to look up the target session.
      * @param attributeKey the unique name of the object bound to the associated session
      * @return the object bound under the {@code attributeKey} or {@code null} if there is no object bound.
      * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
      * @see org.apache.shiro.session.Session#getAttribute(Object key)
      */
     Object getAttribute(SessionKey sessionKey, Object attributeKey) throws InvalidSessionException;
 
     /**
      * Binds the specified {@code value} to the associated session uniquely identified by the {@code attributeKey}.
      * If there is already a session attribute bound under the {@code attributeKey}, that existing object will be
      * replaced by the new {@code value}.
      * <p/>
      * If the {@code value} parameter is null, it has the same effect as if the
      * {@link #removeAttribute(SessionKey sessionKey, Object attributeKey)} method was called.
      *
      * @param sessionKey   the session key to use to look up the target session.
      * @param attributeKey the key under which the {@code value} object will be bound in this session
      * @param value        the object to bind in this session.
      * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
      * @see org.apache.shiro.session.Session#setAttribute(Object key, Object value)
      */
     void setAttribute(SessionKey sessionKey, Object attributeKey, Object value) throws InvalidSessionException;
 
     /**
      * Removes (unbinds) the object bound to associated {@code Session} under the given {@code attributeKey}.
      *
      * @param sessionKey   session key to use to look up the target session.
      * @param attributeKey the key uniquely identifying the object to remove
      * @return the object removed or {@code null} if there was no object bound under the specified {@code attributeKey}.
      * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
      * @see org.apache.shiro.session.Session#removeAttribute(Object key)
      */
     Object removeAttribute(SessionKey sessionKey, Object attributeKey) throws InvalidSessionException;
 
 }

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		}