001// Copyright 2006, 2008, 2020 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
015package org.apache.tapestry5.http.services;
016
017import java.util.List;
018
019import javax.servlet.http.HttpSession;
020
021import org.apache.tapestry5.http.OptimizedSessionPersistedObject;
022import org.apache.tapestry5.http.annotations.ImmutableSessionPersistedObject;
023import org.apache.tapestry5.http.internal.services.OptimizedSessionPersistedObjectAnalyzer;
024
025
026/**
027 * Generic version of {@link HttpSession}, used to bridge the gaps between the Servlet API and the Portlet API.
028 */
029public interface Session
030{
031
032    /**
033     * The type of lock used to access atttributes in the {@link Session}.
034     * <p>
035     * The actual lock-type depends on if a lock is already held by the this thread.
036     *
037     * @since 5.9
038     */
039    public enum LockMode {
040        /**
041         * No lock is supposed to be acquired.
042         */
043        NONE,
044
045        /**
046         * Acquire a shared read-lock.
047         */
048        READ,
049
050        /**
051         * Acquire an exclusive write-lock.
052         */
053        WRITE
054    }
055
056    /**
057     * Returns a list of the names of all attributes stored in the session.
058     * <p>
059     * The names are returned sorted alphabetically.
060     * <p>
061     * By default, a {@code READ} lock is requested.
062     */
063    List<String> getAttributeNames();
064
065    /**
066     * Returns a list of the names of all attributes stored in the session.
067     * <p>
068     * Uses the requested {@link LockMode} to acquire an appropiate lock.
069     *
070     * @param lockMode The requested minimum lock mode. If null, {@code READ} is used.
071     * @return Alphabetically sorted list of all attributes
072     *
073     * @since 5.9
074     */
075    List<String> getAttributeNames(LockMode lockMode);
076
077    /**
078     * Returns a list of the names of all attributes stored in the session whose name has the provided prefix.
079     * <p>
080     * By default, a {@code READ} lock is requested.
081     * 
082     * @param prefix The attribute prefix
083     * @throws NullPointerException if prefix is {@code null}
084     * @return Alphabetically sorted list of attributes matching the prefix
085     */
086    List<String> getAttributeNames(String prefix);
087
088    /**
089     * Returns a list of the names of all attributes stored in the session whose name has the
090     * provided prefix.
091     * <p>
092     * Uses the requested {@link LockMode} to acquire an appropriate lock.
093     *
094     * @param prefix The attribute prefix
095     * @throws NullPointerException if prefix is {@code null}
096     * @return Alphabetically sorted list of attributes matching the prefix
097     * 
098     * @since 5.9
099     */
100    List<String> getAttributeNames(String prefix, Session.LockMode lockMode);
101
102    /**
103     * Returns the value previously stored in the session.
104     * <p>
105     * By default, a {@code WRITE} lock is requested.
106     * 
107     * @param name The name of the attribute
108     * @throws NullPointerException if name is {@code null}
109     */
110    Object getAttribute(String name);
111
112    /**
113     * Returns the value previously stored in the session.
114     * <p>
115     * Uses the requested {@link LockMode} to acquire an appropriate lock.
116     * 
117     * @param name The name of the attribute
118     * @throws NullPointerException if name is {@code null}
119     *
120     * @since 5.9
121     */
122    Object getAttribute(String name, Session.LockMode lockMode);
123
124    /**
125     * Sets the value of an attribute. If the value is {@code null}, then the attribute is deleted.
126     *
127     * @param name The name of the attribute
128     * @param value The new value of the attribute; {@code null} deletes the attribute.
129     * @throws NullPointerException if name is {@code null}
130     */
131    void setAttribute(String name, Object value);
132
133    /**
134     * Checks if the a value is stored in the session with the specified name.
135     * <p>
136     * By default, a {@code READ} lock is requested.
137     *
138     * @param name The name of the attribute
139     * @throws NullPointerException if name is {@code null}
140     *
141     * @since 5.9
142     */
143    boolean containsAttribute(String name);
144
145    /**
146     * Checks if the a value is stored in the session with the specified name.
147     * <p>
148     * Uses the requested {@link LockMode} to acquire an appropriate lock.
149     *
150     * @param name The name of the attribute
151     * @throws NullPointerException if name is {@code null}
152     *
153     * @since 5.9
154     */
155    boolean containsAttribute(String name, Session.LockMode lockMode);
156
157    /**
158     * Returns the maximum time interval, in seconds, that the servlet container will keep this
159     * session open between client accesses.
160     * After this interval, the servlet container will invalidate the session.
161     * <p>
162     * The maximum time interval can be set with the setMaxInactiveInterval method.
163     * <p>
164     * A negative time indicates the session should never timeout.
165     */
166    int getMaxInactiveInterval();
167
168    /**
169     * Specifies the time, in seconds, between client requests before the servlet container will
170     * invalidate this
171     * session.
172     * <p>
173     * A negative time indicates the session should never timeout.
174     */
175    void setMaxInactiveInterval(int seconds);
176
177    /**
178     * Invalidates this session then unbinds any objects bound to it.
179     *
180     * @throws IllegalStateException
181     *             if this method is called on an already invalidated session
182     */
183    void invalidate();
184
185    /**
186     * Checks to see if the session has been invalidated. Note: since 5.3 this will also catch calls to
187     * {@link javax.servlet.http.HttpSession#invalidate()}.
188     * 
189     * @since 5.1.0.0
190     */
191    boolean isInvalidated();
192
193    /**
194     * Re-stores dirty objects back into the session. This is necessary to support clustering, because (in most
195     * application servers) session objects are only broadcast around the cluster from setAttribute(). If a mutable
196     * session object is read and changed, those changes will be limited to a single server in the cluster, which can
197     * cause confusing application failures in the event of a failover. Does nothing if there are no changes, or
198     * the session has been invalidated.
199     *
200     * @see OptimizedSessionPersistedObject
201     * @see OptimizedSessionPersistedObjectAnalyzer
202     * @see ImmutableSessionPersistedObject
203     * @since 5.1.0.0
204     */
205    void restoreDirtyObjects();
206}