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 */ 016package org.apache.shiro.session.mgt; 017 018import org.apache.shiro.session.InvalidSessionException; 019 020import java.util.Collection; 021import 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 * @since 1.0 029 */ 030public interface NativeSessionManager extends SessionManager { 031 032 /** 033 * Returns the time the associated {@code Session} started (was created). 034 * 035 * @param key the session key to use to look up the target session. 036 * @return the time the specified {@code Session} started (was created). 037 * @see org.apache.shiro.session.Session#getStartTimestamp() 038 */ 039 Date getStartTimestamp(SessionKey key); 040 041 /** 042 * Returns the time the associated {@code Session} last interacted with the system. 043 * 044 * @param key the session key to use to look up the target session. 045 * @return time the session last accessed the system 046 * @see org.apache.shiro.session.Session#getLastAccessTime() 047 * @see org.apache.shiro.session.Session#touch() 048 */ 049 Date getLastAccessTime(SessionKey key); 050 051 /** 052 * Returns {@code true} if the associated session is valid (it exists and is not stopped nor expired), 053 * {@code false} otherwise. 054 * 055 * @param key the session key to use to look up the target session. 056 * @return {@code true} if the session is valid (exists and is not stopped or expired), {@code false} otherwise. 057 */ 058 boolean isValid(SessionKey key); 059 060 /** 061 * Returns quietly if the associated session is valid (it exists and is not stopped or expired) or throws 062 * an {@link org.apache.shiro.session.InvalidSessionException} indicating that the session id is invalid. This 063 * might be preferred to be used instead of {@link #isValid} since any exception thrown will definitively explain 064 * the reason for invalidation. 065 * 066 * @param key the session key to use to look up the target session. 067 * @throws org.apache.shiro.session.InvalidSessionException 068 * if the session id is invalid (it does not exist or it is stopped or expired). 069 */ 070 void checkValid(SessionKey key) throws InvalidSessionException; 071 072 /** 073 * Returns the time in milliseconds that the associated session may remain idle before expiring. 074 * <ul> 075 * <li>A negative return value means the session will never expire.</li> 076 * <li>A non-negative return value (0 or greater) means the session expiration will occur if idle for that 077 * length of time.</li> 078 * </ul> 079 * 080 * @param key the session key to use to look up the target session. 081 * @return the time in milliseconds that the associated session may remain idle before expiring. 082 * @throws org.apache.shiro.session.InvalidSessionException 083 * if the session has been stopped or expired prior to calling this method. 084 */ 085 long getTimeout(SessionKey key) throws InvalidSessionException; 086 087 /** 088 * Sets the time in milliseconds that the associated session may remain idle before expiring. 089 * <ul> 090 * <li>A negative return value means the session will never expire.</li> 091 * <li>A non-negative return value (0 or greater) means the session expiration will occur if idle for that 092 * length of time.</li> 093 * </ul> 094 * 095 * @param key the session key to use to look up the target session. 096 * @param maxIdleTimeInMillis the time in milliseconds that the associated session may remain idle before expiring. 097 * @throws org.apache.shiro.session.InvalidSessionException 098 * if the session has been stopped or expired prior to calling this method. 099 */ 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}