001 // Copyright 2006, 2008 The Apache Software Foundation
002 //
003 // Licensed under the Apache License, Version 2.0 (the "License");
004 // you may not use this file except in compliance with the License.
005 // You may obtain a copy of the License at
006 //
007 // http://www.apache.org/licenses/LICENSE-2.0
008 //
009 // Unless required by applicable law or agreed to in writing, software
010 // distributed under the License is distributed on an "AS IS" BASIS,
011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012 // See the License for the specific language governing permissions and
013 // limitations under the License.
014
015 package org.apache.tapestry5.services;
016
017 import javax.servlet.http.HttpSession;
018
019 import org.apache.tapestry5.OptimizedSessionPersistedObject;
020 import org.apache.tapestry5.annotations.ImmutableSessionPersistedObject;
021 import org.apache.tapestry5.internal.services.OptimizedSessionPersistedObjectAnalyzer;
022
023 import java.util.List;
024
025 /**
026 * Generic version of {@link HttpSession}, used to bridge the gaps between the Servlet API and the Portlet API.
027 */
028 public interface Session
029 {
030 /**
031 * Returns a list of the names of all attributes stored in the session. The names are returned sorted
032 * alphabetically.
033 */
034 List<String> getAttributeNames();
035
036 /**
037 * Returns a list of the names of all attributes stored in the session whose name has the provided prefix. The names
038 * are returned in alphabetical order.
039 */
040 List<String> getAttributeNames(String prefix);
041
042 /**
043 * Returns the value previously stored in the session.
044 */
045 Object getAttribute(String name);
046
047 /**
048 * Sets the value of an attribute. If the value is null, then the attribute is deleted.
049 */
050 void setAttribute(String name, Object value);
051
052 /**
053 * Returns the maximum time interval, in seconds, that the servlet container will keep this session open between
054 * client accesses. After this interval, the servlet container will invalidate the session. The maximum time
055 * interval can be set with the setMaxInactiveInterval method. A negative time indicates the session should never
056 * timeout.
057 */
058 int getMaxInactiveInterval();
059
060 /**
061 * Specifies the time, in seconds, between client requests before the servlet container will invalidate this
062 * session. A negative time indicates the session should never timeout.
063 */
064 void setMaxInactiveInterval(int seconds);
065
066 /**
067 * Invalidates this session then unbinds any objects bound to it.
068 *
069 * @throws IllegalStateException
070 * if this method is called on an already invalidated session
071 */
072 void invalidate();
073
074 /**
075 * Checks to see if the session has been invalidated. Note: since 5.3 this will also catch calls to
076 * {@link javax.servlet.http.HttpSession#invalidate()}.
077 *
078 * @since 5.1.0.0
079 */
080 boolean isInvalidated();
081
082 /**
083 * Re-stores dirty objects back into the session. This is necessary to support clustering, because (in most
084 * application servers) session objects are only broadcast around the cluster from setAttribute(). If a mutable
085 * session object is read and changed, those changes will be limited to a single server in the cluster, which can
086 * cause confusing application failures in the event of a failover. Does nothing if there are no changes, or
087 * the session has been invalidated.
088 *
089 * @see OptimizedSessionPersistedObject
090 * @see OptimizedSessionPersistedObjectAnalyzer
091 * @see ImmutableSessionPersistedObject
092 * @since 5.1.0.0
093 */
094 void restoreDirtyObjects();
095 }