    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}