PortletSession


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