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}