1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21 package javax.portlet;
22
23
24
25 /***
26 * The <CODE>PortletSession</CODE> interface provides a way to identify a user
27 * across more than one request and to store transient information about that user.
28 * <p>
29 * A <code>PortletSession</code> is created per user client per portlet application.
30 * <p>
31 * A portlet can bind an object attribute into a <code>PortletSession</code> by name.
32 * The <code>PortletSession</code> interface defines two scopes for storing objects:
33 * <ul>
34 * <li><code>APPLICATION_SCOPE</code>
35 * <li><code>PORTLET_SCOPE</code>
36 * </ul>
37 * All objects stored in the session using the <code>APPLICATION_SCOPE</code>
38 * must be available to all the portlets, servlets and
39 * JSPs that belongs to the same portlet application and that handles a
40 * request identified as being a part of the same session.
41 * Objects stored in the session using the <code>PORTLET_SCOPE</code> must be
42 * available to the portlet during requests for the same portlet window
43 * that the objects where stored from. Attributes stored in the
44 * <code>PORTLET_SCOPE</code> are not protected from other web components
45 * of the portlet application. They are just conveniently namespaced.
46 * <P>
47 * The portlet session is based on the <code>HttpSession</code>. Therefore all
48 * <code>HttpSession</code> listeners do apply to the portlet session and
49 * attributes set in the portlet session are visible in the <code>HttpSession</code>
50 * and vice versa.
51 */
52 public interface PortletSession
53 {
54
55
56 /***
57 * This constant defines an application wide scope for the session attribute.
58 * <code>APPLICATION_SCOPE</code> session attributes enable Portlets
59 * within one portlet application to share data.
60 * <p>
61 * Portlets may need to prefix attributes set in this scope with some
62 * ID, to avoid overwriting each other's attributes in the
63 * case where two portlets of the same portlet definition
64 * are created.
65 * <p>
66 * Value: <code>0x01</code>
67 */
68 public static final int APPLICATION_SCOPE = 0x01;
69
70 /***
71 * This constant defines the scope of the session attribute to be
72 * private to the portlet and its included resources.
73 * <p>
74 * Value: <code>0x02</code>
75 */
76 public static final int PORTLET_SCOPE = 0x02;
77
78
79
80 /***
81 * Returns the object bound with the specified name in this session
82 * under the <code>PORTLET_SCOPE</code>, or <code>null</code> if no
83 * object is bound under the name in that scope.
84 *
85 * @param name a string specifying the name of the object
86 *
87 * @return the object with the specified name for
88 * the <code>PORTLET_SCOPE</code>.
89 *
90 * @exception java.lang.IllegalStateException if this method is called on an
91 * invalidated session.
92 * @exception java.lang.IllegalArgumentException
93 * if name is <code>null</code>.
94 */
95
96 public java.lang.Object getAttribute(java.lang.String name);
97
98
99 /***
100 * Returns the object bound with the specified name in this session,
101 * or <code>null</code> if no object is bound under the name in the given scope.
102 *
103 * @param name a string specifying the name of the object
104 * @param scope session scope of this attribute
105 *
106 * @return the object with the specified name
107 *
108 * @exception java.lang.IllegalStateException if this method is called on an
109 * invalidated session
110 * @exception java.lang.IllegalArgumentException
111 * if name is <code>null</code>.
112 */
113
114 public java.lang.Object getAttribute(java.lang.String name,int scope);
115
116
117 /***
118 * Returns an <code>Enumeration</code> of String objects containing the names of
119 * all the objects bound to this session under the <code>PORTLET_SCOPE</code>, or an
120 * empty <code>Enumeration</code> if no attributes are available.
121 *
122 * @return an <code>Enumeration</code> of
123 * <code>String</code> objects specifying the
124 * names of all the objects bound to
125 * this session, or an empty <code>Enumeration</code>
126 * if no attributes are available.
127 *
128 * @exception java.lang.IllegalStateException if this method is called on an
129 * invalidated session
130 */
131
132 public java.util.Enumeration getAttributeNames();
133
134
135 /***
136 * Returns an <code>Enumeration</code> of String objects containing the names of
137 * all the objects bound to this session in the given scope, or an
138 * empty <code>Enumeration</code> if no attributes are available in the
139 * given scope.
140 *
141 * @param scope session scope of the attribute names
142 *
143 * @return an <code>Enumeration</code> of
144 * <code>String</code> objects specifying the
145 * names of all the objects bound to
146 * this session, or an empty <code>Enumeration</code>
147 * if no attributes are available in the given scope.
148 *
149 * @exception java.lang.IllegalStateException if this method is called on an
150 * invalidated session
151 */
152
153 public java.util.Enumeration getAttributeNames(int scope);
154
155 /***
156 * Returns the time when this session was created, measured in
157 * milliseconds since midnight January 1, 1970 GMT.
158 *
159 * @return a <code>long</code> specifying
160 * when this session was created,
161 * expressed in
162 * milliseconds since 1/1/1970 GMT
163 *
164 * @exception java.lang.IllegalStateException if this method is called on an
165 * invalidated session
166 */
167
168 public long getCreationTime();
169
170
171 /***
172 * Returns a string containing the unique identifier assigned to this session.
173 *
174 * @return a string specifying the identifier
175 * assigned to this session
176 */
177
178 public java.lang.String getId();
179
180
181 /***
182 * Returns the last time the client sent a request associated with this session,
183 * as the number of milliseconds since midnight January 1, 1970 GMT.
184 *
185 * <p>Actions that your portlet takes, such as getting or setting
186 * a value associated with the session, do not affect the access
187 * time.
188 *
189 * @return a <code>long</code>
190 * representing the last time
191 * the client sent a request associated
192 * with this session, expressed in
193 * milliseconds since 1/1/1970 GMT
194 */
195
196 public long getLastAccessedTime();
197
198
199 /***
200 * Returns the maximum time interval, in seconds, for which the portlet container
201 * keeps this session open between client accesses. After this interval,
202 * the portlet container invalidates the session. The maximum time
203 * interval can be set
204 * with the <code>setMaxInactiveInterval</code> method.
205 * A negative time indicates the session should never timeout.
206 *
207 * @return an integer specifying the number of
208 * seconds this session remains open
209 * between client requests
210 *
211 * @see #setMaxInactiveInterval
212 */
213
214 public int getMaxInactiveInterval();
215
216
217 /***
218 * Invalidates this session (all scopes) and unbinds any objects bound to it.
219 * <p>
220 * Invalidating the portlet session will result in invalidating the underlying
221 * <code>HttpSession</code>
222 *
223 * @exception java.lang.IllegalStateException if this method is called on a
224 * session which has already been invalidated
225 */
226
227 public void invalidate();
228
229
230
231 /***
232 * Returns true if the client does not yet know about the session or
233 * if the client chooses not to join the session.
234 *
235 * @return <code>true</code> if the
236 * server has created a session,
237 * but the client has not joined yet.
238 *
239 * @exception java.lang.IllegalStateException if this method is called on a
240 * session which has already been invalidated
241 *
242 */
243
244 public boolean isNew();
245
246
247 /***
248 * Removes the object bound with the specified name under
249 * the <code>PORTLET_SCOPE</code> from
250 * this session. If the session does not have an object
251 * bound with the specified name, this method does nothing.
252 *
253 * @param name the name of the object to be
254 * removed from this session in the
255 * <code> PORTLET_SCOPE</code>.
256 *
257 * @exception java.lang.IllegalStateException
258 * if this method is called on a
259 * session which has been invalidated
260 * @exception java.lang.IllegalArgumentException
261 * if name is <code>null</code>.
262 */
263
264 public void removeAttribute(String name) ;
265
266
267 /***
268 * Removes the object bound with the specified name and the given scope from
269 * this session. If the session does not have an object
270 * bound with the specified name, this method does nothing.
271 *
272 * @param name the name of the object to be
273 * removed from this session
274 * @param scope session scope of this attribute
275 *
276 * @exception java.lang.IllegalStateException
277 * if this method is called on a
278 * session which has been invalidated
279 * @exception java.lang.IllegalArgumentException
280 * if name is <code>null</code>.
281 */
282
283 public void removeAttribute(String name, int scope) ;
284
285
286 /***
287 * Binds an object to this session under the <code>PORTLET_SCOPE</code>, using the name specified.
288 * If an object of the same name in this scope is already bound to the session,
289 * that object is replaced.
290 *
291 * <p>After this method has been executed, and if the new object
292 * implements <code>HttpSessionBindingListener</code>,
293 * the container calls
294 * <code>HttpSessionBindingListener.valueBound</code>. The container then
295 * notifies any <code>HttpSessionAttributeListeners</code> in the web
296 * application.
297 * <p>If an object was already bound to this session
298 * that implements <code>HttpSessionBindingListener</code>, its
299 * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
300 *
301 * <p>If the value is <code>null</code>, this has the same effect as calling
302 * <code>removeAttribute()</code>.
303 *
304 *
305 * @param name the name to which the object is bound under
306 * the <code>PORTLET_SCOPE</code>;
307 * this cannot be <code>null</code>.
308 * @param value the object to be bound
309 *
310 * @exception java.lang.IllegalStateException if this method is called on a
311 * session which has been invalidated
312 * @exception java.lang.IllegalArgumentException
313 * if name is <code>null</code>.
314 */
315
316 public void setAttribute(java.lang.String name, java.lang.Object value);
317
318
319 /***
320 * Binds an object to this session in the given scope, using the name specified.
321 * If an object of the same name in this scope is already bound to the session,
322 * that object is replaced.
323 *
324 * <p>After this method has been executed, and if the new object
325 * implements <code>HttpSessionBindingListener</code>,
326 * the container calls
327 * <code>HttpSessionBindingListener.valueBound</code>. The container then
328 * notifies any <code>HttpSessionAttributeListeners</code> in the web
329 * application.
330 * <p>If an object was already bound to this session
331 * that implements <code>HttpSessionBindingListener</code>, its
332 * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
333 *
334 * <p>If the value is <code>null</code>, this has the same effect as calling
335 * <code>removeAttribute()</code>.
336 *
337 *
338 * @param name the name to which the object is bound;
339 * this cannot be <code>null</code>.
340 * @param value the object to be bound
341 * @param scope session scope of this attribute
342 *
343 * @exception java.lang.IllegalStateException if this method is called on a
344 * session which has been invalidated
345 * @exception java.lang.IllegalArgumentException
346 * if name is <code>null</code>.
347 */
348
349 public void setAttribute(java.lang.String name, java.lang.Object value, int scope);
350
351
352 /***
353 * Specifies the time, in seconds, between client requests, before the
354 * portlet container invalidates this session. A negative time
355 * indicates the session should never timeout.
356 *
357 * @param interval An integer specifying the number
358 * of seconds
359 */
360
361 public void setMaxInactiveInterval(int interval);
362
363
364 /***
365 * Returns the portlet application context associated with this session.
366 *
367 * @return the portlet application context
368 */
369
370 public PortletContext getPortletContext ();
371
372 }
373
374