001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *  http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    
020    //
021    // This source code implements specifications defined by the Java
022    // Community Process. In order to remain compliant with the specification
023    // DO NOT add / change / or delete method signatures!
024    //
025    
026    package javax.servlet.http;
027    
028    import java.util.Enumeration;
029    import javax.servlet.ServletContext;
030    
031    /**
032     * Provides a way to identify a user across more than one page
033     * request or visit to a Web site and to store information about that user.
034     *
035     * <p>The servlet container uses this interface to create a session
036     * between an HTTP client and an HTTP server. The session persists
037     * for a specified time period, across more than one connection or
038     * page request from the user. A session usually corresponds to one
039     * user, who may visit a site many times. The server can maintain a
040     * session in many ways such as using cookies or rewriting URLs.
041     *
042     * <p>This interface allows servlets to
043     * <ul>
044     * <li>View and manipulate information about a session, such as
045     *     the session identifier, creation time, and last accessed time
046     * <li>Bind objects to sessions, allowing user information to persist
047     *     across multiple user connections
048     * </ul>
049     *
050     * <p>When an application stores an object in or removes an object from a
051     * session, the session checks whether the object implements
052     * {@link HttpSessionBindingListener}. If it does,
053     * the servlet notifies the object that it has been bound to or unbound
054     * from the session. Notifications are sent after the binding methods complete.
055     * For session that are invalidated or expire, notifications are sent after
056     * the session has been invalidatd or expired.
057     *
058     * <p> When container migrates a session between VMs in a distributed container
059     * setting, all session attributes implementing the {@link HttpSessionActivationListener}
060     * interface are notified.
061     *
062     * <p>A servlet should be able to handle cases in which
063     * the client does not choose to join a session, such as when cookies are
064     * intentionally turned off. Until the client joins the session,
065     * <code>isNew</code> returns <code>true</code>.  If the client chooses
066     * not to join
067     * the session, <code>getSession</code> will return a different session
068     * on each request, and <code>isNew</code> will always return
069     * <code>true</code>.
070     *
071     * <p>Session information is scoped only to the current web application
072     * (<code>ServletContext</code>), so information stored in one context
073     * will not be directly visible in another.
074     *
075     * @see HttpSessionBindingListener
076     * @see HttpSessionContext
077     *
078     * @version $Rev: 467553 $ $Date: 2006-10-25 06:01:51 +0200 (Mi, 25. Okt 2006) $
079     */
080    public interface HttpSession {
081        /**
082         * Returns the time when this session was created, measured
083         * in milliseconds since midnight January 1, 1970 GMT.
084         *
085         * @return a <code>long</code> specifying when this session was created,
086         * expressed in milliseconds since 1/1/1970 GMT
087         *
088         * @exception IllegalStateException if this method is called on an
089         * invalidated session
090         */
091        public long getCreationTime();
092    
093        /**
094         * Returns a string containing the unique identifier assigned to this
095         * session. The identifier is assigned by the servlet container and is
096         * implementation dependent.
097         *
098         * @return a string specifying the identifier assigned to this session
099         *
100         * @exception IllegalStateException if this method is called on an
101         * invalidated session
102         */
103        public String getId();
104    
105        /**
106         * Returns the last time the client sent a request associated with
107         * this session, as the number of milliseconds since midnight
108         * January 1, 1970 GMT, and marked by the time the container received the request.
109         *
110         * <p>Actions that your application takes, such as getting or setting
111         * a value associated with the session, do not affect the access
112         * time.
113         *
114         * @return a <code>long</code> representing the last time the client sent
115         * a request associated with this session, expressed in milliseconds since
116         * 1/1/1970 GMT
117         *
118         * @exception IllegalStateException if this method is called on an
119         * invalidated session
120         */
121        public long getLastAccessedTime();
122    
123        /**
124         * Returns the ServletContext to which this session belongs.
125         *
126         * @return The ServletContext object for the web application
127         * @since Servlet 2.3
128         */
129        public ServletContext getServletContext();
130    
131        /**
132         * Specifies the time, in seconds, between client requests before the
133         * servlet container will invalidate this session.  A negative time
134         * indicates the session should never timeout.
135         *
136         * @param interval An integer specifying the number of seconds
137         */
138        public void setMaxInactiveInterval(int interval);
139    
140        /**
141         * Returns the maximum time interval, in seconds, that
142         * the servlet container will keep this session open between
143         * client accesses. After this interval, the servlet container
144         * will invalidate the session.  The maximum time interval can be set
145         * with the <code>setMaxInactiveInterval</code> method.
146         * A negative time indicates the session should never timeout.
147         *
148         * @return an integer specifying the number of seconds this session
149         * remains open between client requests
150         *
151         * @see #setMaxInactiveInterval
152         */
153        public int getMaxInactiveInterval();
154    
155        /**
156         * @deprecated As of Version 2.1, this method is deprecated and has no
157         * replacement. It will be removed in a future version of the Java Servlet
158         * API.
159         */
160        public HttpSessionContext getSessionContext();
161    
162        /**
163         * Returns the object bound with the specified name in this session, or
164         * <code>null</code> if no object is bound under the name.
165         *
166         * @param name a string specifying the name of the object
167         *
168         * @return the object with the specified name
169         *
170         * @exception IllegalStateException if this method is called on an
171         * invalidated session
172         */
173        public Object getAttribute(String name);
174    
175        /**
176         * @deprecated As of Version 2.2, this method is replaced by
177         * {@link #getAttribute}.
178         *
179         * @param name a string specifying the name of the object
180         *
181         * @return the object with the specified name
182         *
183         * @exception IllegalStateException if this method is called on an
184         * invalidated session
185         */
186        public Object getValue(String name);
187    
188        /**
189         * Returns an <code>Enumeration</code> of <code>String</code> objects
190         * containing the names of all the objects bound to this session.
191         *
192         * @return an <code>Enumeration</code> of <code>String</code> objects
193         * specifying the names of all the objects bound to this session
194         *
195         * @exception IllegalStateException if this method is called on an
196         * invalidated session
197         */
198        public Enumeration getAttributeNames();
199    
200        /**
201         * @deprecated As of Version 2.2, this method is replaced by
202         * {@link #getAttributeNames}
203         *
204         * @return an array of <code>String</code> objects specifying the names of
205         * all the objects bound to this session
206         *
207         * @exception IllegalStateException if this method is called on an
208         * invalidated session
209         */
210        public String[] getValueNames();
211    
212        /**
213         * Binds an object to this session, using the name specified. If an object
214         * of the same name is already bound to the session, the object is
215         * replaced.
216         *
217         * <p>After this method executes, and if the new object implements
218         * <code>HttpSessionBindingListener</code>, the container calls
219         * <code>HttpSessionBindingListener.valueBound</code>. The container then
220         * notifies any <code>HttpSessionAttributeListener</code>s in the web
221         * application.
222         *
223         * <p>If an object was already bound to this session of this name
224         * that implements <code>HttpSessionBindingListener</code>, its
225         * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
226         *
227         * <p>If the value passed in is null, this has the same effect as calling
228         * <code>removeAttribute()<code>.
229         *
230         * @param name the name to which the object is bound; cannot be null
231         *
232         * @param value the object to be bound
233         *
234         * @exception IllegalStateException if this method is called on an
235         * invalidated session
236         */
237        public void setAttribute(String name, Object value);
238    
239        /**
240         * @deprecated As of Version 2.2, this method is replaced by
241         * {@link #setAttribute}
242         *
243         * @param name the name to which the object is bound; cannot be null
244         *
245         * @param value the object to be bound; cannot be null
246         *
247         * @exception IllegalStateException if this method is called on an
248         * invalidated session
249         */
250        public void putValue(String name, Object value);
251    
252        /**
253         * Removes the object bound with the specified name from this session.
254         * If the session does not have an object bound with the specified name,
255         * this method does nothing.
256         *
257         * <p>After this method executes, and if the object implements
258         * <code>HttpSessionBindingListener</code>, the container calls
259         * <code>HttpSessionBindingListener.valueUnbound</code>. The container
260         * then notifies any <code>HttpSessionAttributeListener</code>s in the web
261         * application.
262         *
263         * @param name the name of the object to remove from this session
264         *
265         * @exception IllegalStateException if this method is called on an
266         * invalidated session
267         */
268        public void removeAttribute(String name);
269    
270        /**
271         * @deprecated As of Version 2.2, this method is replaced by
272         * {@link #removeAttribute}
273         *
274         * @param name the name of the object to remove from this session
275         *
276         * @exception IllegalStateException if this method is called on an
277         * invalidated session
278         */
279        public void removeValue(String name);
280    
281        /**
282         * Invalidates this session then unbinds any objects bound to it.
283         *
284         * @exception IllegalStateException if this method is called on an already
285         * invalidated session
286         */
287        public void invalidate();
288    
289        /**
290         * Returns <code>true</code> if the client does not yet know about the
291         * session or if the client chooses not to join the session.  For
292         * example, if the server used only cookie-based sessions, and
293         * the client had disabled the use of cookies, then a session would
294         * be new on each request.
295         *
296         * @return <code>true</code> if the server has created a session, but the
297         * client has not yet joined
298         *
299         * @exception IllegalStateException if this method is called on an already
300         * invalidated session
301         */
302        public boolean isNew();
303    }
304