001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.session;
018
019import java.io.Serializable;
020import java.util.List;
021import java.util.Set;
022
023import javax.servlet.http.HttpSession;
024
025import org.apache.wicket.Session;
026import org.apache.wicket.request.Request;
027
028
029/**
030 * The actual store that is used by {@link org.apache.wicket.Session} to store its attributes.
031 * <p>
032 * This class is intended for internal framework use.
033 * 
034 * @author Eelco Hillenius
035 * @author Johan Compagner
036 * @author Matej Knopp
037 */
038public interface ISessionStore
039{
040        /**
041         * Gets the attribute value with the given name
042         * 
043         * @param request
044         *            the current request
045         * @param name
046         *            The name of the attribute to store
047         * @return The value of the attribute
048         */
049        Serializable getAttribute(Request request, String name);
050
051        /**
052         * @param request
053         *            the current request
054         * 
055         * @return List of attributes for this session
056         */
057        List<String> getAttributeNames(Request request);
058
059        /**
060         * Adds or replaces the attribute with the given name and value.
061         * 
062         * @param request
063         *            the current request
064         * @param name
065         *            the name of the attribute
066         * @param value
067         *            the value of the attribute
068         */
069        void setAttribute(Request request, String name, Serializable value);
070
071        /**
072         * Removes the attribute with the given name.
073         * 
074         * @param request
075         *            the current request
076         * @param name
077         *            the name of the attribute to remove
078         */
079        void removeAttribute(Request request, String name);
080
081        /**
082         * Invalidates the session.
083         * 
084         * @param request
085         *            the current request
086         */
087        void invalidate(Request request);
088
089        /**
090         * Get the session id for the provided request. If create is false and the creation of the
091         * actual session is deferred, this method should return null to reflect it doesn't have one.
092         * 
093         * @param request
094         *            The request
095         * @param create
096         *            Whether to create an actual session (typically an instance of {@link HttpSession})
097         *            when not already done so
098         * @return The session id for the provided request, possibly null if create is false and the
099         *         creation of the actual session was deferred
100         */
101        String getSessionId(Request request, boolean create);
102
103        /**
104         * Retrieves the session for the provided request from this facade.
105         * <p>
106         * This method should return null if it is not bound yet, so that Wicket can recognize that it
107         * should create a session and call {@link #bind(Request, Session)} right after that.
108         * </p>
109         * 
110         * @param request
111         *            The current request
112         * @return The session for the provided request or null if the session was not bound
113         */
114        Session lookup(Request request);
115
116        /**
117         * Adds the provided new session to this facade using the provided request.
118         * 
119         * @param request
120         *            The request that triggered making a new session
121         * @param newSession
122         *            The new session
123         */
124        void bind(Request request, Session newSession);
125
126
127        /**
128         * Flushes the session. Flushing the session generally means setting the attribute with the
129         * value of the current session. Some servlet containers use the setAttribute() as a signal that
130         * the value is dirty and needs to be replicated. Essentially this call comes down to:
131         * 
132         * <code>
133         * String attr=getSessionAttributeName();
134         * Session session=getAttribute(attr);
135         * setAttribute(attr, session);
136         * </code>
137         * 
138         * If the session is not yet bound it will be.
139         * 
140         * @param request
141         *            current request
142         * @param session
143         *            session to be flushed
144         */
145        void flushSession(Request request, Session session);
146
147        /**
148         * Called when the WebApplication is destroyed.
149         */
150        void destroy();
151
152        /**
153         * Listener invoked when session is unbound.
154         */
155        interface UnboundListener
156        {
157                /**
158                 * Informs the listener that session with specific id has been unbound.
159                 * 
160                 * @param sessionId
161                 */
162                void sessionUnbound(String sessionId);
163        }
164
165        /**
166         * Registers listener invoked when session is unbound.
167         * 
168         * @param listener
169         */
170        void registerUnboundListener(UnboundListener listener);
171
172        /**
173         * Unregisters listener invoked when session is unbound.
174         * 
175         * @param listener
176         */
177        void unregisterUnboundListener(UnboundListener listener);
178
179        /**
180         * @return The list of registered unbound listeners
181         */
182        Set<UnboundListener> getUnboundListener();
183
184        /**
185         * Listener invoked when session is bound.
186         */
187        interface BindListener
188        {
189                /**
190                 * Informs the listener that a session is about to be bound. Note that this method is also
191                 * called for {@link Session#isTemporary() temporary sessions}.
192                 * 
193                 * @param request
194                 *            The request the session is bound in
195                 * @param newSession
196                 *            The session that will be bound
197                 */
198                void bindingSession(Request request, Session newSession);
199        }
200
201        /**
202         * Registers listener invoked when session is bound.
203         * 
204         * @param listener
205         */
206        void registerBindListener(BindListener listener);
207
208        /**
209         * Unregisters listener invoked when session is bound.
210         * 
211         * @param listener
212         */
213        void unregisterBindListener(BindListener listener);
214
215        /**
216         * @return The list of registered bind listeners
217         */
218        Set<BindListener> getBindListeners();
219}