001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/tool/tags/sakai_2-4-1/tool-api/api/src/java/org/sakaiproject/tool/api/ContextSession.java $
003: * $Id: ContextSession.java 7523 2006-04-09 13:03:23Z ggolden@umich.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2005, 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.tool.api;
021:
022: import java.util.Enumeration;
023:
024: /**
025: * <p>
026: * ContextSession models an end user's HttpSession for a context (as in ServletContext).
027: * </p>
028: */
029: public interface ContextSession {
030:
031: /**
032: * Remove and unbind all attributes in the session.
033: *
034: * @exception IllegalStateException
035: * if this method is called on an already invalidated session
036: */
037: void clearAttributes();
038:
039: /**
040: * Returns the object bound with the specified name in this session, or <code>null</code> if no object is bound under the name.
041: *
042: * @param name
043: * a string specifying the name of the object
044: * @return the object with the specified name
045: * @exception IllegalStateException
046: * if this method is called on an invalidated session
047: */
048: Object getAttribute(String name);
049:
050: /**
051: * Returns an <code>Enumeration</code> of <code>String</code> objects containing the names of all the objects bound to this session.
052: *
053: * @return an <code>Enumeration</code> of <code>String</code> objects specifying the names of all the objects bound to this session
054: * @exception IllegalStateException
055: * if this method is called on an invalidated session
056: */
057: Enumeration getAttributeNames();
058:
059: /**
060: * Returns the time when this session was created, measured in milliseconds since midnight January 1, 1970 GMT.
061: *
062: * @return a <code>long</code> specifying when this session was created, expressed in milliseconds since 1/1/1970 GMT
063: * @exception IllegalStateException
064: * if this method is called on an invalidated session
065: */
066: long getCreationTime();
067:
068: /**
069: * Returns a string containing the unique identifier assigned to this session.
070: *
071: * @return a string specifying the identifier assigned to this session
072: * @exception IllegalStateException
073: * if this method is called on an invalidated session
074: */
075: String getId();
076:
077: /**
078: * Returns the last time the client sent a request associated with this tool session, as the number of milliseconds since midnight January 1, 1970 GMT.
079: * <p>
080: * Actions that your application takes, such as getting or setting a value associated with the session, do not affect the access time.
081: *
082: * @return a <code>long</code> representing the last time the client sent a request associated with this session, expressed in milliseconds since 1/1/1970 GMT
083: * @exception IllegalStateException
084: * if this method is called on an invalidated session
085: */
086: long getLastAccessedTime();
087:
088: /**
089: * Returns a string containing the context identifier for this session.
090: *
091: * @return a string specifying the context identifier for this session.
092: * @exception IllegalStateException
093: * if this method is called on an invalidated session
094: */
095: String getContextId();
096:
097: /**
098: * Return the enterprise id of the user associated with this session.
099: *
100: * @return The enterprise id of the user associated with this session.
101: */
102: String getUserEid();
103:
104: /**
105: * Return the authenticated user id associated with this session.
106: *
107: * @return The authenticated user id associated with this session.
108: */
109: String getUserId();
110:
111: /**
112: * Removes the object bound with the specified name from this session. If the session does not have an object bound with the specified name, this method does nothing.
113: * <p>
114: * After this method executes, and if the object implements <code>SessionBindingListener</code>, Sakai calls <code>SessionBindingListener.valueUnbound</code>.
115: *
116: * @param name
117: * the name of the object to remove from this session
118: * @exception IllegalStateException
119: * if this method is called on an invalidated session
120: */
121: void removeAttribute(String name);
122:
123: /**
124: * Binds an object to this session, using the name specified. If an object of the same name is already bound to the session, the object is replaced.
125: * <p>
126: * After this method executes, and if the new object implements <code>SessionBindingListener</code>, Sakai calls <code>SessionBindingListener.valueBound</code>.
127: * <p>
128: * If an object was already bound to this session of this name that implements <code>SessionBindingListener</code>, its <code>SessionBindingListener.valueUnbound</code> method is called.
129: * <p>
130: * If the value passed in is null, this has the same effect as calling <code>removeAttribute()<code>.
131: *
132: * @param name the name to which the object is bound;
133: * cannot be null
134: *
135: * @param value the object to be bound
136: *
137: * @exception IllegalStateException if this method is called on an
138: * invalidated session
139: */
140: void setAttribute(String name, Object value);
141: }
|