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: * @throws java.lang.IllegalStateException
065: * if this method is called on an
066: * invalidated session.
067: * @throws java.lang.IllegalArgumentException
068: * if name is <code>null</code>.
069: * @return the object with the specified name for
070: * the <code>PORTLET_SCOPE</code>.
071: */
072:
073: public java.lang.Object getAttribute(java.lang.String name);
074:
075: /**
076: * Returns the object bound with the specified name in this session,
077: * or <code>null</code> if no object is bound under the name in the given scope.
078: *
079: * @param name a string specifying the name of the object
080: * @param scope session scope of this attribute
081: * @throws java.lang.IllegalStateException
082: * if this method is called on an
083: * invalidated session
084: * @throws java.lang.IllegalArgumentException
085: * if name is <code>null</code>.
086: * @return the object with the specified name
087: */
088:
089: public java.lang.Object getAttribute(java.lang.String name,
090: int scope);
091:
092: /**
093: * Returns an <code>Enumeration</code> of String objects containing the names of
094: * all the objects bound to this session under the <code>PORTLET_SCOPE</code>, or an
095: * empty <code>Enumeration</code> if no attributes are available.
096: *
097: * @throws java.lang.IllegalStateException
098: * if this method is called on an
099: * invalidated session
100: * @return an <code>Enumeration</code> of
101: * <code>String</code> objects specifying the
102: * names of all the objects bound to
103: * this session, or an empty <code>Enumeration</code>
104: * if no attributes are available.
105: */
106:
107: public java.util.Enumeration getAttributeNames();
108:
109: /**
110: * Returns an <code>Enumeration</code> of String objects containing the names of
111: * all the objects bound to this session in the given scope, or an
112: * empty <code>Enumeration</code> if no attributes are available in the
113: * given scope.
114: *
115: * @param scope session scope of the attribute names
116: * @throws java.lang.IllegalStateException
117: * if this method is called on an
118: * invalidated session
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:
126: public java.util.Enumeration getAttributeNames(int scope);
127:
128: /**
129: * Returns the time when this session was created, measured in
130: * milliseconds since midnight January 1, 1970 GMT.
131: *
132: * @throws java.lang.IllegalStateException
133: * if this method is called on an
134: * invalidated session
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:
141: public long getCreationTime();
142:
143: /**
144: * Returns a string containing the unique identifier assigned to this session.
145: *
146: * @return a string specifying the identifier
147: * assigned to this session
148: */
149:
150: public java.lang.String getId();
151:
152: /**
153: * Returns the last time the client sent a request associated with this session,
154: * as the number of milliseconds since midnight January 1, 1970 GMT.
155: * <p/>
156: * <p>Actions that your portlet takes, such as getting or setting
157: * a value associated with the session, do not affect the access
158: * time.
159: *
160: * @return a <code>long</code>
161: * representing the last time
162: * the client sent a request associated
163: * with this session, expressed in
164: * milliseconds since 1/1/1970 GMT
165: */
166:
167: public long getLastAccessedTime();
168:
169: /**
170: * Returns the maximum time interval, in seconds, for which the portlet container
171: * keeps this session open between client accesses. After this interval,
172: * the portlet container invalidates the session. The maximum time
173: * interval can be set
174: * with the <code>setMaxInactiveInterval</code> method.
175: * A negative time indicates the session should never timeout.
176: *
177: * @return an integer specifying the number of
178: * seconds this session remains open
179: * between client requests
180: * @see #setMaxInactiveInterval
181: */
182:
183: public int getMaxInactiveInterval();
184:
185: /**
186: * Invalidates this session (all scopes) and unbinds any objects bound to it.
187: * <p/>
188: * Invalidating the portlet session will result in invalidating the underlying
189: * <code>HttpSession</code>
190: *
191: * @throws java.lang.IllegalStateException
192: * if this method is called on a
193: * session which has already been invalidated
194: */
195:
196: public void invalidate();
197:
198: /**
199: * Returns true if the client does not yet know about the session or
200: * if the client chooses not to join the session.
201: *
202: * @return <code>true</code> if the
203: * server has created a session,
204: * but the client has not joined yet.
205: * @throws java.lang.IllegalStateException
206: * if this method is called on a
207: * session which has already been invalidated
208: */
209:
210: public boolean isNew();
211:
212: /**
213: * Removes the object bound with the specified name under
214: * the <code>PORTLET_SCOPE</code> from
215: * this session. If the session does not have an object
216: * bound with the specified name, this method does nothing.
217: *
218: * @param name the name of the object to be
219: * removed from this session in the
220: * <code> PORTLET_SCOPE</code>.
221: * @throws java.lang.IllegalStateException
222: * if this method is called on a
223: * session which has been invalidated
224: * @throws java.lang.IllegalArgumentException
225: * if name is <code>null</code>.
226: */
227:
228: public void removeAttribute(String name);
229:
230: /**
231: * Removes the object bound with the specified name and the given scope from
232: * this session. If the session does not have an object
233: * bound with the specified name, this method does nothing.
234: *
235: * @param name the name of the object to be
236: * removed from this session
237: * @param scope session scope of this attribute
238: * @throws java.lang.IllegalStateException
239: * if this method is called on a
240: * session which has been invalidated
241: * @throws java.lang.IllegalArgumentException
242: * if name is <code>null</code>.
243: */
244:
245: public void removeAttribute(String name, int scope);
246:
247: /**
248: * Binds an object to this session under the <code>PORTLET_SCOPE</code>, using the name specified.
249: * If an object of the same name in this scope is already bound to the session,
250: * that object is replaced.
251: * <p/>
252: * <p>After this method has been executed, and if the new object
253: * implements <code>HttpSessionBindingListener</code>,
254: * the container calls
255: * <code>HttpSessionBindingListener.valueBound</code>. The container then
256: * notifies any <code>HttpSessionAttributeListeners</code> in the web
257: * application.
258: * <p>If an object was already bound to this session
259: * that implements <code>HttpSessionBindingListener</code>, its
260: * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
261: * <p/>
262: * <p>If the value is <code>null</code>, this has the same effect as calling
263: * <code>removeAttribute()</code>.
264: *
265: * @param name the name to which the object is bound under
266: * the <code>PORTLET_SCOPE</code>;
267: * this cannot be <code>null</code>.
268: * @param value the object to be bound
269: * @throws java.lang.IllegalStateException
270: * if this method is called on a
271: * session which has been invalidated
272: * @throws java.lang.IllegalArgumentException
273: * if name is <code>null</code>.
274: */
275:
276: public void setAttribute(java.lang.String name,
277: java.lang.Object value);
278:
279: /**
280: * Binds an object to this session in the given scope, using the name specified.
281: * If an object of the same name in this scope is already bound to the session,
282: * that object is replaced.
283: * <p/>
284: * <p>After this method has been executed, and if the new object
285: * implements <code>HttpSessionBindingListener</code>,
286: * the container calls
287: * <code>HttpSessionBindingListener.valueBound</code>. The container then
288: * notifies any <code>HttpSessionAttributeListeners</code> in the web
289: * application.
290: * <p>If an object was already bound to this session
291: * that implements <code>HttpSessionBindingListener</code>, its
292: * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
293: * <p/>
294: * <p>If the value is <code>null</code>, this has the same effect as calling
295: * <code>removeAttribute()</code>.
296: *
297: * @param name the name to which the object is bound;
298: * this cannot be <code>null</code>.
299: * @param value the object to be bound
300: * @param scope session scope of this attribute
301: * @throws java.lang.IllegalStateException
302: * if this method is called on a
303: * session which has been invalidated
304: * @throws java.lang.IllegalArgumentException
305: * if name is <code>null</code>.
306: */
307:
308: public void setAttribute(java.lang.String name,
309: java.lang.Object value, int scope);
310:
311: /**
312: * Specifies the time, in seconds, between client requests, before the
313: * portlet container invalidates this session. A negative time
314: * indicates the session should never timeout.
315: *
316: * @param interval An integer specifying the number
317: * of seconds
318: */
319:
320: public void setMaxInactiveInterval(int interval);
321:
322: /**
323: * Returns the portlet application context associated with this session.
324: *
325: * @return the portlet application context
326: */
327:
328: public PortletContext getPortletContext();
329:
330: }
|