    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    }