001: /**
002: * Copyright 2003 IBM Corporation and Sun Microsystems, Inc.
003: * All rights reserved.
004: * Use is subject to license terms.
005: */package javax.portlet;
006:
007: /**
008: * The <CODE>PortletSession</CODE> interface provides a way to identify a user
009: * across more than one request and to store transient information about that user.
010: * <p>
011: * A <code>PortletSession</code> is created per user client per portlet application.
012: * <p>
013: * A portlet can bind an object attribute into a <code>PortletSession</code> by name.
014: * The <code>PortletSession</code> interface defines two scopes for storing objects:
015: * <ul>
016: * <li><code>APPLICATION_SCOPE</code>
017: * <li><code>PORTLET_SCOPE</code>
018: * </ul>
019: * All objects stored in the session using the <code>APPLICATION_SCOPE</code>
020: * must be available to all the portlets, servlets and
021: * JSPs that belongs to the same portlet application and that handles a
022: * request identified as being a part of the same session.
023: * Objects stored in the session using the <code>PORTLET_SCOPE</code> must be
024: * available to the portlet during requests for the same portlet window
025: * that the objects where stored from. Attributes stored in the
026: * <code>PORTLET_SCOPE</code> are not protected from other web components
027: * of the portlet application. They are just conveniently namespaced.
028: * <P>
029: * The portlet session is based on the <code>HttpSession</code>. Therefore all
030: * <code>HttpSession</code> listeners do apply to the portlet session and
031: * attributes set in the portlet session are visible in the <code>HttpSession</code>
032: * and vice versa.
033: */
034: public interface PortletSession {
035:
036: /**
037: * This constant defines an application wide scope for the session attribute.
038: * <code>APPLICATION_SCOPE</code> session attributes enable Portlets
039: * within one portlet application to share data.
040: * <p>
041: * Portlets may need to prefix attributes set in this scope with some
042: * ID, to avoid overwriting each other's attributes in the
043: * case where two portlets of the same portlet definition
044: * are created.
045: * <p>
046: * Value: <code>0x01</code>
047: */
048: public static final int APPLICATION_SCOPE = 0x01;
049:
050: /**
051: * This constant defines the scope of the session attribute to be
052: * private to the portlet and its included resources.
053: * <p>
054: * Value: <code>0x02</code>
055: */
056: public static final int PORTLET_SCOPE = 0x02;
057:
058: /**
059: * Returns the object bound with the specified name in this session
060: * under the <code>PORTLET_SCOPE</code>, or <code>null</code> if no
061: * object is bound under the name in that scope.
062: *
063: * @param name a string specifying the name of the object
064: *
065: * @return the object with the specified name for
066: * the <code>PORTLET_SCOPE</code>.
067: *
068: * @exception java.lang.IllegalStateException if this method is called on an
069: * invalidated session.
070: * @exception java.lang.IllegalArgumentException
071: * if name is <code>null</code>.
072: */
073:
074: public java.lang.Object getAttribute(java.lang.String name);
075:
076: /**
077: * Returns the object bound with the specified name in this session,
078: * or <code>null</code> if no object is bound under the name in the given scope.
079: *
080: * @param name a string specifying the name of the object
081: * @param scope session scope of this attribute
082: *
083: * @return the object with the specified name
084: *
085: * @exception java.lang.IllegalStateException if this method is called on an
086: * invalidated session
087: * @exception java.lang.IllegalArgumentException
088: * if name is <code>null</code>.
089: */
090:
091: public java.lang.Object getAttribute(java.lang.String name,
092: int scope);
093:
094: /**
095: * Returns an <code>Enumeration</code> of String objects containing the names of
096: * all the objects bound to this session under the <code>PORTLET_SCOPE</code>, or an
097: * empty <code>Enumeration</code> if no attributes are available.
098: *
099: * @return an <code>Enumeration</code> of
100: * <code>String</code> objects specifying the
101: * names of all the objects bound to
102: * this session, or an empty <code>Enumeration</code>
103: * if no attributes are available.
104: *
105: * @exception java.lang.IllegalStateException if this method is called on an
106: * invalidated session
107: */
108:
109: public java.util.Enumeration getAttributeNames();
110:
111: /**
112: * Returns an <code>Enumeration</code> of String objects containing the names of
113: * all the objects bound to this session in the given scope, or an
114: * empty <code>Enumeration</code> if no attributes are available in the
115: * given scope.
116: *
117: * @param scope session scope of the attribute names
118: *
119: * @return an <code>Enumeration</code> of
120: * <code>String</code> objects specifying the
121: * names of all the objects bound to
122: * this session, or an empty <code>Enumeration</code>
123: * if no attributes are available in the given scope.
124: *
125: * @exception java.lang.IllegalStateException if this method is called on an
126: * invalidated session
127: */
128:
129: public java.util.Enumeration getAttributeNames(int scope);
130:
131: /**
132: * Returns the time when this session was created, measured in
133: * milliseconds since midnight January 1, 1970 GMT.
134: *
135: * @return a <code>long</code> specifying
136: * when this session was created,
137: * expressed in
138: * milliseconds since 1/1/1970 GMT
139: *
140: * @exception java.lang.IllegalStateException if this method is called on an
141: * invalidated session
142: */
143:
144: public long getCreationTime();
145:
146: /**
147: * Returns a string containing the unique identifier assigned to this session.
148: *
149: * @return a string specifying the identifier
150: * assigned to this session
151: */
152:
153: public java.lang.String getId();
154:
155: /**
156: * Returns the last time the client sent a request associated with this session,
157: * as the number of milliseconds since midnight January 1, 1970 GMT.
158: *
159: * <p>Actions that your portlet takes, such as getting or setting
160: * a value associated with the session, do not affect the access
161: * time.
162: *
163: * @return a <code>long</code>
164: * representing the last time
165: * the client sent a request associated
166: * with this session, expressed in
167: * milliseconds since 1/1/1970 GMT
168: */
169:
170: public long getLastAccessedTime();
171:
172: /**
173: * Returns the maximum time interval, in seconds, for which the portlet container
174: * keeps this session open between client accesses. After this interval,
175: * the portlet container invalidates the session. The maximum time
176: * interval can be set
177: * with the <code>setMaxInactiveInterval</code> method.
178: * A negative time indicates the session should never timeout.
179: *
180: * @return an integer specifying the number of
181: * seconds this session remains open
182: * between client requests
183: *
184: * @see #setMaxInactiveInterval
185: */
186:
187: public int getMaxInactiveInterval();
188:
189: /**
190: * Invalidates this session (all scopes) and unbinds any objects bound to it.
191: * <p>
192: * Invalidating the portlet session will result in invalidating the underlying
193: * <code>HttpSession</code>
194: *
195: * @exception java.lang.IllegalStateException if this method is called on a
196: * session which has already been invalidated
197: */
198:
199: public void invalidate();
200:
201: /**
202: * Returns true if the client does not yet know about the session or
203: * if the client chooses not to join the session.
204: *
205: * @return <code>true</code> if the
206: * server has created a session,
207: * but the client has not joined yet.
208: *
209: * @exception java.lang.IllegalStateException if this method is called on a
210: * session which has already been invalidated
211: *
212: */
213:
214: public boolean isNew();
215:
216: /**
217: * Removes the object bound with the specified name under
218: * the <code>PORTLET_SCOPE</code> from
219: * this session. If the session does not have an object
220: * bound with the specified name, this method does nothing.
221: *
222: * @param name the name of the object to be
223: * removed from this session in the
224: * <code> PORTLET_SCOPE</code>.
225: *
226: * @exception java.lang.IllegalStateException
227: * if this method is called on a
228: * session which has been invalidated
229: * @exception java.lang.IllegalArgumentException
230: * if name is <code>null</code>.
231: */
232:
233: public void removeAttribute(String name);
234:
235: /**
236: * Removes the object bound with the specified name and the given scope from
237: * this session. If the session does not have an object
238: * bound with the specified name, this method does nothing.
239: *
240: * @param name the name of the object to be
241: * removed from this session
242: * @param scope session scope of this attribute
243: *
244: * @exception java.lang.IllegalStateException
245: * if this method is called on a
246: * session which has been invalidated
247: * @exception java.lang.IllegalArgumentException
248: * if name is <code>null</code>.
249: */
250:
251: public void removeAttribute(String name, int scope);
252:
253: /**
254: * Binds an object to this session under the <code>PORTLET_SCOPE</code>, using the name specified.
255: * If an object of the same name in this scope is already bound to the session,
256: * that object is replaced.
257: *
258: * <p>After this method has been executed, and if the new object
259: * implements <code>HttpSessionBindingListener</code>,
260: * the container calls
261: * <code>HttpSessionBindingListener.valueBound</code>. The container then
262: * notifies any <code>HttpSessionAttributeListeners</code> in the web
263: * application.
264: * <p>If an object was already bound to this session
265: * that implements <code>HttpSessionBindingListener</code>, its
266: * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
267: *
268: * <p>If the value is <code>null</code>, this has the same effect as calling
269: * <code>removeAttribute()</code>.
270: *
271: *
272: * @param name the name to which the object is bound under
273: * the <code>PORTLET_SCOPE</code>;
274: * this cannot be <code>null</code>.
275: * @param value the object to be bound
276: *
277: * @exception java.lang.IllegalStateException 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 setAttribute(java.lang.String name,
284: java.lang.Object value);
285:
286: /**
287: * Binds an object to this session in the given scope, 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;
306: * this cannot be <code>null</code>.
307: * @param value the object to be bound
308: * @param scope session scope of this attribute
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,
317: java.lang.Object value, int scope);
318:
319: /**
320: * Specifies the time, in seconds, between client requests, before the
321: * portlet container invalidates this session. A negative time
322: * indicates the session should never timeout.
323: *
324: * @param interval An integer specifying the number
325: * of seconds
326: */
327:
328: public void setMaxInactiveInterval(int interval);
329:
330: /**
331: * Returns the portlet application context associated with this session.
332: *
333: * @return the portlet application context
334: */
335:
336: public PortletContext getPortletContext();
337:
338: }
|