001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/tool/tags/sakai_2-4-1/tool-api/api/src/java/org/sakaiproject/tool/api/ToolSession.java $
003: * $Id: ToolSession.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: * ToolSession models an end user's Tool placement specific usage session.
027: * </p>
028: *
029: * @author University of Michigan, Sakai Software Development Team
030: * @version $Revision: 7523 $
031: */
032: public interface ToolSession {
033: /**
034: * Remove and unbind all attributes in the session.
035: *
036: * @exception IllegalStateException
037: * if this method is called on an already invalidated session
038: */
039: void clearAttributes();
040:
041: /**
042: * Returns the object bound with the specified name in this session, or <code>null</code> if no object is bound under the name.
043: *
044: * @param name
045: * a string specifying the name of the object
046: * @return the object with the specified name
047: * @exception IllegalStateException
048: * if this method is called on an invalidated session
049: */
050: Object getAttribute(String name);
051:
052: /**
053: * Returns an <code>Enumeration</code> of <code>String</code> objects containing the names of all the objects bound to this session.
054: *
055: * @return an <code>Enumeration</code> of <code>String</code> objects specifying the names of all the objects bound to this session
056: * @exception IllegalStateException
057: * if this method is called on an invalidated session
058: */
059: Enumeration getAttributeNames();
060:
061: /**
062: * Returns the time when this session was created, measured in milliseconds since midnight January 1, 1970 GMT.
063: *
064: * @return a <code>long</code> specifying when this session was created, expressed in milliseconds since 1/1/1970 GMT
065: * @exception IllegalStateException
066: * if this method is called on an invalidated session
067: */
068: long getCreationTime();
069:
070: /**
071: * Returns a string containing the unique identifier assigned to this session.
072: *
073: * @return a string specifying the identifier assigned to this session
074: * @exception IllegalStateException
075: * if this method is called on an invalidated session
076: */
077: String getId();
078:
079: /**
080: * 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.
081: * <p>
082: * Actions that your application takes, such as getting or setting a value associated with the session, do not affect the access time.
083: *
084: * @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
085: * @exception IllegalStateException
086: * if this method is called on an invalidated session
087: */
088: long getLastAccessedTime();
089:
090: /**
091: * Returns a string containing the tool placement identifier for this session.
092: *
093: * @return a string specifying the tool placement identifier for this session.
094: * @exception IllegalStateException
095: * if this method is called on an invalidated session
096: */
097: String getPlacementId();
098:
099: /**
100: * Return the enterprise id of the user associated with this session.
101: *
102: * @return The enterprise id of the user associated with this session.
103: */
104: String getUserEid();
105:
106: /**
107: * Return the authenticated user id associated with this session.
108: *
109: * @return The authenticated user id associated with this session.
110: */
111: String getUserId();
112:
113: /**
114: * 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.
115: * <p>
116: * After this method executes, and if the object implements <code>SessionBindingListener</code>, Sakai calls <code>SessionBindingListener.valueUnbound</code>.
117: *
118: * @param name
119: * the name of the object to remove from this session
120: * @exception IllegalStateException
121: * if this method is called on an invalidated session
122: */
123: void removeAttribute(String name);
124:
125: /**
126: * 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.
127: * <p>
128: * After this method executes, and if the new object implements <code>SessionBindingListener</code>, Sakai calls <code>SessionBindingListener.valueBound</code>.
129: * <p>
130: * 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.
131: * <p>
132: * If the value passed in is null, this has the same effect as calling <code>removeAttribute()<code>.
133: *
134: * @param name the name to which the object is bound;
135: * cannot be null
136: *
137: * @param value the object to be bound
138: *
139: * @exception IllegalStateException if this method is called on an
140: * invalidated session
141: */
142: void setAttribute(String name, Object value);
143: }
|