Session


1   /*
2    * Copyright 1999-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.cocoon.environment;
17  
18  import java.util.Enumeration  ;
19  
20  /**
21   *
22   * Provides a way to identify a user across more than one page
23   * request or visit to a Web site and to store information about that user.
24   *
25   * <p>Cocoon uses this interface to create a session
26   * between a client and the "cocoon server". The session persists
27   * for a specified time period, across more than one connection or
28   * page request from the user. A session usually corresponds to one
29   * user, who may visit a site many times. The server can maintain a
30   * session in many ways such as using cookies or rewriting URLs.
31   *
32   * <p>This interface allows Cocoon to
33   * <ul>
34   * <li>View and manipulate information about a session, such as
35   *     the session identifier, creation time, and last accessed time
36   * <li>Bind objects to sessions, allowing user information to persist
37   *     across multiple user connections
38   * </ul>
39   *
40   * <p>Session information is scoped only to the current context
41   * (<code>Context</code>), so information stored in one context
42   * will not be directly visible in another.
43   *
44   * @author <a HREF="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
45   * @version CVS $Id: Session.java 30932 2004-07-29 17:35:38Z vgritsenko $
46   *
47   */
48  
49  public interface Session {
50  
51      /**
52       *
53       * Returns the time when this session was created, measured
54       * in milliseconds since midnight January 1, 1970 GMT.
55       *
56       * @return                                a <code>long</code> specifying
57       *                                         when this session was created,
58       *                                        expressed in
59       *                                        milliseconds since 1/1/1970 GMT
60       *
61       * @exception IllegalStateException        if this method is called on an
62       *                                        invalidated session
63       *
64       */
65      long getCreationTime();
66  
67      /**
68       *
69       * Returns a string containing the unique identifier assigned
70       * to this session. The identifier is assigned
71       * by the context container and is implementation dependent.
72       *
73       * @return                                a string specifying the identifier
74       *                                        assigned to this session
75       *
76       * @exception IllegalStateException        if this method is called on an
77       *                                        invalidated session
78       *
79       */
80      String   getId();
81  
82      /**
83       *
84       * Returns the last time the client sent a request associated with
85       * this session, as the number of milliseconds since midnight
86       * January 1, 1970 GMT.
87       *
88       * <p>Actions that your application takes, such as getting or setting
89       * a value associated with the session, do not affect the access
90       * time.
91       *
92       * @return                                a <code>long</code>
93       *                                        representing the last time
94       *                                        the client sent a request associated
95       *                                        with this session, expressed in
96       *                                        milliseconds since 1/1/1970 GMT
97       *
98       * @exception IllegalStateException        if this method is called on an
99       *                                        invalidated session
100      *
101      */
102 
103     long getLastAccessedTime();
104 
105     /**
106      *
107      * Specifies the time, in seconds, between client requests before the
108      * contextcontainer will invalidate this session.  A negative time
109      * indicates the session should never timeout.
110      *
111      * @param interval                An integer specifying the number
112      *                                 of seconds
113      *
114      */
115     void setMaxInactiveInterval(int interval);
116 
117    /**
118     * Returns the maximum time interval, in seconds, that
119     * the context container will keep this session open between
120     * client accesses. After this interval, the context container
121     * will invalidate the session.  The maximum time interval can be set
122     * with the <code>setMaxInactiveInterval</code> method.
123     * A negative time indicates the session should never timeout.
124     *
125     *
126     * @return                an integer specifying the number of
127     *                        seconds this session remains open
128     *                        between client requests
129     *
130     * @see                #setMaxInactiveInterval(int)
131     *
132     *
133     */
134     int getMaxInactiveInterval();
135 
136     /**
137      *
138      * Returns the object bound with the specified name in this session, or
139      * <code>null</code> if no object is bound under the name.
140      *
141      * @param name                a string specifying the name of the object
142      *
143      * @return                        the object with the specified name
144      *
145      * @exception IllegalStateException        if this method is called on an
146      *                                        invalidated session
147      *
148      */
149     Object   getAttribute(String   name);
150 
151     /**
152      *
153      * Returns an <code>Enumeration</code> of <code>String</code> objects
154      * containing the names of all the objects bound to this session.
155      *
156      * @return                        an <code>Enumeration</code> of
157      *                                <code>String</code> objects specifying the
158      *                                names of all the objects bound to
159      *                                this session
160      *
161      * @exception IllegalStateException        if this method is called on an
162      *                                        invalidated session
163      *
164      */
165     Enumeration   getAttributeNames();
166 
167     /**
168      * Binds an object to this session, using the name specified.
169      * If an object of the same name is already bound to the session,
170      * the object is replaced.
171      *
172      *
173      * @param name                        the name to which the object is bound;
174      *                                        cannot be null
175      *
176      * @param value                        the object to be bound; cannot be null
177      *
178      * @exception IllegalStateException        if this method is called on an
179      *                                        invalidated session
180      *
181      */
182     void setAttribute(String   name, Object   value);
183 
184     /**
185      *
186      * Removes the object bound with the specified name from
187      * this session. If the session does not have an object
188      * bound with the specified name, this method does nothing.
189      *
190      *
191      * @param name                                the name of the object to
192      *                                                remove from this session
193      *
194      * @exception IllegalStateException        if this method is called on an
195      *                                        invalidated session
196      */
197     void removeAttribute(String   name);
198 
199     /**
200      *
201      * Invalidates this session
202      * to it.
203      *
204      * @exception IllegalStateException        if this method is called on an
205      *                                        already invalidated session
206      *
207      */
208     void invalidate();
209 
210     /**
211      *
212      * Returns <code>true</code> if the client does not yet know about the
213      * session or if the client chooses not to join the session.  For
214      * example, if the server used only cookie-based sessions, and
215      * the client had disabled the use of cookies, then a session would
216      * be new on each request.
217      *
218      * @return                                 <code>true</code> if the
219      *                                        server has created a session,
220      *                                        but the client has not yet joined
221      *
222      * @exception IllegalStateException        if this method is called on an
223      *                                        already invalidated session
224      *
225      */
226     boolean isNew();
227 
228 }
229 
230
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags