Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you 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; import java.io.Serializable; import java.util.Collection; import java.util.Date; /** * A {@code Session} is a stateful data context associated with a single Subject (user, daemon process, * etc) who interacts with a software system over a period of time. * <p/> * A {@code Session} is intended to be managed by the business tier and accessible via other * tiers without being tied to any given client technology. This is a <em>great</em> benefit to Java * systems, since until now, the only viable session mechanisms were the * {@code javax.servlet.http.HttpSession} or Stateful Session EJB's, which many times * unnecessarily coupled applications to web or ejb technologies. * * @since 0.1 */ public interface Session { /** * Returns the unique identifier assigned by the system upon session creation. * <p/> * All return values from this method are expected to have proper {@code toString()}, * {@code equals()}, and {@code hashCode()} implementations. Good candidates for such * an identifier are {@link java.util.UUID UUID}s, {@link java.lang.Integer Integer}s, and * {@link java.lang.String String}s. * * @return The unique identifier assigned to the session upon creation. */ Serializable getId(); /** * Returns the time the session was started; that is, the time the system created the instance. * * @return The time the system created the session. */ Date getStartTimestamp(); /** * Returns the last time the application received a request or method invocation from the user associated * with this session. Application calls to this method do not affect this access time. * * @return The time the user last interacted with the system. * @see #touch() */ Date getLastAccessTime(); /** * Returns the time in milliseconds that the session 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> * <b>*Note:</b> if you are used to the {@code HttpSession}'s {@code getMaxInactiveInterval()} method, the scale on * this method is different: Shiro Sessions use millisecond values for timeout whereas * {@code HttpSession.getMaxInactiveInterval} uses seconds. Always use millisecond values with Shiro sessions. * * @return the time in milliseconds the session may remain idle before expiring. * @throws InvalidSessionException if the session has been stopped or expired prior to calling this method. * @since 0.2 */ long getTimeout() throws InvalidSessionException; /** * Sets the time in milliseconds that the session may remain idle before expiring. * <ul> * <li>A negative value means the session will never expire.</li> * <li>A non-negative value (0 or greater) means the session expiration will occur if idle for that * length of time.</li> * </ul> * <p/> * <b>*Note:</b> if you are used to the {@code HttpSession}'s {@code getMaxInactiveInterval()} method, the scale on * this method is different: Shiro Sessions use millisecond values for timeout whereas * {@code HttpSession.getMaxInactiveInterval} uses seconds. Always use millisecond values with Shiro sessions. * * @param maxIdleTimeInMillis the time in milliseconds that the session may remain idle before expiring. * @throws InvalidSessionException if the session has been stopped or expired prior to calling this method. * @since 0.2 */ void setTimeout(long maxIdleTimeInMillis) throws InvalidSessionException; /** * Returns the host name or IP string of the host that originated this session, or {@code null} * if the host is unknown. * * @return the host name or IP string of the host that originated this session, or {@code null} * if the host address is unknown. */ String getHost(); /** * Explicitly updates the {@link #getLastAccessTime() lastAccessTime} of this session to the current time when * this method is invoked. This method can be used to ensure a session does not time out. * <p/> * Most programmers won't use this method directly and will instead rely on the last access time to be updated * automatically as a result of an incoming web request or remote procedure call/method invocation. * <p/> * However, this method is particularly useful when supporting rich-client applications such as * Java Web Start app, Java or Flash applets, etc. Although rare, it is possible in a rich-client * environment that a user continuously interacts with the client-side application without a * server-side method call ever being invoked. If this happens over a long enough period of * time, the user's server-side session could time-out. Again, such cases are rare since most * rich-clients frequently require server-side method invocations. * <p/> * In this example though, the user's session might still be considered valid because * the user is actively "using" the application, just not communicating with the * server. But because no server-side method calls are invoked, there is no way for the server * to know if the user is sitting idle or not, so it must assume so to maintain session * integrity. This {@code touch()} method could be invoked by the rich-client application code during those * times to ensure that the next time a server-side method is invoked, the invocation will not * throw an {@link ExpiredSessionException ExpiredSessionException}. In short terms, it could be used periodically * to ensure a session does not time out. * <p/> * How often this rich-client "maintenance" might occur is entirely dependent upon * the application and would be based on variables such as session timeout configuration, * usage characteristics of the client application, network utilization and application server * performance. * * @throws InvalidSessionException if this session has stopped or expired prior to calling this method. */ void touch() throws InvalidSessionException; /** * Explicitly stops (invalidates) this session and releases all associated resources. * <p/> * If this session has already been authenticated (i.e. the {@code Subject} that * owns this session has logged-in), calling this method explicitly might have undesired side effects: * <p/> * It is common for a {@code Subject} implementation to retain authentication state in the * {@code Session}. If the session * is explicitly stopped by application code by calling this method directly, it could clear out any * authentication state that might exist, thereby effectively "unauthenticating" the {@code Subject}. * <p/> * As such, you might consider {@link org.apache.shiro.subject.Subject#logout logging-out} the 'owning' * {@code Subject} instead of manually calling this method, as a log out is expected to stop the * corresponding session automatically, and also allows framework code to execute additional cleanup logic. * * @throws InvalidSessionException if this session has stopped or expired prior to calling this method. */ void stop() throws InvalidSessionException; /** * Returns the keys of all the attributes stored under this session. If there are no * attributes, this returns an empty collection. * * @return the keys of all attributes stored under this session, or an empty collection if * there are no session attributes. * @throws InvalidSessionException if this session has stopped or expired prior to calling this method. * @since 0.2 */ Collection<Object> getAttributeKeys() throws InvalidSessionException; /** * Returns the object bound to this session identified by the specified key. If there is no * object bound under the key, {@code null} is returned. * * @param key the unique name of the object bound to this session * @return the object bound under the specified {@code key} name or {@code null} if there is * no object bound under that name. * @throws InvalidSessionException if this session has stopped or expired prior to calling * this method. */ Object getAttribute(Object key) throws InvalidSessionException; /** * Binds the specified {@code value} to this session, uniquely identified by the specified * {@code key} name. If there is already an object bound under the {@code key} name, 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 * {@link #removeAttribute(Object) removeAttribute} was called. * * @param key the name under which the {@code value} object will be bound in this session * @param value the object to bind in this session. * @throws InvalidSessionException if this session has stopped or expired prior to calling * this method. */ void setAttribute(Object key, Object value) throws InvalidSessionException; /** * Removes (unbinds) the object bound to this session under the specified {@code key} name. * * @param key the name uniquely identifying the object to remove * @return the object removed or {@code null} if there was no object bound under the name * {@code key}. * @throws InvalidSessionException if this session has stopped or expired prior to calling * this method. */ Object removeAttribute(Object key) throws InvalidSessionException; }