View Javadoc

1   /*
2    * Copyright 2003,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  /*
17   * This source code implements specifications defined by the Java
18   * Community Process. In order to remain compliant with the specification
19   * DO NOT add / change / or delete method signatures!
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