Session


1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  
19  package org.apache.catalina;
20  
21  
22  import java.security.Principal  ;
23  import java.util.Iterator  ;
24  
25  import javax.servlet.http.HttpSession  ;
26  
27  
28  /**
29   * A <b>Session</b> is the Catalina-internal facade for an
30   * <code>HttpSession</code> that is used to maintain state information
31   * between requests for a particular user of a web application.
32   *
33   * @author Craig R. McClanahan
34   * @version $Revision: 467222 $ $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
35   */
36  
37  public interface Session {
38  
39  
40      // ----------------------------------------------------- Manifest Constants
41  
42  
43      /**
44       * The SessionEvent event type when a session is created.
45       */
46      public static final String   SESSION_CREATED_EVENT = "createSession";
47  
48  
49      /**
50       * The SessionEvent event type when a session is destroyed.
51       */
52      public static final String   SESSION_DESTROYED_EVENT = "destroySession";
53  
54  
55      /**
56       * The SessionEvent event type when a session is activated.
57       */
58      public static final String   SESSION_ACTIVATED_EVENT = "activateSession";
59  
60  
61      /**
62       * The SessionEvent event type when a session is passivated.
63       */
64      public static final String   SESSION_PASSIVATED_EVENT = "passivateSession";
65  
66  
67      // ------------------------------------------------------------- Properties
68  
69  
70      /**
71       * Return the authentication type used to authenticate our cached
72       * Principal, if any.
73       */
74      public String   getAuthType();
75  
76  
77      /**
78       * Set the authentication type used to authenticate our cached
79       * Principal, if any.
80       *
81       * @param authType The new cached authentication type
82       */
83      public void setAuthType(String   authType);
84  
85  
86      /**
87       * Return the creation time for this session.
88       */
89      public long getCreationTime();
90  
91  
92      /**
93       * Set the creation time for this session.  This method is called by the
94       * Manager when an existing Session instance is reused.
95       *
96       * @param time The new creation time
97       */
98      public void setCreationTime(long time);
99  
100 
101     /**
102      * Return the session identifier for this session.
103      */
104     public String   getId();
105 
106 
107     /**
108      * Return the session identifier for this session.
109      */
110     public String   getIdInternal();
111 
112 
113     /**
114      * Set the session identifier for this session.
115      *
116      * @param id The new session identifier
117      */
118     public void setId(String   id);
119 
120 
121     /**
122      * Return descriptive information about this Session implementation and
123      * the corresponding version number, in the format
124      * <code>&lt;description&gt;/&lt;version&gt;</code>.
125      */
126     public String   getInfo();
127 
128 
129     /**
130      * Return the last time the client sent a request associated with this
131      * session, as the number of milliseconds since midnight, January 1, 1970
132      * GMT.  Actions that your application takes, such as getting or setting
133      * a value associated with the session, do not affect the access time.
134      */
135     public long getLastAccessedTime();
136 
137     /**
138      * Return the last client access time without invalidation check
139      * @see #getLastAccessedTime().
140      */
141     public long getLastAccessedTimeInternal();
142 
143     /**
144      * Return the Manager within which this Session is valid.
145      */
146     public Manager getManager();
147 
148 
149     /**
150      * Set the Manager within which this Session is valid.
151      *
152      * @param manager The new Manager
153      */
154     public void setManager(Manager manager);
155 
156 
157     /**
158      * Return the maximum time interval, in seconds, between client requests
159      * before the servlet container will invalidate the session.  A negative
160      * time indicates that the session should never time out.
161      */
162     public int getMaxInactiveInterval();
163 
164 
165     /**
166      * Set the maximum time interval, in seconds, between client requests
167      * before the servlet container will invalidate the session.  A negative
168      * time indicates that the session should never time out.
169      *
170      * @param interval The new maximum interval
171      */
172     public void setMaxInactiveInterval(int interval);
173 
174 
175     /**
176      * Set the <code>isNew</code> flag for this session.
177      *
178      * @param isNew The new value for the <code>isNew</code> flag
179      */
180     public void setNew(boolean isNew);
181 
182 
183     /**
184      * Return the authenticated Principal that is associated with this Session.
185      * This provides an <code>Authenticator</code> with a means to cache a
186      * previously authenticated Principal, and avoid potentially expensive
187      * <code>Realm.authenticate()</code> calls on every request.  If there
188      * is no current associated Principal, return <code>null</code>.
189      */
190     public Principal   getPrincipal();
191 
192 
193     /**
194      * Set the authenticated Principal that is associated with this Session.
195      * This provides an <code>Authenticator</code> with a means to cache a
196      * previously authenticated Principal, and avoid potentially expensive
197      * <code>Realm.authenticate()</code> calls on every request.
198      *
199      * @param principal The new Principal, or <code>null</code> if none
200      */
201     public void setPrincipal(Principal   principal);
202 
203 
204     /**
205      * Return the <code>HttpSession</code> for which this object
206      * is the facade.
207      */
208     public HttpSession   getSession();
209 
210 
211     /**
212      * Set the <code>isValid</code> flag for this session.
213      *
214      * @param isValid The new value for the <code>isValid</code> flag
215      */
216     public void setValid(boolean isValid);
217 
218 
219     /**
220      * Return the <code>isValid</code> flag for this session.
221      */
222     public boolean isValid();
223 
224 
225     // --------------------------------------------------------- Public Methods
226 
227 
228     /**
229      * Update the accessed time information for this session.  This method
230      * should be called by the context when a request comes in for a particular
231      * session, even if the application does not reference it.
232      */
233     public void access();
234 
235 
236     /**
237      * Add a session event listener to this component.
238      */
239     public void addSessionListener(SessionListener listener);
240 
241 
242     /**
243      * End access to the session.
244      */
245     public void endAccess();
246 
247 
248     /**
249      * Perform the internal processing required to invalidate this session,
250      * without triggering an exception if the session has already expired.
251      */
252     public void expire();
253 
254 
255     /**
256      * Return the object bound with the specified name to the internal notes
257      * for this session, or <code>null</code> if no such binding exists.
258      *
259      * @param name Name of the note to be returned
260      */
261     public Object   getNote(String   name);
262 
263 
264     /**
265      * Return an Iterator containing the String names of all notes bindings
266      * that exist for this session.
267      */
268     public Iterator   getNoteNames();
269 
270 
271     /**
272      * Release all object references, and initialize instance variables, in
273      * preparation for reuse of this object.
274      */
275     public void recycle();
276 
277 
278     /**
279      * Remove any object bound to the specified name in the internal notes
280      * for this session.
281      *
282      * @param name Name of the note to be removed
283      */
284     public void removeNote(String   name);
285 
286 
287     /**
288      * Remove a session event listener from this component.
289      */
290     public void removeSessionListener(SessionListener listener);
291 
292 
293     /**
294      * Bind an object to a specified name in the internal notes associated
295      * with this session, replacing any existing binding for this name.
296      *
297      * @param name Name to which the object should be bound
298      * @param value Object to be bound to the specified name
299      */
300     public void setNote(String   name, Object   value);
301 
302 
303 }
304
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags